OpenTrade DEX Aggregator CLI

5 commands for multi-chain swap aggregation — quote, approve, and execute.

Pre-flight Checks

Every time before running any opentrade command, always follow these steps in order. Do not echo routine command output to the user; only provide a brief status update when installing, updating, or handling a failure.

Confirm installed: Run which opentrade . If not found, install it:

curl -sSL https://raw.githubusercontent.com/6551Team/openskills/main/skills/opentrade/install.sh | sh

If the install script fails, ask the user to install manually following the instructions at: https://github.com/6551Team/openskills

Check for updates: Read ~/.opentrade/last_check and compare it with the current timestamp:

cached_ts=$(cat ~/.opentrade/last_check 2>/dev/null || true) now=$(date +%s)

• If cached_ts is non-empty and (now - cached_ts) < 43200 (12 hours), skip the update and proceed.

• Otherwise (file missing or older than 12 hours), run the installer to check for updates: curl -sSL https://raw.githubusercontent.com/6551Team/openskills/main/skills/opentrade/install.sh | sh

If a newer version is installed, tell the user and suggest updating their opentrade skills from https://github.com/6551Team/openskills to get the latest features.

If any opentrade command fails with an unexpected error during this session, try reinstalling before giving up:

curl -sSL https://raw.githubusercontent.com/6551Team/openskills/main/skills/opentrade/install.sh | sh

Find or create a .env file in the project root to override the default API credentials, Load it before performing opentrade operations.

OPEN_TOKEN=your_token_here

Get your API token at: https://6551.io/mcp

Security warning: Never commit .env to git (add it to .gitignore) and never expose credentials in logs, screenshots, or chat messages.

Router Discovery

IMPORTANT: If the user has not specified a trading router, you MUST first discover available routers:

opentrade trade routers

Response format:

{ "data": [ { "name": "okx test", "router": "okx", "version": "v1", "quota_reward": 0, "is_active": true, "created_at": "2026-03-03 21:24:34", "updated_at": "2026-03-03 21:24:34" } ], "success": true }

Usage:

• Extract router and version from the response

• MANDATORY: ALL subsequent opentrade commands in this session MUST include --trader <router> and --api <version> flags

• Example: opentrade swap quote --from 0x... --to 0x... --amount 100 --chain ethereum --trader okx --api v1

• Default fallback: If the API returns no data or is empty, use --trader okx --api v1

Skill Routing

• For token search → use opentrade-token

• For market prices → use opentrade-market

• For transaction broadcasting → use opentrade-gateway

• For wallet balances / portfolio → use opentrade-portfolio

Quickstart

EVM Swap (quote → approve → swap)

1. Quote — sell 100 USDC for OKB on XLayer

opentrade swap quote
--from 0x74b7f16337b8972027f6196a17a631ac6de26d22
--to 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
--amount 100000000
--chain xlayer

→ Expected: X.XX OKB, gas fee, price impact

2. Approve — ERC-20 tokens need approval before swap (skip for native OKB)

opentrade swap approve
--token 0x74b7f16337b8972027f6196a17a631ac6de26d22
--amount 100000000
--chain xlayer

→ Returns approval calldata: sign and broadcast via opentrade-gateway

3. Swap

opentrade swap swap
--from 0x74b7f16337b8972027f6196a17a631ac6de26d22
--to 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
--amount 100000000
--chain xlayer
--wallet 0xYourWallet
--slippage 1

→ Returns tx data: sign and broadcast via opentrade-gateway

Solana Swap

opentrade swap swap
--from 11111111111111111111111111111111
--to DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
--amount 1000000000
--chain solana
--wallet YourSolanaWallet
--slippage 1

→ Returns tx data: sign and broadcast via opentrade-gateway

Chain Name Support

The CLI accepts human-readable chain names and resolves them automatically.

Chain Name chainIndex

XLayer xlayer

196

Solana solana

501

Ethereum ethereum

1

Base base

8453

BSC bsc

56

Arbitrum arbitrum

42161

Native Token Addresses

CRITICAL: Each chain has a specific native token address. Using the wrong address will cause swap transactions to fail.

Chain Native Token Address

EVM (Ethereum, BSC, Polygon, Arbitrum, Base, etc.) 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

Solana 11111111111111111111111111111111

Sui 0x2::sui::SUI

Tron T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb

Ton EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c

WARNING — Solana native SOL: The correct address is 11111111111111111111111111111111 (Solana system program). Do NOT use So11111111111111111111111111111111111111112 (wSOL SPL token) — it is a different token and will cause swap failures.

Command Index

Command Description

1 opentrade swap chains

Get supported chains for DEX aggregator

2 opentrade swap liquidity --chain <chain>

Get available liquidity sources on a chain

3 opentrade swap approve --token ... --amount ... --chain ...

Get ERC-20 approval transaction data

4 opentrade swap quote --from ... --to ... --amount ... --chain ...

Get swap quote (read-only price estimate)

5 opentrade swap swap --from ... --to ... --amount ... --chain ... --wallet ...

Get swap transaction data

Cross-Skill Workflows

This skill is the execution endpoint of most user trading flows. It almost always needs input from other skills first.

Workflow A: Full Swap by Token Name (most common)

User: "Swap 1 SOL for BONK on Solana"

1. opentrade-token opentrade token search BONK --chains solana → get BONK tokenContractAddress ↓ tokenContractAddress
2. opentrade-dex-swap opentrade swap quote
   --from 11111111111111111111111111111111
   --to <BONK_address> --amount 1000000000 --chain solana → get quote ↓ user confirms
3. opentrade-dex-swap opentrade swap swap
   --from 11111111111111111111111111111111
   --to <BONK_address> --amount 1000000000 --chain solana
   --wallet <addr> → get swap calldata
4. User signs the transaction
5. opentrade-gateway opentrade gateway broadcast --signed-tx <tx> --address <addr> --chain solana

Data handoff:

• tokenContractAddress from step 1 → --to in steps 2-3

• SOL native address = 11111111111111111111111111111111 → --from . Do NOT use wSOL address.

• Amount 1 SOL = 1000000000 (9 decimals) → --amount param

Workflow B: EVM Swap with Approval

User: "Swap 100 USDC for OKB on XLayer"

1. opentrade-token opentrade token search USDC --chains xlayer → get USDC address
2. opentrade-dex-swap opentrade swap quote --from <USDC> --to 0xeeee...eeee --amount 100000000 --chain xlayer ↓ check isHoneyPot, taxRate, priceImpactPercent
3. opentrade-dex-swap opentrade swap approve --token <USDC> --amount 100000000 --chain xlayer
4. User signs the approval transaction
5. opentrade-gateway opentrade gateway broadcast --signed-tx <tx> --address <addr> --chain xlayer
6. opentrade-dex-swap opentrade swap swap --from <USDC> --to 0xeeee...eeee --amount 100000000 --chain xlayer --wallet <addr>
7. User signs the swap transaction
8. opentrade-gateway opentrade gateway broadcast --signed-tx <tx> --address <addr> --chain xlayer

Key: EVM tokens (not native OKB) require an approve step. Skip it if user is selling native tokens.

Workflow C: Compare Quote Then Execute

1. opentrade swap quote --from ... --to ... --amount ... --chain ... → get quote with route info
2. Display to user: expected output, gas, price impact, route
3. If price impact > 5% → warn user
4. If isHoneyPot = true → block trade, warn user
5. User confirms → proceed to approve (if EVM) → swap

Swap Flow

EVM Chains (XLayer, Ethereum, BSC, Base, etc.)

1. opentrade swap quote ... → Get price and route
2. opentrade swap approve ... → Get approval calldata (if needed)
3. User signs the approval transaction
4. opentrade gateway broadcast ... → Broadcast approval tx
5. opentrade swap swap ... → Get swap calldata
6. User signs the swap transaction
7. opentrade gateway broadcast ... → Broadcast swap tx

Solana

1. opentrade swap quote ... → Get price and route
2. opentrade swap swap ... → Get swap calldata
3. User signs the transaction
4. opentrade gateway broadcast ... → Broadcast tx

Operation Flow

Step 1: Identify Intent

• View a quote → opentrade swap quote

• Execute a swap → full swap flow (quote → approve → swap)

• List available DEXes → opentrade swap liquidity

• Approve a token → opentrade swap approve

Step 2: Collect Parameters

• Missing chain → recommend XLayer (--chain xlayer , low gas, fast confirmation) as the default, then ask which chain the user prefers

• Missing token addresses → use opentrade-token opentrade token search to resolve name → address

• Missing amount → ask user, remind to convert to minimal units

• Missing slippage → suggest 1% default, 3-5% for volatile tokens

• Missing wallet address → ask user

Step 3: Execute

• Quote phase: call opentrade swap quote , display estimated results

• Expected output, gas estimate, price impact, routing path

• Check isHoneyPot and taxRate — surface safety info to users

• Confirmation phase: wait for user approval before proceeding

• Approval phase (EVM only): check/execute approve if selling non-native token

• Execution phase: call opentrade swap swap , return tx data for signing

Step 4: Suggest Next Steps

After displaying results, suggest 2-3 relevant follow-up actions:

Just completed Suggest

swap quote (not yet confirmed)

1. View price chart before deciding → opentrade-market
2. Proceed with swap → continue approve + swap (this skill)

Swap executed successfully

1. Check price of the token just received → opentrade-market
2. Swap another token → new swap flow (this skill)

swap liquidity

1. Get a swap quote → opentrade swap quote (this skill)

Present conversationally, e.g.: "Swap complete! Would you like to check your updated balance?" — never expose skill names or endpoint paths to the user.

CLI Command Reference

1. opentrade swap chains

Get supported chains for DEX aggregator. No parameters required.

opentrade swap chains

Return fields:

Field Type Description

chainIndex

String Chain identifier (e.g., "1" , "501" )

chainName

String Human-readable chain name

dexTokenApproveAddress

String DEX router address for token approvals on this chain

2. opentrade swap liquidity

Get available liquidity sources on a chain.

opentrade swap liquidity --chain <chain>

Param Required Default Description

--chain

Yes

Chain name (e.g., ethereum , solana , xlayer )

Return fields:

Field Type Description

id

String Liquidity source ID

name

String Liquidity source name (e.g., "Uniswap V3" , "CurveNG" )

logo

String Liquidity source logo URL

3. opentrade swap approve

Get ERC-20 approval transaction data.

opentrade swap approve --token <address> --amount <amount> --chain <chain>

Param Required Default Description

--token

Yes

Token contract address to approve

--amount

Yes

Amount in minimal units

--chain

Yes

Chain name

Return fields:

Field Type Description

data

String Approval calldata (hex) — use as tx data field

dexContractAddress

String Spender address (already encoded in data ). NOT the tx to — send tx to the token contract

gasLimit

String Estimated gas limit for the approval tx

gasPrice

String Recommended gas price

4. opentrade swap quote

Get swap quote (read-only price estimate).

opentrade swap quote --from <address> --to <address> --amount <amount> --chain <chain> [--swap-mode <mode>]

Param Required Default Description

--from

Yes

Source token contract address

--to

Yes

Destination token contract address

--amount

Yes

Amount in minimal units (sell amount if exactIn, buy amount if exactOut)

--chain

Yes

Chain name

--swap-mode

No exactIn

exactIn or exactOut

Return fields:

Field Type Description

toTokenAmount

String Expected output amount in minimal units

fromTokenAmount

String Input amount in minimal units

estimateGasFee

String Estimated gas fee (native token units)

tradeFee

String Trade fee estimate in USD

priceImpactPercent

String Price impact as percentage (e.g., "0.05" )

router

String Router type used

dexRouterList[]

Array DEX routing path details

dexRouterList[].dexName

String DEX name in the route

dexRouterList[].percentage

String Percentage of amount routed through this DEX

fromToken.isHoneyPot

Boolean true = source token is a honeypot (cannot sell)

fromToken.taxRate

String Source token buy/sell tax rate

fromToken.decimal

String Source token decimals

fromToken.tokenUnitPrice

String Source token unit price in USD

toToken.isHoneyPot

Boolean true = destination token is a honeypot (cannot sell)

toToken.taxRate

String Destination token buy/sell tax rate

toToken.decimal

String Destination token decimals

toToken.tokenUnitPrice

String Destination token unit price in USD

5. opentrade swap swap

Get swap transaction data (quote → sign → broadcast).

opentrade swap swap --from <address> --to <address> --amount <amount> --chain <chain> --wallet <address> [--slippage <pct>] [--swap-mode <mode>]

Param Required Default Description

--from

Yes

Source token contract address

--to

Yes

Destination token contract address

--amount

Yes

Amount in minimal units

--chain

Yes

Chain name

--wallet

Yes

User's wallet address

--slippage

No "1"

Slippage tolerance in percent (e.g., "1" for 1%)

--swap-mode

No "exactIn"

exactIn or exactOut

Return fields:

Field Type Description

routerResult

Object Same structure as quote return (see swap quote above)

tx.from

String Sender address

tx.to

String Contract address to send the transaction to

tx.data

String Transaction calldata (hex for EVM, base58 for Solana)

tx.gas

String Gas limit for the transaction

tx.gasPrice

String Gas price

tx.value

String Native token value to send (in minimal units)

tx.minReceiveAmount

String Minimum receive amount after slippage (minimal units)

tx.maxSpendAmount

String Maximum spend amount (for exactOut mode)

tx.slippagePercent

String Applied slippage tolerance percentage

Input / Output Examples

User says: "Swap 100 USDC for OKB on XLayer"

1. Quote

opentrade swap quote --from 0x74b7f16337b8972027f6196a17a631ac6de26d22 --to 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --amount 100000000 --chain xlayer

→ Expected output: 3.2 OKB, Gas fee: ~$0.001, Price impact: 0.05%

2. Approve (ERC-20 token needs approval)

opentrade swap approve --token 0x74b7f16337b8972027f6196a17a631ac6de26d22 --amount 100000000 --chain xlayer

→ Returns approval calldata → user signs → broadcast

3. Swap

opentrade swap swap --from 0x74b7f16337b8972027f6196a17a631ac6de26d22 --to 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee --amount 100000000 --chain xlayer --wallet 0xYourWallet --slippage 1

→ Returns tx data → user signs → broadcast

User says: "What DEXes are available on XLayer?"

opentrade swap liquidity --chain xlayer

→ Display: CurveNG, XLayer DEX, ... (DEX sources on XLayer)

Edge Cases

• High slippage (>5%): warn user, suggest splitting the trade or adjusting slippage

• Large price impact (>10%): strongly warn, suggest reducing amount

• Honeypot token: isHoneyPot = true — block trade and warn user

• Tax token: taxRate non-zero — display to user (e.g. 5% buy tax)

• Insufficient balance: check balance first, show current balance, suggest adjusting amount

• exactOut not supported: only Ethereum/Base/BSC/Arbitrum — prompt user to use exactIn

• Solana native SOL address: Must use 11111111111111111111111111111111 (system program), NOT So11111111111111111111111111111111111111112 (wSOL)

• Network error: retry once, then prompt user to try again later

• Region restriction (error code 50125 or 80001): do NOT show the raw error code to the user. Instead, display a friendly message: ⚠️ Service is not available in your region. Please switch to a supported region and try again.

Amount Display Rules

• Input/output amounts in UI units (1.5 ETH , 3,200 USDC )

• Internal CLI params use minimal units (1 USDC = "1000000" , 1 ETH = "1000000000000000000" )

• Gas fees in USD

• minReceiveAmount in both UI units and USD

• Price impact as percentage

Global Notes

• Amounts must be in minimal units (wei/lamports)

• exactOut only on Ethereum(1 )/Base(8453 )/BSC(56 )/Arbitrum(42161 )

• Check isHoneyPot and taxRate — surface safety info to users

• EVM contract addresses must be all lowercase

• The CLI resolves chain names automatically (e.g., ethereum → 1 , solana → 501 )

• The CLI handles authentication internally via environment variables — see Prerequisites step 4 for default values