Opentrade Wallet

OpenTrade Custodial Wallet

4 API endpoints for custodial wallet creation, account query, swap execution, and native token withdrawal.

IMPORTANT: Custodial wallet only supports BSC and Solana networks.

IMPORTANT: Newly created wallets have zero balance. You must deposit BNB (to the BSC address) or SOL (to the Solana address) before you can swap or withdraw. Do NOT send tokens from other chains (e.g., Ethereum, Polygon, Arbitrum) to these addresses — funds sent from unsupported chains will be lost.

Pre-flight Checks

Every time before running any custodial wallet command, always follow these steps in order:

1. Find or create a .env file in the project root to load the API credentials:

OPENNEWS_TOKEN=your_token_here

Get your API token at: https://www.newsliquid.com/mcp

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

2. Set the base URL and auth header:

BASE_URL="https://ai.6551.io"
AUTH_HEADER="Authorization: Bearer $OPENNEWS_TOKEN"

Skill Routing

• For swap quotes (read-only price estimate) → use opentrade-dex-swap
• For token search / metadata → use opentrade-token
• For market prices → use opentrade-market
• For generic holdings/assets/positions/orders/trade history → use opentrade-cex first
• For wallet balances / portfolio after CEX fallback → use opentrade-portfolio
• For transaction broadcasting (non-custodial) → use opentrade-gateway
• For custodial wallet management → use this skill (opentrade-wallet)

Quickstart

# 1. Create a custodial wallet (EVM + Solana)
curl -s -X POST "$BASE_URL/open/trader/custodial/create" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json"

# 2. Get custodial account addresses
curl -s "$BASE_URL/open/trader/custodial/account" \
  -H "$AUTH_HEADER"

# 3. Custodial swap (auto-sign + broadcast)
curl -s -X POST "$BASE_URL/open/trader/custodial/swap" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"chainIndex":"56","fromTokenAddress":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","toTokenAddress":"0x55d398326f99059fF775485246999027B3197955","amount":"1000000000000000000","slippagePercent":"1"}'

# 4. Withdraw native tokens
curl -s -X POST "$BASE_URL/open/trader/custodial/withdraw" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"network":"bsc","to":"0xRecipientAddress","amount":1000000000000000000}'

Command Index

Supported Networks

Custodial wallet only supports BSC and Solana.

Cross-Skill Workflows

Workflow A: Create Wallet → Deposit → Check Balance → Swap

User: "Create a custodial wallet and swap 1 BNB for USDT"

1. opentrade-wallet         POST /open/trader/custodial/create              → get evm_address, sol_address
       → Tell user to deposit BNB (BSC) or SOL (Solana) to the new address
       → WARNING: only accept BNB/SOL, do NOT send other chain assets
2. opentrade-portfolio opentrade portfolio all-balances --address <evm_address> --chains bsc
       → verify BNB balance >= 1 (user must have deposited first)
3. opentrade-wallet         POST /open/trader/custodial/swap
       {"chainIndex":"56","fromTokenAddress":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "toTokenAddress":"0x55d398326f99059fF775485246999027B3197955",
        "amount":"1000000000000000000","slippagePercent":"1"}
       → returns tx_hash

Data handoff:

• evm_address from step 1 → --address in step 2
• Custodial swap auto-signs and broadcasts — no manual signing needed

Workflow B: Swap Quote → Custodial Swap

User: "Get a quote for swapping BNB to USDT, then execute with custodial wallet"

1. opentrade-dex-swap  opentrade swap quote \
       --from 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee \
       --to 0x55d398326f99059fF775485246999027B3197955 \
       --amount 1000000000000000000 --chain bsc
       → display quote: expected output, price impact
       ↓ user confirms
2. opentrade-wallet         POST /open/trader/custodial/swap
       → auto-sign and broadcast, returns tx_hash

Workflow C: Withdraw After Swap

User: "Swap BNB to USDT, then withdraw BNB to my external wallet"

1. opentrade-wallet         POST /open/trader/custodial/swap → swap tokens
2. opentrade-wallet         POST /open/trader/custodial/withdraw
       {"network":"bsc","to":"0xExternalWallet","amount":1000000000000000000}
       → returns tx_hash

Note: Withdraw only supports native tokens (BNB on BSC, SOL on Solana).

Operation Flow

Step 1: Identify Intent

• Create a new custodial wallet → POST /open/trader/custodial/create
• View custodial wallet addresses → GET /open/trader/custodial/account
• Execute a swap automatically → POST /open/trader/custodial/swap
• Withdraw native tokens → POST /open/trader/custodial/withdraw

Step 2: Collect Parameters

• Missing wallet address → call GET /open/trader/custodial/account first, or create one with POST /open/trader/custodial/create
• Missing token addresses → use opentrade-token to search token by name
• Missing amount → ask user, remind to convert to minimal units
• Missing slippage → suggest 1% default
• Missing network for withdraw → ask user, only bsc or sol supported
• User requests unsupported chain → inform user that custodial wallet only supports BSC and Solana

Step 3: Execute & Display

• Run the API call
• Parse JSON response
• Display human-readable summary

Step 4: Suggest Next Steps

Present conversationally — never expose endpoint paths to the user.

API Reference

1. Create Custodial Wallet

创建托管钱包，同时生成 EVM（BSC）和 Solana 地址。每个用户只能创建一个钱包。

curl -s -X POST "$BASE_URL/open/trader/custodial/create" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json"

Parameters: None (user identity from JWT token)

Response:

{
  "success": true,
  "data": {
    "evm_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "sol_address": "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV"
  }
}

Return fields:

Display to user:

• "Custodial wallet created!"
• "BSC Address: 0x742d..."
• "Solana Address: 7EcD..."
• "Please deposit BNB to your BSC address or SOL to your Solana address before trading."
• "WARNING: Only send BNB (BSC network) or SOL (Solana network). Do NOT send tokens from other chains — funds will be lost."

2. Get Custodial Account

获取当前用户的托管钱包地址。

curl -s "$BASE_URL/open/trader/custodial/account" \
  -H "$AUTH_HEADER"

Parameters: None

Response:

{
  "success": true,
  "data": {
    "evm_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "sol_address": "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV"
  }
}

Return fields:

3. Custodial Swap

使用托管钱包执行 DEX swap。服务端自动完成签名和广播。仅支持 BSC（chainIndex: 56）和 Solana（chainIndex: 501）。

curl -s -X POST "$BASE_URL/open/trader/custodial/swap" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "chainIndex": "56",
    "fromTokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "toTokenAddress": "0x55d398326f99059fF775485246999027B3197955",
    "amount": "1000000000000000000",
    "slippagePercent": "1"
  }'

Parameters:

Response:

{
  "success": true,
  "data": {
    "tx_hash": "0xabc123def456...",
    "error": ""
  }
}

Return fields:

Display to user:

• "Swap executed successfully!"
• "Tx Hash: 0xabc123..."
• If error is non-empty, display the error message

4. Custodial Withdraw

从托管钱包提现原生代币。仅支持 BSC (BNB) 和 Solana (SOL)。

curl -s -X POST "$BASE_URL/open/trader/custodial/withdraw" \
  -H "$AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "bsc",
    "to": "0xRecipientAddress",
    "amount": 1000000000000000000
  }'

Parameters:

Response:

{
  "success": true,
  "data": {
    "tx_hash": "0xdef789...",
    "network": "bsc"
  }
}

Return fields:

Display to user:

• "Withdrawal successful!"
• "Tx Hash: 0xdef789..."
• "Network: BSC"

Native Token Addresses

Input / Output Examples

User says: "Create a custodial wallet for me"

curl -s -X POST "$BASE_URL/open/trader/custodial/create" -H "$AUTH_HEADER" -H "Content-Type: application/json"
# → Wallet created! BSC: 0x742d..., Solana: 7EcD...

User says: "Swap 0.1 BNB for USDT on BSC using my custodial wallet"

# Amount: 0.1 BNB = 100000000000000000 wei
curl -s -X POST "$BASE_URL/open/trader/custodial/swap" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"chainIndex":"56","fromTokenAddress":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","toTokenAddress":"0x55d398326f99059fF775485246999027B3197955","amount":"100000000000000000","slippagePercent":"1"}'
# → Swap executed! Tx Hash: 0xabc...

User says: "Withdraw 1 SOL to my external wallet"

# Amount: 1 SOL = 1000000000 lamports
curl -s -X POST "$BASE_URL/open/trader/custodial/withdraw" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"network":"sol","to":"ExternalSolanaAddress","amount":1000000000}'
# → Withdrawal successful! Tx Hash: 5xYz...

Edge Cases

• Wallet already exists: POST /open/trader/custodial/create will return an error if the user already has a wallet. Use GET /open/trader/custodial/account to retrieve existing addresses.
• New wallet has zero balance: After creating a wallet, the user must deposit BNB (via BSC network) or SOL (via Solana network) before performing any swap or withdraw. Do NOT deposit tokens from other chains (Ethereum, Polygon, Arbitrum, etc.) — those funds will be permanently lost.
• Unsupported chain: Custodial wallet only supports BSC (chainIndex: 56) and Solana (chainIndex: 501). If the user requests another chain (e.g., Ethereum, Arbitrum), inform them that the custodial wallet does not support that chain and suggest using a non-custodial workflow with opentrade-dex-swap + opentrade-gateway.
• Insufficient balance: Swap or withdraw will fail if the custodial wallet has insufficient funds. Check balance with opentrade-portfolio first.
• Unsupported network for withdraw: Only bsc and sol are supported for withdraw.
• Amount must be positive: The amount field for withdraw must be greater than 0.
• High slippage swap: If slippage is too low, the swap may fail. Suggest increasing slippage for volatile tokens.
• 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 (0.1 BNB, 50 USDT)
• Internal API params use minimal units (1 BNB = "1000000000000000000", 1 SOL = 1000000000)
• Display tx hash as clickable link when possible

Global Notes

• All endpoints require Authorization: Bearer <token> header
• Only BSC and Solana are supported — do not attempt other chains
• Amounts must be in minimal units (wei for BSC, lamports for Solana)
• EVM contract addresses must be all lowercase
• Custodial swap handles signing and broadcasting automatically — no need to call sign or broadcast separately
• Withdraw only supports native tokens (BNB/SOL)
• The custodial wallet is powered by Turnkey with AWS KMS for delegated key custody — 6551 does NOT store your private keys