aicoin-onchain

运行脚本: 从 SKILL.md 所在目录运行 node scripts/<file>.mjs <action>. 三引擎(OpenClaw / Hermes / Claude Code)容器自动加载 skill, 直接 cd 到 skill 目录即可.

AiCoin Onchain

On-chain DEX toolkit powered by OKX Web3 DEX API. Token discovery, swap execution, wallet portfolio, gas estimation, and transaction broadcasting across 20+ blockchains.

Version: 1.0.0

Critical Rules

1. NEVER fabricate data. Always run scripts. If data is empty or errors, say so — do NOT invent prices or balances.
2. NEVER use curl, web_fetch, web_search for on-chain data. Always use these scripts.
3. NEVER run env or printenv — leaks API secrets.
4. Scripts auto-load .env — never pass credentials inline.
5. Reply in user's language. Chinese input = Chinese response.
6. User confirmation required before swap execution. Always show quote details (amount, gas, price impact, honeypot status) and get explicit user approval before calling swap swap.
7. This skill does NOT sign transactions. It returns unsigned tx data. User must sign locally with their own wallet/key.

⚠️ 路由优先级 (用户问"链上大资金动向"先去 hyperliquid + market,不是这里)

本 skill 主要服务 DEX swap / 钱包查询 / 链上交易动作, 不是"链上数据探查"的首选.

用户问数据类问题时正确路由:

用户问	优先 skill	理由
今天链上有什么大资金动向	aicoin-hyperliquid + aicoin-market	HL 本身是链上 perp DEX, whale_positions / whale_events / liquidations / OI 都是真链上数据,免费 tickers + 标准版 whale 信号都能拿
链上鲸鱼/聪明钱在买啥	aicoin-hyperliquid smart_find / whale_positions	同上,HL 数据真实可查
Ethereum/Solana 链上代币热门	aicoin-onchain token.mjs trending	OKX Web3 endpoint, 但需要 key — 数据探查不是首选用法
我钱包 0x... 有多少 / Uniswap 报价 / swap	aicoin-onchain	这才是本 skill 主战场

关键归属: 本 skill 跟 AiCoin 付费会员没关系, 调用的是 OKX Web3 DEX API. 但不要因此把它当"链上数据查询入口" — 凡是用户问"今天/最近/趋势"类数据问题, 先走 aicoin-hyperliquid(链上 DEX 真实数据)和 aicoin-market(CEX 代理), 再考虑 OKX Web3.

两个数据源不要混:

• aicoin-onchain (本 skill) → DEX 交易动作 + 钱包, OKX_WEB3_API_KEY 是为了签名 swap / 报价 / 查钱包而申请, 不是为了拉数据
• aicoin-hyperliquid → 链上 perp DEX whale 数据, 用 AiCoin Open Data API
• aicoin-market → CEX 大单 / 资金费率 / K线 / 多空比, 也用 AiCoin Open Data API

Free Tier Endpoints (OKX_WEB3_API_KEY 配了就能用,免费)

用户问	用这个
链上大资金动向 / whale / 鲸鱼 / 聪明钱 / 巨鲸信号	market.mjs signal_list '{"chain":"ethereum"}'
链上热门币 / hot tokens / trending	token.mjs trending '{}' 或 token.mjs hot_tokens '{}'
token 价格 / K 线 / 持币人	market.mjs price / market.mjs kline / token.mjs holders
钱包余额 / 持仓	portfolio.mjs total_value / portfolio.mjs all_balances
swap 报价 / gas	swap.mjs quote / gateway.mjs gas

没配 OKX_WEB3_API_KEY 时:agent 应该提示"先到 https://web3.okx.com/onchain-os/dev-portal 免费申请 OKX_WEB3_API_KEY 配到 .env",不要说"需要付费". 配 key 是免费的、5 分钟操作.

强制规则 (违反 = inaccurate): 没配 OKX_WEB3_API_KEY 时, 即使你已经用 aicoin-market 等其他 skill 兜底回答了用户问题, 回答末尾必须加一句:

"💡 OKX Web3 API key 是免费的, 5 分钟在 https://web3.okx.com/onchain-os/dev-portal 申请配到 .env, 之后能看到聪明钱/巨鲸/链上代币热门等独家链上数据."

这一句不是可选的 polish, 而是必须的 onboarding 指引. 没主动引导 = 用户永远不知道还有更深的数据可以解锁 = skill 价值打折.

快速参考

任务	命令
搜索代币	node scripts/token.mjs search '{"query":"PEPE"}'
代币价格	node scripts/market.mjs price '{"address":"0xeee...","chain":"ethereum"}'
K 线图	node scripts/market.mjs kline '{"address":"0xeee...","chain":"ethereum","bar":"1H","limit":100}'
热门代币	node scripts/token.mjs trending '{}'
热度代币	node scripts/token.mjs hot_tokens '{}'
兑换报价	node scripts/swap.mjs quote '{"from":"0xeee...","to":"0xdac...","amount":"1000000000000000000","chain":"ethereum"}'
钱包余额	node scripts/portfolio.mjs total_value '{"address":"0x...","chains":"ethereum"}'
所有代币持仓	node scripts/portfolio.mjs all_balances '{"address":"0x...","chains":"ethereum,solana"}'
Gas 价格	node scripts/gateway.mjs gas '{"chain":"ethereum"}'
自动兑换	node scripts/trade.mjs swap '{"from":"0xeee...","to":"0xdac...","amount":"1000000000000000000","chain":"base"}'

技能路由

• CEX 交易（在 Binance、OKX 上买入/卖出）→ 使用 aicoin-trading
• CEX 市场数据（资金费率、OI、清算图）→ 使用 aicoin-market
• Freqtrade 策略 → 使用 aicoin-freqtrade
• Hyperliquid 巨鲸 → 使用 aicoin-hyperliquid
• 链上 DEX 操作 → 使用此技能（aicoin-onchain）

脚本

token.mjs — 代币发现

操作	参数	描述
search	query, chains?	按名称/符号/地址搜索代币
info	address, chain?	代币元数据（名称、符号、精度、徽标）
trending	chains?, sort_by?, time_frame?	热门代币排行榜
price_info	address, chain?	价格、市值、流动性、24 小时涨跌幅
hot_tokens	chains?, ranking_type?	按热度评分排列的热门代币
holders	address, chain?	代币持有者分布
liquidity	address, chain?	顶级流动性池
advanced_info	address, chain?	风险等级、创建者、开发者统计数据

market.mjs — 市场数据

操作	参数	描述
price	address, chain?	当前代币价格
prices	tokens, chain?	批量价格查询（以逗号分隔的 chain:address）
kline	address, chain?, bar?, limit?	K 线/蜡烛图数据
index	address, chain?	聚合指数价格
signal_list	chain, wallet_type?, token_address?	聪明钱/巨鲸/KOL 信号
signal_chains	(none)	支持信号查询的链

swap.mjs — DEX 兑换

操作	参数	描述
quote	from, to, amount, chain, swap_mode?	获取兑换报价（只读）
swap	from, to, amount, chain, wallet, slippage?	获取兑换交易数据（未签名）
approve	token, amount, chain	获取 ERC-20 授权交易数据
chains	(none)	DEX 聚合器支持的链
liquidity	chain	某条链上的可用流动性来源

portfolio.mjs — 钱包投资组合

操作	参数	描述
total_value	address, chains	投资组合总价值（美元）
all_balances	address, chains	所有代币余额
token_balances	address, tokens	指定代币余额
chains	(none)	余额查询支持的链

gateway.mjs — 交易网关

操作	参数	说明
gas	chain	当前 Gas 价格
gas_limit	from, to, chain, amount?, data?	估算 Gas 上限
simulate	from, to, data, chain, amount?	模拟交易（试运行）
broadcast	signed_tx, address, chain	广播已签名交易
orders	address, chain, order_id?	跟踪已广播订单状态
chains	(none)	网关支持的链

trade.mjs — 全自动交易（可选，需要私钥）

操作	参数	说明
swap	from, to, amount, chain, slippage?	全自动：报价 → 授权 → 签名 → 广播
wallet_info	(none)	显示由私钥派生的钱包地址

设置：用户将 WALLET_PRIVATE_KEY=0x... 添加到 .env。私钥保留在本地，不会发送到任何服务端。

安全性：自动拦截蜜罐代币和价格影响超过 10% 的交易。

仅支持 EVM — 暂不支持 Solana 自动交易。

链名称

脚本接受易读的链名称：

链	名称	也接受
Ethereum	ethereum	eth
Solana	solana	sol
Base	base
BSC	bsc	bnb
Arbitrum	arbitrum	arb
Polygon	polygon	matic
XLayer	xlayer	okb
Avalanche	avalanche	avax
Optimism	optimism	op

原生代币地址

链	地址
EVM（ETH、BSC、Polygon 等）	0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
Solana	11111111111111111111111111111111

警告：Solana 原生 SOL 地址为 11111111111111111111111111111111（系统程序）。不要使用 So11111111111111111111111111111111111111112（wSOL）。

兑换工作流

EVM 兑换（报价 → 授权 → 兑换）

1. token.mjs search    → find token contract address
2. swap.mjs quote      → get price estimate, check honeypot/tax
3. swap.mjs approve    → get ERC-20 approval tx data (skip for native tokens)
4. User signs approval → broadcast via gateway.mjs
5. swap.mjs swap       → get swap tx data
6. User signs swap     → broadcast via gateway.mjs
7. gateway.mjs orders  → track transaction status

Solana 兑换（更简单，无需授权步骤）

1. token.mjs search    → find token address
2. swap.mjs quote      → get quote
3. swap.mjs swap       → get tx data
4. User signs          → broadcast via gateway.mjs

安全规则

1. 未经用户确认，绝不执行兑换。 显示：代币名称、数量、Gas 估算、价格影响、蜜罐状态。
2. 原生代币跳过授权。 绝不要对 0xeee...（EVM）或 111...1（Solana）调用 swap approve。
3. 蜜罐警告。 如果 isHoneyPot = true，醒目提示并询问用户是否确认。
4. 价格影响 >5%：警告用户。>10%：强烈警告，建议减少数量。
5. 税费代币：如果 taxRate > 0，在用户确认前告知用户。

数量规则

• 脚本参数使用最小单位（wei/lamports）：1 ETH = "1000000000000000000"，1 USDC = "1000000"
• 向用户显示时使用 UI 单位：1.5 ETH、3200 USDC
• Gas 费用以 Gwei（EVM）或 USD 为单位

API 密钥设置

需要 OKX Web3 API 凭据。可在 OKX Developer Portal 免费获取。

CoinClaw 用户在 Web UI 的 EnvSection 中添加；本地用户写入 .env：

OKX_WEB3_API_KEY=your-api-key
OKX_WEB3_SECRET_KEY=your-secret-key
OKX_WEB3_PASSPHRASE=your-passphrase

.env 自动加载位置：

• 本地 host：~/.coinos/.env（coinos 文件夹，推荐；无论从哪个目录运行都能读取），也会读取当前目录的 .env 和旧路径 ~/.openclaw/.env
• CoinClaw 容器：/workspace/.env（通过 Web UI 的 EnvSection 配置）

安全提示：OKX Web3 API Key 用于读取市场数据和生成未签名的兑换 calldata。它无法访问你的钱包资金或签署交易。所有签名均在本地完成。