爱迪克斯
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 较高消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows · WSL · Docker
- 运行环境要求
- Node.js · Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
## Overview
AIDEX is a high-performance DEX aggregator on Ethereum. This skill gives your OpenClaw agent the ability to swap tokens, check exchange rates, monitor balances, and verify transaction results.
AIDEX provides tools, not decisions. You decide when and what to trade. AIDEX is your hands — fast, transparent, reliable. Every operation is a visible on-chain Ethereum transaction that you can verify on Etherscan. Nothing is hidden, nothing is obscured.
AIDEX doesn't pretend to be smarter than you. It doesn't make decisions on your behalf. It does exactly what you ask — honestly, quickly, and verifiably. If you want to experiment with automated trading, AIDEX gives you the simplest, most transparent foundation to build on.
Your funds stay in your wallet at all times. Unlike centralized exchange integrations where your money sits on someone else's platform, AIDEX works with decentralized liquidity pools. You remain in full control.
## Source code
Open source on GitHub: [AIDEX-DeFi/skills](https://github.com/AIDEX-DeFi/skills). Issues and pull requests welcome.
## Why AIDEX
- **Simplicity** — Simple, clear scripts. Clear inputs, clear outputs. The agent calls them, you see the results. That's it.
- **Transparency** — Every swap is a standard Ethereum transaction. You get a transaction hash. You can check it on Etherscan. What you asked for is what gets executed.
- **Security** — Your private key never leaves your machine. The API only receives already-signed transactions. Even if our servers were compromised, no one could alter your transaction — it's cryptographically signed by you. See the [Security Model](#security-model) section below.
- **Speed** — Lightning-fast execution layer with minimal latency. Transactions are built and sent in milliseconds.
- **Best rates** — Wide liquidity pool coverage finds exchange routes that competitors miss, giving you better rates.
## Dependencies
This skill requires Node.js packages listed in `package.json` in the skill's root folder:
- **ethers** — Ethereum library for client-side transaction signing. This is what keeps your private key safe — transactions are signed locally, never sent to the API.
- **@napi-rs/keyring** *(optional)* — Native access to the operating system's credential manager (Windows Credential Manager, macOS Keychain, Linux Secret Service). Allows storing the private key securely instead of an environment variable.
**Run `npm install` in the skill's root folder after the initial install and after each skill update.** Skill updates may pin new dependency versions. The packages are installed locally into the skill's own `node_modules/` folder — this is NOT a modification to the user's system environment. It is a standard, reversible operation (the folder can be deleted at any time).
If your operational constraints prevent you from running `npm install` automatically, ask the user for permission and let them decide.
**Do not report the skill as broken if dependencies are missing — install them.**
## Security Model
### Client-side transaction signing
All transaction signing happens locally on your machine using ethers.js. The AIDEX API **never receives, requests, or has access to your private key**.
Here's what happens during a swap:
1. Your agent calls the AIDEX API with swap parameters (which tokens, how much)
2. The API returns a **complete unsigned transaction** (destination address, call data, gas parameters)
3. The `swap.js` script signs this transaction using your private key via `ethers.Wallet.signTransaction()`
4. Finally, the signed transaction is sent back to the API for fast broadcasting to the Ethereum network
### What the API cannot do
Your funds are protected because every transaction must be reviewed and signed directly by your wallet. AIDEX cannot modify transaction amounts, tokens, or recipients, and cannot initiate unauthorized transactions.
### What AIDEX API does NOT do
- Does not store private keys
- Does not manage or custody your funds
- Does not deduct fees from your wallet
- Does not have any access to your assets beyond what you explicitly sign
### Private key storage — a reasonable trade-off
Your private key can be stored in the `AIDEX_PRIVATE_KEY` environment variable or in the operating system's credential manager (system keyring). Both approaches keep the key local to your machine. See the [Setup](#setup) section for configuration details.
This is a deliberate and reasonable trade-off between autonomy and security: if the agent cannot sign transactions, it cannot trade autonomously.
## Setup
The AIDEX skill works out of the box for read-only operations: searching tokens, checking exchange rates, and viewing balances. No configuration needed.
To execute swaps, configure your private key using one of the options below.
### What is a Private Key?
A private key is 64 hexadecimal characters (`0-9`, `a-f`), optionally prefixed with `0x` — 64 or 66 characters total. It is the sole credential that authorizes transactions from your Ethereum wallet. Unlike a password, a private key cannot be reset or recovered — if it is lost or compromised, access to the wallet's funds is permanently lost or stolen.
If you don't have a wallet yet, the easiest way to get started is with [MetaMask](https://metamask.io/):
1. Install the MetaMask browser extension and create a new wallet
2. Open MetaMask, click the account selector at the top of the screen
3. Tap the account menu (⋮) next to the account name, then select **Account details**
4. Select **Private keys**, enter your MetaMask password, and copy the revealed key
Use this key in one of the configuration options below.
### Option A: Environment variable (via OpenClaw)
**Simple — for testing only.** The private key is passed as a command-line argument and may end up in shell history, process list, and audit logs:
```bash
openclaw config set skills.entries.aidex.env.AIDEX_PRIVATE_KEY "0xYourPrivateKeyHere"
```
**Secure — requires bash (on Windows use WSL).** The key is read interactively into a shell variable and piped via stdin, never appearing in argv:
```bash
read -rsp "AIDEX private key: " k; echo; printf '{"skills":{"entries":{"aidex":{"env":{"AIDEX_PRIVATE_KEY":"%s"}}}}}' "$k" | openclaw config patch --stdin; unset k
```
After changing the config, restart the gateway so the new value takes effect:
```bash
openclaw gateway restart
```
### Option B: System keyring (desktop only)
> **Not available in Docker, WSL, CI, or headless Linux.** The system keyring requires a desktop session. If you are running in a containerized or headless environment, use Option A above.
Store your private key in the operating system's credential manager. The key is encrypted at rest and protected by your OS user account, keeping it out of configuration files and environment variable logs.
**Windows** (Credential Manager):
```cmd
cmdkey /generic:AIDEX_PRIVATE_KEY.aidex /user:AIDEX_PRIVATE_KEY
```
**macOS** (Keychain):
```bash
security add-generic-password -s aidex -a AIDEX_PRIVATE_KEY -U -w
```
**Linux** (Secret Service — GNOME Keyring, KWallet):
```bash
secret-tool store --label="AIDEX Private Key" service aidex username AIDEX_PRIVATE_KEY target default
```
In all three commands above, you will be prompted to enter the private key interactively.
**Headless and containerized environments (Docker, WSL, CI):**
The system keyring is not accessible from containers or headless environments — it requires a desktop session with D-Bus. In these environments, use Option A (environment variable). For production server deployments, proper firewall configuration is essential to restrict access to the machine running the agent.
If both an environment variable and a keyring entry are present, the environment variable takes priority.
## Token identification
In all scripts that accept token parameters (`--token-in`, `--token-out`, `--tokens`), you can specify tokens by **address** or by **symbol**:
- By address: `--token-in 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
- By symbol: `--token-in USDC`
If a symbol is ambiguous (matches multiple tokens), the API will return an error listing all matches so you can specify the address instead.
## Scripts
> **Note:** You don't need to read this section to use AIDEX for trading. Your OpenClaw agent handles the scripts automatically. This section is for developers or anyone who wants to understand how the system works under the hood.
All scripts output JSON to stdout. Every response contains a `success` field (`true` or `false`). On failure, an `error` field explains what went wrong.
### account.js — Get wallet address *(requires private key)*
Derives your wallet address from the private key. Does not call the API.
```bash
node {baseDir}/scripts/account.js
```
Output: `{"success": true, "address": "0x..."}`
### tokens.js — Search tokens
Search for tokens by symbol, name, or address.
```bash
node {baseDir}/scripts/tokens.js --term USDC
```
Without `--term`, returns the full token list.
Output: `{"success": true, "tokens": [{"address": "0x...", "symbol": "USDC", "decimals": 6, "name": "USD Coin", "imageUrl": "..."}]}`
### rate.js — Check exchange rate
Get the current exchange rate for a token pair. Read-only, does not execute anything. Tokens can be specified by address or symbol.
```bash
node {baseDir}/scripts/rate.js --token-in ETH --token-out USDC --amount-in 0.5
```
Output: `{"success": true, "rate": "3125.50", "amountOut": "1562.75", "estimatedGasPriceUsd": 2.34}`
### balance.js — Check token balances
Get balances for up to 9 tokens at once. Use `ETH` or the zero address (`0x0000000000000000000000000000000000000000`) for native ETH balance. Tokens can be specified by address or symbol.
> **Note:** `--address` is required, but you often don't need to ask the user for it. Run `account.js` first — if the private key is configured, it returns the wallet address. Only ask the user for their address if `account.js` returns an error (private key not configured).
```bash
node {baseDir}/scripts/balance.js --address 0xYourWallet --tokens ETH,USDC
```
Output: `{"success": true, "balances": [{"address": "0x000...0", "symbol": "ETH", "balance": "1.5", "allowance": null}, {"address": "0xA0b...eB48", "symbol": "USDC", "balance": "3250.00", "allowance": "1000.0"}]}`
The `allowance` field shows how much the AIDEX router is approved to spend on behalf of the wallet (relevant for ERC-20 tokens). For native ETH, `allowance` is `null`.
### swap.js — Execute a swap *(requires private key)*
Builds a chain of transactions (approve if needed + swap) via API, signs them locally on your machine, and broadcasts them. Full cycle in one call. The API handles approve automatically — the script doesn't need to know about it. Tokens can be specified by address or symbol.
```bash
node {baseDir}/scripts/swap.js --token-in ETH --token-out USDC --amount-in 0.5 --slippage 0.5 --deadline-minutes 20
```
- `--slippage` — Maximum acceptable slippage in percent (default: 0.5)
- `--deadline-minutes` — Transaction deadline in minutes from now (default: 20)
Output: `{"success": true, "transactionHashes": ["0x..."], "fromAddress": "0x...", "amountOut": "1562.75", "estimatedGasPriceUsd": 2.34}`
Note: `transactionHashes` is an array — it may contain 1-3 hashes (approve transactions + swap). Pass all of them to swap-status.js.
### swap-status.js — Check swap operation status
Verify the result of a swap operation (including approve steps). Accepts 1-3 transaction hashes.
```bash
node {baseDir}/scripts/swap-status.js --hashes 0xApproveHash,0xSwapHash
```
Output:
```json
{
"success": true,
"status": "completed",
"steps": [
{"type": "approve", "status": "confirmed", "transactionHash": "0x..."},
{"type": "swap", "status": "confirmed", "transactionHash": "0x...", "amountIn": "0.5", "tokenIn": "ETH", "amountOut": "1562.75", "tokenOut": "USDC"}
]
}
```
High-level status: `pending` (waiting for confirmation), `completed` (all steps confirmed), `failed` (a step reverted).
## Workflow Patterns
### Check exchange rate
```
1. rate.js --token-in ETH --token-out USDC --amount-in 1
```
### Execute a swap
```
1. account.js → get wallet address
2. rate.js --token-in ETH --token-out USDC --amount-in 0.5 → show rate and gas cost to user
3. [Ask user for confirmation]
4. balance.js --address <wallet> --tokens ETH,USDC → show balances and allowance
5. swap.js --token-in ETH --token-out USDC --amount-in 0.5 → execute (approve + swap if needed)
6. swap-status.js --hashes <hash1>,<hash2> → verify result
7. balance.js --address <wallet> --tokens ETH,USDC → show balances after
```
### Price monitoring with auto-swap (via OpenClaw cron/heartbeat)
```
1. rate.js --token-in ETH --token-out USDC --amount-in 0.5 → check current rate
2. If target rate reached:
a. swap.js --token-in ETH --token-out USDC --amount-in 0.5 → execute swap
b. swap-status.js --hashes <hashes> → verify result
c. balance.js ... → show final balances
3. If not reached: wait for next cron tick
```
When using cron-based monitoring and the API returns a temporary error ("AIDEX is temporarily unavailable" or network error), simply skip this iteration and retry on the next tick. Do not treat temporary errors as final failures.
## Agent Rules
1. **Always show rate and gas cost** before executing a swap. The user must see what they're getting.
2. **Ask for explicit confirmation** before executing a swap — unless the user explicitly set up automatic execution (e.g., "swap every time the price drops below 2800"). Confirmation can be one-time or for a series, but the agent never invents retries on its own.
3. **Display amounts in human-readable format** (e.g., "0.5 ETH", "1,562.75 USDC"), not raw BigInt values.
4. **Always show transaction hashes** after a swap so the user can track them on Etherscan.
5. **Handle error responses gracefully**:
- `Route not found` — Let the user know AIDEX could not find a route for this pair, and suggest trying a different pair or amount.
- `AIDEX is temporarily unavailable` — Let the user know AIDEX is not available right now and suggest trying again in a few minutes.
- The error says the skill is outdated (e.g., `Skill ... is outdated` or `Outdated skill version`) — Ask the user to run `openclaw skills update aidex` in their terminal.
- `Request rejected` — Most likely the request was formed incorrectly — re-check the arguments. If they look correct, ask the user to update the skill: `openclaw skills update aidex`.
- Network errors — Same as above, suggest retrying later.
- Invalid token — Suggest searching for the token by name or symbol.
6. **After a swap, always call swap-status.js** to verify the actual result and show it to the user.
7. **Private key not configured?** If no private key is available, present **all** configuration options: environment variable (via `openclaw config set`) **and** system keyring. Do not default to a single option — let the user choose.
8. **NEVER loop or auto-retry on errors.** If any transaction reverts or the API returns an error, stop the current operation and report to the user. Do not automatically retry. If the user wants to try again, they will say so.
9. **NEVER access the private key directly.** Do not read openclaw.json, .env files, or any other configuration files to extract the private key. Do not pass the private key as a command-line argument — command-line arguments are visible to all processes on the system. Passing the key this way is equivalent to leaking it to an attacker. The key is resolved from the AIDEX_PRIVATE_KEY environment variable or the system keyring. If neither source provides a valid key, inform the user and stop. No workarounds.
10. **While a transaction is mining**, you can show the user a link to track it: `https://etherscan.io/tx/{transactionHash}`. This applies to all transactions (swap, approve).
11. **Detect the user's environment.** When helping with private key setup, adapt your suggestions to the user's environment. If the user is running in a containerized or headless Linux environment (Docker, WSL, CI), lead with the environment variable approach (Option A) — do not mention the system keyring unless the user explicitly asks about alternatives. If asked, explain that the system keyring is available for desktop operating systems (Windows, macOS, Linux with a graphical session) but is not accessible from containers or headless environments. For desktop users, present all keyring options but highlight the one matching their OS first.
12. **Never ask the user about private key configuration proactively.** Do not ask "is your private key configured?" or offer to help with setup when the user first interacts with the skill. The user may not even know what a private key is. Simply run the requested operation — if the key is needed and not configured, the script will return a clear error, and only then should you explain what happened and how to set it up. For read-only operations (rate, tokens, balances), the key is not needed at all — do not mention it.
13. **Do not assume the private key is missing — check by running the script.** When the user asks for their balance, wallet address, or any operation that may require a private key, do not refuse preemptively. Run `account.js` — if the key is configured, you'll get the wallet address. If not, the script will return a clear error explaining what to set up. This is a read-only operation with no cost and no risk. Never tell the user "I can't do this" without actually trying first.
14. **When asking for a wallet address, warn the user not to confuse it with a private key.** Both start with `0x`, but an address is 42 characters and is safe to share, while a private key is 66 characters and must be kept secret. If the user provides a 66-character string where an address is expected, **do not use it** — warn them immediately that this looks like a private key and should never be shared. Example: "Your wallet address (42 characters, starts with 0x — this is **not** your private key, which is longer and must be kept secret)."
15. **Never modify the skill's source code.** The scripts in `{baseDir}/scripts/` and `package.json` are canonical — do not edit, patch, or "fix" them under any circumstances, even temporarily. If a script returns an unexpected error and you suspect a bug in the skill, you are almost certainly wrong: re-check your own inputs and call sequence carefully, read the script specifications in this SKILL.md word-for-word, and use the exact command names and argument names documented there — never invent your own syntax.
## Key Constants
- Native ETH address: `0x0000000000000000000000000000000000000000`
- WETH address: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`
- Network: Ethereum mainnet (chainId: 1)
- Common tokens: ETH (18 decimals), USDC (6), USDT (6), DAI (18), WBTC (8)
---
> Source: [AIDEX-DeFi/skills](https://github.com/AIDEX-DeFi/skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-23 -->
章节与文件索引
按说明文件中的顺序排列。
概述
源代码
为什么选择艾德克斯
依赖关系
客户端交易签名
文件/命令 -> package.json · npm install · node_modules/ · swap.js · ethers.Wallet.signTransaction() · AIDEX_PRIVATE_KEY · 0-9 · a-f
内容校验值 -> 8b5165e528f7
当前原文的自动摘译,尚未人工审校。
概述
AIDEX 是以太坊上的高性能 DEX 聚合器。这项技能使您的 OpenClaw 代理能够交换代币、检查汇率、监控余额和验证交易结果。 AIDEX 提供工具,而不是决策。您决定何时交易以及交易什么。 AIDEX 是您的双手——快速、透明、可靠。每个操作都是可见的链上以太坊交易,您可以在 Etherscan 上验证。没有什么是隐藏的,没有什么是模糊的。
源代码
GitHub 上开源:AIDEX-DeFi/skills。欢迎提出问题和请求。
为什么选择艾德克斯
简单性——简单、清晰的脚本。清晰的输入,清晰的输出。代理打电话给他们,您会看到结果。就是这样。透明度——每次交换都是标准的以太坊交易。你得到一个交易哈希。您可以在 Etherscan 上检查。你所要求的就是被执行的。安全性——您的私钥永远不会离开您的机器。 API 仅接收已签名的交易。即使我们的服务器遭到破坏,也没有人可以更改您的交易——它是由您以加密方式签名的。请参阅下面的安全模型部分。
依赖关系
此技能需要技能根文件夹中的
package.json中列出的 Node.js 包:ethers — 用于客户端交易签名的以太坊库。这就是保证您的私钥安全的原因——交易在本地签名,永远不会发送到 API。 @napi-rs/keyring (可选) — 对操作系统凭据管理器(Windows 凭据管理器、macOS 钥匙串、Linux Secret Service)的本机访问。允许安全地存储私钥而不是环境变量。客户端交易签名
所有交易签名都使用 ethers.js 在您的计算机上本地进行。 AIDEX API 永远不会接收、请求或访问您的私钥。以下是交换期间发生的情况: 您的代理使用交换参数(哪些代币、多少)调用 AIDEX API API 返回完整的未签名交易(目标地址、调用数据、gas 参数)
swap.js脚本使用您的私钥通过ethers.Wallet.signTransaction()签署此交易