aicoin-onchain

Run the script: run from the directory where SKILL.md is located node scripts/<file>.mjs <action>. The three engines (OpenClaw / Hermes / Claude Code) automatically load the skill in the container, just cd to the skill directory.

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.

⚠️ Routing priority (if the user asks about "on-chain large capital movements", go to hyperliquid + market first, not here)

This skill mainly serves DEX swap / wallet queries / on-chain transaction actions, it is not the first choice for "on-chain data exploration".

Correct routing when the user asks data-type questions:

User asks	Preferred skill	Reason
What large capital movements are there on-chain today	aicoin-hyperliquid + aicoin-market	HL itself is an on-chain perp DEX; whale_positions / whale_events / liquidations / OI are all real on-chain data, and free tickers + standard whale signals are all available
What are on-chain whales / smart money buying	aicoin-hyperliquid smart_find / whale_positions	Same as above, HL data is real and verifiable
Ethereum/Solana on-chain tokens trending	aicoin-onchain token.mjs trending	OKX Web3 endpoint, but requires a key — data exploration is not the preferred use case
How much does my wallet 0x... have / Uniswap quote / swap	aicoin-onchain	This is exactly this skill's main battlefield

Key attribution: This skill hasnothing to dowith the AiCoin paid membership, it calls the OKX Web3 DEX API. Butdo nottherefore treat it as the "on-chain data query entry point" — for any "today/recent/trend"-typedataquestion from the user, go to aicoin-hyperliquid (real on-chain DEX data) and aicoin-market (CEX proxy) first, then consider OKX Web3.

Do not mix the two data sources:

• aicoin-onchain (this skill) → DEX transaction actions + wallet, OKX_WEB3_API_KEY is applied forsigning swaps / quotes / checking wallets, not for pulling data
• aicoin-hyperliquid → on-chain perp DEX whale data, use the AiCoin Open Data API
• aicoin-market → CEX large orders / funding rates / K-line / long-short ratio, also use the AiCoin Open Data API

Free Tier Endpoints (as long as OKX_WEB3_API_KEY is configured, they can be used, free)

User asks	Use this
On-chain large capital movements / whale / whales / smart money / giant whale signals	market.mjs signal_list '{"chain":"ethereum"}'
On-chain hot tokens / hot tokens / trending	token.mjs trending '{}' or token.mjs hot_tokens '{}'
token price / K-line / holders	market.mjs price / market.mjs kline / token.mjs holders
Wallet balance / positions	portfolio.mjs total_value / portfolio.mjs all_balances
swap quote / gas	swap.mjs quote / gateway.mjs gas

When OKX_WEB3_API_KEY is not configured: the agent should prompt "first go to https://web3.okx.com/onchain-os/dev-portal to apply for OKX_WEB3_API_KEY for free and configure it in .env",do notsay "it requires payment". Configuring the key is free, a 5-minute operation.

Mandatory rule (violation = inaccurate): when OKX_WEB3_API_KEY is not configured, even if you have already used other skills such as aicoin-market to give the user a fallback answer, you must add a sentence at the end of the answer:

"💡 The OKX Web3 API key is free, apply for it in 5 minutes at https://web3.okx.com/onchain-os/dev-portal and configure it in .env, then you can see exclusive on-chain data such as smart money/giant whales/on-chain hot tokens."

This sentence is not optional polish, but a mandatory onboarding guideline. Not proactively guiding = the user will never know there is deeper data that can be unlocked = the skill's value is discounted.

Quick Reference

Task	Command
Search token	node scripts/token.mjs search '{"query":"PEPE"}'
Token price	node scripts/market.mjs price '{"address":"0xeee...","chain":"ethereum"}'
K-line chart	node scripts/market.mjs kline '{"address":"0xeee...","chain":"ethereum","bar":"1H","limit":100}'
Trending tokens	node scripts/token.mjs trending '{}'
Hot tokens	node scripts/token.mjs hot_tokens '{}'
Swap quote	node scripts/swap.mjs quote '{"from":"0xeee...","to":"0xdac...","amount":"1000000000000000000","chain":"ethereum"}'
Wallet balance	node scripts/portfolio.mjs total_value '{"address":"0x...","chains":"ethereum"}'
All token holdings	node scripts/portfolio.mjs all_balances '{"address":"0x...","chains":"ethereum,solana"}'
Gas price	node scripts/gateway.mjs gas '{"chain":"ethereum"}'
Auto swap	node scripts/trade.mjs swap '{"from":"0xeee...","to":"0xdac...","amount":"1000000000000000000","chain":"base"}'

Skill Routing

• CEX trading (buy/sell on Binance, OKX) → use aicoin-trading
• CEX market data (funding rates, OI, liquidation maps) → use aicoin-market
• Freqtrade strategies → use aicoin-freqtrade
• Hyperliquid whales → use aicoin-hyperliquid
• On-chain DEX operations → use this skill (aicoin-onchain)

Scripts

token.mjs — Token Discovery

Action	Params	Description
search	query, chains?	Search tokens by name/symbol/address
info	address, chain?	Token metadata (name, symbol, decimals, logo)
trending	chains?, sort_by?, time_frame?	Trending token rankings
price_info	address, chain?	Price, market cap, liquidity, 24h change
hot_tokens	chains?, ranking_type?	Hot tokens by trending score
holders	address, chain?	Token holder distribution
liquidity	address, chain?	Top liquidity pools
advanced_info	address, chain?	Risk level, creator, dev stats

market.mjs — Market Data

Action	Params	Description
price	address, chain?	Current token price
prices	tokens, chain?	Batch price query (comma-separated chain:address)
kline	address, chain?, bar?, limit?	K-line / candlestick data
index	address, chain?	Aggregated index price
signal_list	chain, wallet_type?, token_address?	Smart money / whale / KOL signals
signal_chains	(none)	Supported chains for signals

swap.mjs — DEX Swap

Action	Params	Description
quote	from, to, amount, chain, swap_mode?	Get swap quote (read-only)
swap	from, to, amount, chain, wallet, slippage?	Get swap tx data (unsigned)
approve	token, amount, chain	Get ERC-20 approval tx data
chains	(none)	Supported chains for DEX aggregator
liquidity	chain	Available liquidity sources on a chain

portfolio.mjs — Wallet Portfolio

Action	Params	Description
total_value	address, chains	Total portfolio value in USD
all_balances	address, chains	All token balances
token_balances	address, tokens	Specific token balances
chains	(none)	Supported chains for balance queries

gateway.mjs — Transaction Gateway

Action	Params	Description
gas	chain	Current gas prices
gas_limit	from, to, chain, amount?, data?	Estimate gas limit
simulate	from, to, data, chain, amount?	Simulate transaction (dry-run)
broadcast	signed_tx, address, chain	Broadcast signed transaction
orders	address, chain, order_id?	Track broadcast order status
chains	(none)	Supported chains for gateway

trade.mjs — Full Auto Trade (optional, requires private key)

Action	Params	Description
swap	from, to, amount, chain, slippage?	Full auto: quote → approve → sign → broadcast
wallet_info	(none)	Show wallet address derived from private key

Setup: User adds WALLET_PRIVATE_KEY=0x... to .env. Private key stays local, never sent to any server.

Safety: Auto-blocks honeypot tokens and trades with >10% price impact.

EVM only — Solana auto-trade not yet supported.

Chain Names

The scripts accept human-readable chain names:

Chain	Name	Also Accepts
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

Native Token Addresses

Chain	Address
EVM (ETH, BSC, Polygon, etc.)	0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
Solana	11111111111111111111111111111111

WARNING: Solana native SOL address is 11111111111111111111111111111111 (system program). Do NOT use So11111111111111111111111111111111111111112 (wSOL).

Swap Workflow

EVM Swap (quote → approve → swap)

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 Swap (simpler, no approve step)

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

Security Rules

1. Never execute swap without user confirmation. Show: token names, amounts, gas estimate, price impact, honeypot status.
2. Skip approve for native tokens. Never call swap approve for 0xeee... (EVM) or 111...1 (Solana).
3. Honeypot warning. If isHoneyPot = true, warn prominently and ask user to confirm.
4. Price impact >5%: warn user. >10%: strongly warn, suggest reducing amount.
5. Tax tokens: if taxRate > 0, show to user before confirmation.

Amount Rules

• Script params use minimal units (wei/lamports): 1 ETH = "1000000000000000000", 1 USDC = "1000000"
• Display to user in UI units: 1.5 ETH, 3200 USDC
• Gas fees in Gwei (EVM) or USD

API Key Setup

Requires OKX Web3 API credentials. Free at OKX Developer Portal.

CoinClaw users are added in the web UI EnvSection; local users are written to .env:

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

.env Auto-load locations:

• Local host: ~/.coinos/.env(coinos folder, recommended; it can be read no matter which directory it is run from), and the current directory is also recognized .env + old ~/.openclaw/.env
• CoinClaw container: /workspace/.env(configured in the web UI EnvSection)

Security notice: OKX Web3 API Key is for reading market data and generating unsigned swap calldata. It cannot access your wallet funds or sign transactions. All signing happens locally.