OpenTrade CEX Trading

29 API endpoints for centralized exchange trading — market data, account management, spot & futures orders, positions, leverage, and wallet agent.

IMPORTANT: This is a CEX (centralized exchange) trading skill. All trades are executed server-side with built-in risk controls — no private key management or transaction signing required.

IMPORTANT: Write operations (place order, edit order, close position, set leverage) are protected by a 4-layer risk engine: price deviation check, position limit, rate limit, and balance verification.

Pre-flight Checks

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

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

OPEN_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.

Set the base URL and auth header:

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

Skill Routing

For DEX swaps / on-chain token exchange → use opentrade-dex-swap
For on-chain wallet balances / portfolio → use opentrade-portfolio
For on-chain market data / smart money signals → use opentrade-market
For token search / holders / trending → use opentrade-token
For custodial wallet (BSC/Solana) → use opentrade-wallet
For transaction broadcasting / gas → use opentrade-gateway
For CEX trading (spot, futures, leverage, orders, positions) → use this skill (opentrade-cex)

Supported Exchanges

ExchangeID	Name
`binance`	Binance
`bybit`	Bybit
`okx`	OKX
`hyperliquid`	Hyperliquid
`aster`	Aster

Quickstart

# 1. Get real-time ticker
curl -s "$BASE_URL/open/trader/newsliquid/v1/market/ticker?symbol=BTC/USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"

# 2. Check account balance
curl -s "$BASE_URL/open/trader/newsliquid/v1/account/summary?exchangeId=binance&symbol=BTC/USDT:USDT" \
  -H "$AUTH_HEADER"

# 3. Place a limit buy order
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/orders" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"symbol":"BTC/USDT:USDT","side":"buy","type":"limit","quantity":0.001,"price":60000,"exchangeId":"binance"}'

# 4. Check open orders
curl -s "$BASE_URL/open/trader/newsliquid/v1/orders/open?exchangeId=binance" \
  -H "$AUTH_HEADER"

# 5. Check current positions
curl -s "$BASE_URL/open/trader/newsliquid/v1/positions?exchangeId=binance" \
  -H "$AUTH_HEADER"

# 6. Close a position (market price)
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/positions/close" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"symbol":"BTC/USDT:USDT","side":"long","quantity":0,"exchangeId":"binance"}'

Note: Trading pair format follows CCXT standard: BTC/USDT for spot, BTC/USDT:USDT for USDT perpetual contracts.

Command Index

Market Data (no risk control)

#	Endpoint	Method	Description
1	`/open/trader/newsliquid/v1/market/metadata`	GET	Get market metadata (trading pairs, precision, limits)
2	`/open/trader/newsliquid/v1/market/ticker`	GET	Get real-time ticker (last price, 24h change, volume)
3	`/open/trader/newsliquid/v1/market/klines`	GET	Get K-line / candlestick data
4	`/open/trader/newsliquid/v1/market/base-currencies`	GET	Get base currency list (USDT, BTC, etc.)
5	`/open/trader/newsliquid/v1/market/time`	GET	Get server time

Account (no risk control)

#	Endpoint	Method	Description
6	`/open/trader/newsliquid/v1/account/summary`	GET	Account summary (balance, leverage, max position)
7	`/open/trader/newsliquid/v1/account/spot`	GET	Query specific spot asset
8	`/open/trader/newsliquid/v1/account/spots`	GET	Query all spot assets

Config (no risk control)

#	Endpoint	Method	Description
9	`/open/trader/newsliquid/v1/config`	GET	Get trading config
10	`/open/trader/newsliquid/v1/config`	PUT	Update trading config

Orders (risk control on create/edit)

#	Endpoint	Method	Risk	Description
11	`/open/trader/newsliquid/v1/orders`	POST	Yes	Place order (limit/market/stop-loss/take-profit)
12	`/open/trader/newsliquid/v1/orders/edit`	PUT	Yes	Edit existing order
13	`/open/trader/newsliquid/v1/orders/:orderId`	DELETE	No	Cancel order
14	`/open/trader/newsliquid/v1/orders/open`	GET	No	List open orders
15	`/open/trader/newsliquid/v1/orders/closed`	GET	No	List closed orders

Positions (risk control on close)

#	Endpoint	Method	Risk	Description
16	`/open/trader/newsliquid/v1/positions`	GET	No	List current positions
17	`/open/trader/newsliquid/v1/positions/history`	GET	No	List historical positions
18	`/open/trader/newsliquid/v1/positions/close`	POST	Yes	Close position (market price)

Trades (no risk control)

#	Endpoint	Method	Description
19	`/open/trader/newsliquid/v1/trades/history`	GET	Get trade execution history

Leverage & Margin (risk control on leverage change)

#	Endpoint	Method	Risk	Description
20	`/open/trader/newsliquid/v1/leverage`	GET	No	Get available leverage tiers
21	`/open/trader/newsliquid/v1/leverage/current`	GET	No	Get current leverage setting
22	`/open/trader/newsliquid/v1/leverage/current`	PUT	Yes	Set leverage multiplier
23	`/open/trader/newsliquid/v1/margin/mode`	GET	No	Get margin mode
24	`/open/trader/newsliquid/v1/position/mode`	GET	No	Get position mode (one-way/hedge)
25	`/open/trader/newsliquid/v1/position/mode`	PUT	No	Set position mode

Wallet Agent (no risk control)

#	Endpoint	Method	Description
26	`/open/trader/newsliquid/v1/walletagent/create`	POST	Create wallet agent
27	`/open/trader/newsliquid/v1/walletagent/list`	GET	List wallet agents
28	`/open/trader/newsliquid/v1/walletagent/address/:address`	GET	Query wallet agent by address
29	`/open/trader/newsliquid/v1/walletagent/authorize`	PUT	Authorize wallet agent

API Reference

1. Get Market Metadata

获取指定交易对在所有交易所的市场元数据信息（交易对列表、合约类型、杠杆范围、最小下单量等）。

curl -s "$BASE_URL/open/trader/newsliquid/v1/market/metadata?ticker=BTC" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`ticker`	String (query)	Yes	Base currency code (e.g., `BTC`, `ETH`, `SOL`)

Response:

{
  "success": true,
  "data": {
    "ticker": "BTC",
    "markets": [
      {
        "exchangeId": "binance",
        "id": "BTCUSDT",
        "symbol": "BTC/USDT",
        "displaySymbol": "BTC/USDT",
        "active": true,
        "leverageMin": 1,
        "leverageMax": 125,
        "baseCurrency": "BTC",
        "quoteCurrency": "USDT",
        "settleCurrency": "USDT",
        "type": "swap",
        "rawType": "swap",
        "costMin": 5.0,
        "amountMin": 0.001,
        "margin": true,
        "spot": false,
        "swap": true,
        "future": false,
        "option": false,
        "contract": true
      }
    ]
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

List available exchanges and trading pairs for the requested ticker
Highlight leverage range, min order size, and contract type (spot/swap/future)

2. Get Ticker

获取指定交易所和交易对的实时行情数据。

curl -s "$BASE_URL/open/trader/newsliquid/v1/market/ticker?symbol=BTC/USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`symbol`	String (query)	Yes	Trading pair in CCXT format (e.g., `BTC/USDT`)
`exchangeId`	String (query)	Yes	Exchange ID: `binance`, `bybit`, `okx`, `hyperliquid`

Response:

{
  "success": true,
  "data": {
    "symbol": "BTC/USDT",
    "last": 67890.50,
    "bid": 67889.00,
    "ask": 67891.00,
    "high": 68500.00,
    "low": 66800.00,
    "volume": 12345.678,
    "timestamp": "2026-03-21T10:30:00Z"
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"BTC/USDT: $67,890.50"
"Bid: $67,889 | Ask: $67,891"
"24h High: $68,500 | Low: $66,800 | Volume: 12,345.68 BTC"

3. Get K-Lines

获取 Binance K 线（蜡烛图）数据。

curl -s "$BASE_URL/open/trader/newsliquid/v1/market/klines?symbol=BTCUSDT&interval=1h&limit=100" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`symbol`	String (query)	No	Trading pair (default: `BTCUSDT`)
`interval`	String (query)	No	K-line interval (default: `1m`): `1m`, `5m`, `15m`, `1h`, `4h`, `1d`, etc.
`limit`	Integer (query)	No	Number of candles (default: 100)

Response:

{
  "success": true,
  "data": [
    {
      "openTime": 1679400000000,
      "open": "67800.00",
      "high": "67900.00",
      "low": "67750.00",
      "close": "67850.00",
      "volume": "123.456",
      "closeTime": 1679400059999
    }
  ],
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

Summarize recent price action (e.g., "BTC rose from $67,800 to $67,850 in the last hour")
Mention support/resistance levels if visible

4. Get Base Currencies

获取所有交易所支持的去重基础币种列表。

curl -s "$BASE_URL/open/trader/newsliquid/v1/market/base-currencies" \
  -H "$AUTH_HEADER"

Parameters: None

Response:

{
  "success": true,
  "data": ["BTC", "ETH", "SOL", "DOGE", "XRP"],
  "usage": {"cost": 1, "quota": 99}
}

5. Get Server Time

获取 ai-bots-trading 服务器的当前时间。

curl -s "$BASE_URL/open/trader/newsliquid/v1/market/time" \
  -H "$AUTH_HEADER"

Parameters: None

Response:

{
  "timestamp": 1679400000000,
  "time": "2026-03-21T10:30:00Z",
  "usage": {"cost": 1, "quota": 99}
}

6. Get Account Summary

获取指定交易所的账户余额摘要信息，包括总余额、可用余额、杠杆分析等。

curl -s "$BASE_URL/open/trader/newsliquid/v1/account/summary?exchangeId=binance&symbol=BTC/USDT:USDT&accountType=swap" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`exchangeId`	String (query)	Yes	Exchange ID
`symbol`	String (query)	No	Trading pair, for determining quote currency
`accountType`	String (query)	No	Account type (default: `spot`): `spot`, `swap`, `future`, `margin`

Response:

{
  "success": true,
  "data": {
    "exchangeId": "binance",
    "accountType": "swap",
    "balance": 10000.00,
    "available": 8500.00,
    "currency": "USDT",
    "leverage": 10,
    "maxPosition": 85000.00,
    "totals": {
      "USDT": 10000.00,
      "BTC": 0.05
    },
    "frees": {
      "USDT": 8500.00,
      "BTC": 0.05
    },
    "leverageAnalysis": {
      "symbol": "BTC/USDT:USDT",
      "exchangeId": "binance",
      "availableBalance": 8500.00,
      "balanceCurrency": "USDT",
      "leverageInfo": {
        "exchangeId": "binance",
        "symbol": "BTC/USDT:USDT",
        "tiers": [],
        "supportsDynamicLeverage": true,
        "baseCurrency": "BTC",
        "quoteCurrency": "USDT",
        "settleCurrency": "USDT",
        "generatedAt": 1679400000000
      },
      "marketPrice": 67890.50
    }
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"Total Balance: $10,000.00 USDT"
"Available: $8,500.00 | Leverage: 10x"
"Max Position: $85,000.00"

7. Get Spot Asset

查询指定交易所和交易对的现货资产持有信息。

curl -s "$BASE_URL/open/trader/newsliquid/v1/account/spot?exchangeId=binance&symbol=BTC/USDT" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`exchangeId`	String (query)	Yes	Exchange ID
`symbol`	String (query)	Yes	Trading pair (e.g., `BTC/USDT`)

Response:

{
  "success": true,
  "data": {
    "exchangeId": "binance",
    "symbol": "BTC/USDT",
    "baseAsset": "BTC",
    "quantity": 0.5,
    "free": 0.45,
    "locked": 0.05,
    "costPrice": 65000.00,
    "totalCost": 32500.00
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"BTC: 0.5 (Free: 0.45, Locked: 0.05)"
"Avg Cost: $65,000 | Total Cost: $32,500"

8. Get All Spot Assets

获取指定交易所的所有现货资产列表。

curl -s "$BASE_URL/open/trader/newsliquid/v1/account/spots?exchangeId=binance" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`exchangeId`	String (query)	Yes	Exchange ID
`symbol`	String (query)	No	Filter by trading pair

Response:

{
  "success": true,
  "data": [
    {
      "exchangeId": "binance",
      "symbol": null,
      "baseAsset": "BTC",
      "quantity": 0.5,
      "free": 0.45,
      "locked": 0.05,
      "costPrice": 65000.00,
      "totalCost": 32500.00
    },
    {
      "exchangeId": "binance",
      "symbol": null,
      "baseAsset": "USDT",
      "quantity": 10000.00,
      "free": 8500.00,
      "locked": 1500.00,
      "costPrice": 1.00,
      "totalCost": 10000.00
    }
  ],
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

List all assets with non-zero balances, showing free/locked split and cost basis

9. Get Trading Config

获取用户的交易配置摘要（不包含密钥敏感信息）。

curl -s "$BASE_URL/open/trader/newsliquid/v1/config" \
  -H "$AUTH_HEADER"

Parameters: None

Response:

{
  "success": true,
  "data": {
    "defaultExchange": "binance",
    "defaultLeverage": 10,
    "defaultPosition": 100.0,
    "general": {},
    "binanceConfigured": true,
    "bybitConfigured": false,
    "okxConfigured": true,
    "hyperliquidConfigured": false,
    "asterConfigured": false
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"Default Exchange: binance | Leverage: 10x | Position: $100"
List which exchanges are configured

10. Update Trading Config

更新用户的交易配置，包括默认交易所、杠杆和交易所凭证。

IMPORTANT: Exchange API credentials (apiKey, secret, password) are sensitive. Never log or display them.

curl -s -X PUT "$BASE_URL/open/trader/newsliquid/v1/config" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "defaultExchange": "binance",
    "defaultLeverage": 10,
    "defaultPosition": 100.0,
    "binance": {
      "apiKey": "your-api-key",
      "secret": "your-api-secret",
      "password": ""
    }
  }'

Parameters (body):

Field	Type	Required	Description
`defaultExchange`	String	No	Default exchange: `binance`, `bybit`, `okx`, `hyperliquid`
`defaultLeverage`	Integer	No	Default leverage (1-125)
`defaultPosition`	Float	No	Default position size
`general`	Object	No	General config
`binance` / `bybit` / `okx` / `hyperliquid` / `aster`	Object	No	Exchange credentials: `apiKey` (required), `secret` (required), `password` (optional, OKX requires)

Response:

{
  "success": true,
  "data": {
    "updated": true
  },
  "usage": {"cost": 1, "quota": 99}
}

11. Place Order (Risk Controlled)

在指定交易所下单。支持多种订单类型。

This endpoint is protected by the risk engine — orders that deviate too far from market price, exceed position limits, hit rate limits, or lack sufficient balance will be rejected.

# Limit order: buy 0.01 BTC at $65,000 with TP/SL
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/orders" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "exchangeId": "binance",
    "symbol": "BTC/USDT:USDT",
    "side": "buy",
    "type": "limit",
    "quantity": 0.01,
    "price": 65000.00,
    "stopLossPrice": 64000.00,
    "takeProfitPrice": 70000.00
  }'

# Market order: sell 0.5 ETH
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/orders" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "exchangeId": "binance",
    "symbol": "ETH/USDT:USDT",
    "side": "sell",
    "type": "market",
    "quantity": 0.5
  }'

# Stop-loss market order
curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/orders" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "exchangeId": "binance",
    "symbol": "BTC/USDT:USDT",
    "side": "sell",
    "type": "stop_market",
    "quantity": 0.01,
    "triggerPrice": 58000.00
  }'

Parameters (body):

Field	Type	Required	Description
`exchangeId`	String	No	Exchange ID (default: `binance`)
`symbol`	String	Yes	Trading pair in CCXT format (e.g., `BTC/USDT:USDT`)
`side`	String	Yes	`buy` or `sell`
`type`	String	Yes	Order type (see below)
`quantity`	Float	Conditional	Base currency quantity
`quoteAmount`	Float	Conditional	Quote currency amount (e.g., USDT)
`price`	Float	Conditional	Limit price, required for `limit`, `stop_limit`, `take_profit_limit`
`triggerPrice`	Float	Conditional	Trigger price, required for `stop_market`, `stop_limit`, `take_profit_market`, `take_profit_limit`
`hedged`	Boolean	No	Hedge mode (default: `false`)
`stopLossPrice`	Float	No	Attached stop-loss trigger price
`takeProfitPrice`	Float	No	Attached take-profit trigger price

Order types:

market — Market order
limit — Limit order
oco — OCO order
stop_market — Stop-loss market order
stop_limit — Stop-loss limit order
take_profit_market — Take-profit market order
take_profit_limit — Take-profit limit order

Response:

{
  "success": true,
  "data": {
    "exchange": "binance",
    "orderId": "123456789",
    "symbol": "BTC/USDT:USDT",
    "side": "buy",
    "type": "limit",
    "amount": 0.01,
    "price": 65000.00,
    "triggerPrice": 0,
    "status": "open",
    "filledQty": 0,
    "avgPrice": 0,
    "reduceOnly": false,
    "createdAt": "2026-03-21T10:30:00Z",
    "tpsl": {
      "tpTriggerPx": 70000.00,
      "tpTriggerPxType": "last",
      "tpOrdPx": -1,
      "slTriggerPx": 64000.00,
      "slTriggerPxType": "last",
      "slOrdPx": -1,
      "attachId": "attach_001",
      "closePosition": false
    }
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"Order placed! ID: 123456789"
"Buy 0.01 BTC @ $65,000 (Limit) on Binance"
"TP: $70,000 | SL: $64,000"
"Status: Open"

12. Edit Order (Risk Controlled)

修改已存在的挂单参数。

This endpoint is protected by the risk engine.

curl -s -X PUT "$BASE_URL/open/trader/newsliquid/v1/orders/edit" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "exchangeId": "binance",
    "orderId": "123456789",
    "symbol": "BTC/USDT:USDT",
    "type": "limit",
    "side": "buy",
    "quantity": 0.02,
    "price": 64500.00
  }'

Parameters (body):

Field	Type	Required	Description
`exchangeId`	String	Yes	Exchange ID
`orderId`	String	No	Order ID (Binance TP/SL orders can omit)
`symbol`	String	Yes	Trading pair
`type`	String	No	Order type
`side`	String	No	Direction
`quantity`	Float	No	New quantity
`price`	Float	No	New limit price
`triggerPrice`	Float	No	New trigger price
`stopLossPrice`	Float	No	New stop-loss price
`takeProfitPrice`	Float	No	New take-profit price
`hedged`	Boolean	No	Hedge mode

Response: Same OrderResponse structure as Place Order.

13. Cancel Order

取消指定的挂单。

curl -s -X DELETE "$BASE_URL/open/trader/newsliquid/v1/orders/123456789?exchangeId=binance&symbol=BTC/USDT:USDT" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`orderId`	String (path)	Yes	Order ID (in URL path)
`exchangeId`	String (query)	Yes	Exchange ID
`symbol`	String (query)	Yes	Trading pair
`type`	String (query)	No	Order type (required for TP/SL orders)

Response:

{
  "success": true,
  "data": {
    "cancelled": true
  },
  "usage": {"cost": 1, "quota": 99}
}

14. List Open Orders

获取当前所有未成交的挂单。

curl -s "$BASE_URL/open/trader/newsliquid/v1/orders/open?exchangeId=binance&symbol=BTC/USDT:USDT" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`exchangeId`	String (query)	No	Exchange ID (omit for all exchanges)
`symbol`	String (query)	No	Filter by trading pair
`days`	Integer (query)	No	Filter by creation time (days)

Response:

{
  "success": true,
  "data": [
    {
      "exchange": "binance",
      "orderId": "123456789",
      "symbol": "BTC/USDT:USDT",
      "side": "buy",
      "type": "limit",
      "amount": 0.01,
      "price": 65000.00,
      "triggerPrice": 0,
      "status": "open",
      "filledQty": 0,
      "avgPrice": 0,
      "reduceOnly": false,
      "createdAt": "2026-03-21T10:30:00Z",
      "tpsl": null
    }
  ],
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

Table of open orders with exchange, ID, pair, side, type, amount, price, status

15. List Closed Orders

获取已完成（成交/取消）的历史订单。

curl -s "$BASE_URL/open/trader/newsliquid/v1/orders/closed?exchangeId=binance&symbol=BTC/USDT:USDT&days=7" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`exchangeId`	String (query)	No	Exchange ID (omit for all exchanges)
`symbol`	String (query)	No	Filter by trading pair
`days`	Integer (query)	No	Filter by days (default: 7)

Response: Same []OrderResponse structure as List Open Orders.

16. List Current Positions

获取当前所有持仓信息。

curl -s "$BASE_URL/open/trader/newsliquid/v1/positions?exchangeId=binance" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`exchangeId`	String (query)	No	Exchange ID (omit for all exchanges)
`symbol`	String (query)	No	Filter by trading pair

Response:

{
  "success": true,
  "data": [
    {
      "exchange": "binance",
      "symbol": "BTC/USDT:USDT",
      "side": "long",
      "contracts": 0.01,
      "entryPrice": 65000.00,
      "markPrice": 67890.50,
      "unrealizedPnl": 28.905,
      "leverage": 10,
      "liquidationPrice": 58500.00,
      "marginMode": "cross",
      "hedged": false,
      "timestamp": 1679400000000
    }
  ],
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"BTC/USDT:USDT Long 0.01 BTC (Binance)"
"Entry: $65,000 | Mark: $67,890.50"
"P&L: +$28.91 (+4.45%)"
"Leverage: 10x Cross | Liq: $58,500"

17. List Historical Positions

获取已平仓的历史持仓记录（包含关联的交易明细）。

curl -s "$BASE_URL/open/trader/newsliquid/v1/positions/history?exchangeId=binance&days=7" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`exchangeId`	String (query)	No	Exchange ID
`symbol`	String (query)	No	Filter by trading pair
`days`	Integer (query)	No	Filter by days (default: 0 = all)

Response:

{
  "success": true,
  "data": [
    {
      "exchange": "binance",
      "symbol": "BTC/USDT:USDT",
      "side": "long",
      "marginMode": "cross",
      "leverage": 10,
      "entryPrice": 65000.00,
      "openDateTime": "2026-03-20T08:00:00Z",
      "openTimestamp": 1679313600000,
      "closePrice": 67500.00,
      "fullyClosed": true,
      "closeDateTime": "2026-03-21T10:30:00Z",
      "closeTimestamp": 1679400600000,
      "closedAmount": 0.01,
      "totalAmount": 0.01,
      "realizedPnl": 25.00,
      "totalFee": 1.30,
      "tradeCount": 2,
      "openTrades": 1,
      "closeTrades": 1,
      "trades": [
        {
          "exchange": "binance",
          "tradeId": "trade_001",
          "orderId": "order_001",
          "symbol": "BTC/USDT:USDT",
          "side": "buy",
          "price": 65000.00,
          "amount": 0.01,
          "cost": 650.00,
          "fee": 0.65,
          "pnl": 0,
          "reduceOnly": false,
          "timestamp": 1679313600000,
          "datetime": "2026-03-20T08:00:00Z"
        },
        {
          "exchange": "binance",
          "tradeId": "trade_002",
          "orderId": "order_002",
          "symbol": "BTC/USDT:USDT",
          "side": "sell",
          "price": 67500.00,
          "amount": 0.01,
          "cost": 675.00,
          "fee": 0.65,
          "pnl": 25.00,
          "reduceOnly": true,
          "timestamp": 1679400600000,
          "datetime": "2026-03-21T10:30:00Z"
        }
      ]
    }
  ],
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"BTC/USDT:USDT Long — Closed"
"Entry: $65,000 → Exit: $67,500"
"Realized P&L: +$25.00 (Fee: $1.30)"
"Duration: ~26.5 hours"

18. Close Position (Risk Controlled)

关闭指定的持仓（全部或部分平仓）。

This endpoint is protected by the risk engine.

curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/positions/close" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "exchangeId": "binance",
    "symbol": "BTC/USDT:USDT",
    "side": "long",
    "quantity": 0,
    "hedged": false
  }'

Parameters (body):

Field	Type	Required	Description
`exchangeId`	String	Yes	Exchange ID
`symbol`	String	Yes	Trading pair
`side`	String	Yes	Position side: `long` or `short`
`quantity`	Float	No	Close quantity (0 = close all)
`hedged`	Boolean	No	Hedge mode
`price`	Float	No	Market price for Hyperliquid

Response: Same OrderResponse structure as Place Order.

Display to user:

"Position closed! BTC/USDT:USDT Long"
Show realized P&L from the order response

19. Get Trade History

获取历史成交记录。

curl -s "$BASE_URL/open/trader/newsliquid/v1/trades/history?exchangeId=binance&symbol=BTC/USDT:USDT&days=7" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`exchangeId`	String (query)	No	Exchange ID
`symbol`	String (query)	No	Filter by trading pair
`days`	Integer (query)	No	Filter by days (default: 7)

Response:

{
  "success": true,
  "data": [
    {
      "exchange": "binance",
      "tradeId": "trade_001",
      "orderId": "order_001",
      "symbol": "BTC/USDT:USDT",
      "side": "buy",
      "price": 65000.00,
      "amount": 0.01,
      "cost": 650.00,
      "fee": 0.65,
      "pnl": 0,
      "reduceOnly": false,
      "timestamp": 1679313600000,
      "datetime": "2026-03-20T08:00:00Z"
    }
  ],
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

Table of trades with exchange, pair, side, price, amount, cost, fee, P&L

20. Get Leverage Tiers

获取指定交易对的杠杆档位（梯度）信息。

curl -s "$BASE_URL/open/trader/newsliquid/v1/leverage?symbol=BTC/USDT:USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`symbol`	String (query)	Yes	Trading pair
`exchangeId`	String (query)	Yes	Exchange ID

Response:

{
  "success": true,
  "data": {
    "exchangeId": "binance",
    "symbol": "BTC/USDT:USDT",
    "tiers": [
      {
        "tier": 1,
        "minNotional": 0,
        "maxNotional": 50000,
        "maintenanceMarginRate": 0.004,
        "initialMarginRate": 0.01,
        "maxLeverage": 100
      },
      {
        "tier": 2,
        "minNotional": 50000,
        "maxNotional": 250000,
        "maintenanceMarginRate": 0.005,
        "initialMarginRate": 0.02,
        "maxLeverage": 50
      }
    ],
    "supportsDynamicLeverage": true,
    "baseCurrency": "BTC",
    "quoteCurrency": "USDT",
    "settleCurrency": "USDT",
    "minNotional": 5.0,
    "generatedAt": 1679400000000
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

Table of leverage tiers with max leverage, notional range, and margin rates

21. Get Current Leverage

获取指定交易对当前设置的杠杆倍数和保证金模式。

curl -s "$BASE_URL/open/trader/newsliquid/v1/leverage/current?symbol=BTC/USDT:USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`symbol`	String (query)	Yes	Trading pair
`exchangeId`	String (query)	Yes	Exchange ID

Response:

{
  "success": true,
  "data": {
    "leverage": 10,
    "marginMode": "cross"
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"BTC/USDT:USDT: 10x leverage, Cross margin"

22. Set Leverage (Risk Controlled)

设置指定交易对的杠杆倍数。

This endpoint is protected by the risk engine.

curl -s -X PUT "$BASE_URL/open/trader/newsliquid/v1/leverage/current" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"exchangeId":"binance","symbol":"BTC/USDT:USDT","leverage":20}'

Parameters (body):

Field	Type	Required	Description
`exchangeId`	String	Yes	Exchange ID
`symbol`	String	Yes	Trading pair
`leverage`	Integer	Yes	Leverage multiplier (min: 1)

Response:

{
  "success": true,
  "data": {
    "updated": true
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"Leverage updated! BTC/USDT:USDT: 20x"

23. Get Margin Mode

获取指定交易对的保证金模式（cross 全仓 / isolated 逐仓）。

curl -s "$BASE_URL/open/trader/newsliquid/v1/margin/mode?symbol=BTC/USDT:USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`symbol`	String (query)	Yes	Trading pair
`exchangeId`	String (query)	Yes	Exchange ID

Response:

{
  "success": true,
  "data": {
    "marginMode": "cross"
  },
  "usage": {"cost": 1, "quota": 99}
}

24. Get Position Mode

获取指定交易对的持仓模式（单向/双向）。

curl -s "$BASE_URL/open/trader/newsliquid/v1/position/mode?symbol=BTC/USDT:USDT&exchangeId=binance" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`symbol`	String (query)	Yes	Trading pair
`exchangeId`	String (query)	Yes	Exchange ID

Response:

{
  "success": true,
  "data": {
    "hedged": false,
    "positionMode": "one_way"
  },
  "usage": {"cost": 1, "quota": 99}
}

25. Set Position Mode

设置指定交易对的持仓模式。

curl -s -X PUT "$BASE_URL/open/trader/newsliquid/v1/position/mode" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"exchangeId":"binance","symbol":"BTC/USDT:USDT","hedged":true}'

Parameters (body):

Field	Type	Required	Description
`exchangeId`	String	Yes	Exchange ID
`symbol`	String	Yes	Trading pair
`hedged`	Boolean	Yes	`true` = Hedge Mode (two-way), `false` = One-way Mode

Response:

{
  "success": true,
  "data": {
    "updated": true
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"Position mode updated to Hedge (two-way)"

26. Create Wallet Agent

创建一个新的以太坊钱包代理（用于 Aster 或 Hyperliquid 交易）。

curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/walletagent/create" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"exchange":"hyperliquid"}'

Parameters (body):

Field	Type	Required	Description
`exchange`	String	Yes	Exchange type: `aster` or `hyperliquid`

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "userId": "user_001",
    "agentAddress": "0x1234567890abcdef...",
    "userAddress": "",
    "exchange": "hyperliquid",
    "authorized": false,
    "createdAt": "2026-03-21T10:30:00Z",
    "updatedAt": "2026-03-21T10:30:00Z"
  },
  "usage": {"cost": 1, "quota": 99}
}

Display to user:

"Wallet agent created!"
"Agent Address: 0x1234..."
"Exchange: Hyperliquid"
"Status: Not authorized (run authorize to activate)"

27. List Wallet Agents

获取当前用户的所有钱包代理列表。

curl -s "$BASE_URL/open/trader/newsliquid/v1/walletagent/list?exchange=hyperliquid" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`exchange`	String (query)	No	Filter by exchange type: `aster` or `hyperliquid`

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "userId": "user_001",
      "agentAddress": "0x1234567890abcdef...",
      "userAddress": "0xabcdef1234567890...",
      "exchange": "hyperliquid",
      "authorized": true,
      "expiredAt": 1681992600000,
      "createdAt": "2026-03-21T10:30:00Z",
      "updatedAt": "2026-03-21T10:30:00Z"
    }
  ],
  "usage": {"cost": 1, "quota": 99}
}

28. Query Wallet Agent by Address

根据钱包地址获取钱包代理信息。

curl -s "$BASE_URL/open/trader/newsliquid/v1/walletagent/address/0x1234567890abcdef?exchange=hyperliquid" \
  -H "$AUTH_HEADER"

Parameters:

Field	Type	Required	Description
`address`	String (path)	Yes	Wallet address (in URL path)
`exchange`	String (query)	No	Filter by exchange type

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "userId": "user_001",
    "agentAddress": "0x1234567890abcdef...",
    "userAddress": "0xabcdef1234567890...",
    "exchange": "hyperliquid",
    "authorized": true,
    "expiredAt": 1681992600000,
    "createdAt": "2026-03-21T10:30:00Z",
    "updatedAt": "2026-03-21T10:30:00Z"
  },
  "usage": {"cost": 1, "quota": 99}
}

29. Authorize Wallet Agent

设置钱包代理的授权状态。

curl -s -X PUT "$BASE_URL/open/trader/newsliquid/v1/walletagent/authorize" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{
    "agentAddress": "0x1234567890abcdef...",
    "exchange": "hyperliquid",
    "userAddress": "0xabcdef1234567890...",
    "authorized": true,
    "expiredAt": 1681992600000
  }'

Parameters (body):

Field	Type	Required	Description
`agentAddress`	String	Yes	Agent wallet address
`exchange`	String	Yes	Exchange type: `aster` or `hyperliquid`
`userAddress`	String	Yes	User's main wallet address
`authorized`	Boolean	Yes	`true` to authorize, `false` to revoke
`expiredAt`	Integer	No	Authorization expiry (Unix milliseconds)

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "userId": "user_001",
    "agentAddress": "0x1234567890abcdef...",
    "userAddress": "0xabcdef1234567890...",
    "exchange": "hyperliquid",
    "authorized": true,
    "expiredAt": 1681992600000,
    "createdAt": "2026-03-21T10:30:00Z",
    "updatedAt": "2026-03-21T11:00:00Z"
  },
  "usage": {"cost": 1, "quota": 99}
}

Cross-Skill Workflows

Workflow A: CEX Spot Trading

User: "Buy 0.1 BTC on Binance"

1. opentrade-cex  GET /market/ticker?symbol=BTC/USDT&exchangeId=binance  → check current price
2. opentrade-cex  GET /account/summary?exchangeId=binance                → verify available balance
3. opentrade-cex  GET /market/metadata?ticker=BTC                        → confirm pair info/limits
4. opentrade-cex  POST /orders                                           → place order
       {"symbol":"BTC/USDT:USDT","side":"buy","type":"market","quantity":0.1,"exchangeId":"binance"}
5. opentrade-cex  GET /orders/open                                       → confirm order status

Data handoff:

last price from step 1 → helps user decide order type (market vs limit)
available balance from step 2 → validates user can afford the order
Market info from step 3 → confirms pair exists and shows limits

Workflow B: CEX Futures Trading

User: "Open a 10x long on ETH with $1000"

1. opentrade-cex  GET /market/ticker?symbol=ETH/USDT&exchangeId=binance  → check ETH price
2. opentrade-cex  GET /account/summary?exchangeId=binance&symbol=ETH/USDT:USDT&accountType=swap  → check margin balance
3. opentrade-cex  GET /leverage/current?symbol=ETH/USDT:USDT&exchangeId=binance  → check current leverage
4. opentrade-cex  PUT /leverage/current                       → set leverage to 10x (if needed)
       {"symbol":"ETH/USDT:USDT","leverage":10,"exchangeId":"binance"}
5. opentrade-cex  POST /orders                                → open long position
       {"symbol":"ETH/USDT:USDT","side":"buy","type":"market","quantity":<calculated>,"exchangeId":"binance"}
6. opentrade-cex  GET /positions                              → verify position opened

Data handoff:

last price from step 1 → calculate quantity: $1000 / ETH_price
Leverage 10x means only $100 margin needed for $1000 position

Workflow C: News-Driven CEX Trading

User: "Check latest crypto news and trade accordingly"

1. [opennews]             Search crypto news → get AI ratings and trade signals
2. [opentwitter]          Check KOL sentiment on the target token
3. opentrade-cex   GET /market/ticker                         → check CEX price
4. opentrade-cex   GET /market/klines?interval=1h             → check recent trend
5. opentrade-cex   GET /account/summary                       → check balance
6. opentrade-cex   POST /orders                               → execute trade
7. opentrade-cex   GET /positions                             → monitor position

Workflow D: CEX-DEX Price Arbitrage

User: "Compare BTC price between CEX and DEX"

1. opentrade-cex   GET /market/ticker?symbol=BTC/USDT&exchangeId=binance   → CEX price
2. [opentrade-market]     GET /market/price (on-chain)               → DEX price
3. Compare prices → identify arbitrage opportunity
4a. CEX cheaper → opentrade-cex POST /orders (CEX buy) + [opentrade-dex-swap] (DEX sell)
4b. DEX cheaper → [opentrade-dex-swap] (DEX buy) + opentrade-cex POST /orders (CEX sell)
5. Confirm both sides filled → calculate profit

Workflow E: CEX Hedge + DEX Spot Holdings

User: "Hedge my on-chain ETH holdings with a CEX short"

1. [opentrade-portfolio]  Check on-chain ETH balance                 → e.g., 10 ETH
2. opentrade-cex   GET /account/summary                       → check CEX margin
3. opentrade-cex   PUT /leverage/current                      → set leverage
4. opentrade-cex   POST /orders                               → open short position
       {"symbol":"ETH/USDT:USDT","side":"sell","type":"market","quantity":10,"exchangeId":"binance"}
5. opentrade-cex   GET /positions                             → confirm hedge position

Workflow F: DEX Discovery + CEX Execution

User: "Find trending tokens and trade on CEX"

1. [opentrade-token]      Search trending tokens                     → discover hot tokens
2. [opentrade-market]     Check on-chain trading activity            → smart money signals
3. opentrade-cex   GET /market/metadata                       → check if listed on CEX
4. If CEX listed → opentrade-cex POST /orders                 → trade on CEX (lower fees)
   If not listed → [opentrade-dex-swap]                              → trade on DEX

Workflow G: Cross-Venue Portfolio Overview

User: "Show me all my assets across CEX and DEX"

1. opentrade-cex   GET /account/summary                       → CEX total balance
2. opentrade-cex   GET /account/spots                         → CEX spot assets
3. opentrade-cex   GET /positions                             → CEX open positions
4. [opentrade-portfolio]  Get on-chain wallet balances               → DEX holdings
5. Combine and present unified portfolio report

Operation Flow

Step 1: Identify Intent

User wants to...	Action
Check CEX market price	`GET /market/ticker`
View K-line / chart data	`GET /market/klines`
Check account balance	`GET /account/summary` or `GET /account/spots`
Place a buy/sell order	`POST /orders`
Modify an existing order	`PUT /orders/edit`
Cancel an order	`DELETE /orders/:orderId`
View open orders	`GET /orders/open`
View closed orders	`GET /orders/closed`
Check current positions	`GET /positions`
Close a position	`POST /positions/close`
Set leverage	`PUT /leverage/current`
Check leverage / margin	`GET /leverage/current`, `GET /margin/mode`
View trade history	`GET /trades/history`
Manage wallet agents	`POST/GET/PUT /walletagent/*`

Step 2: Collect Parameters

Missing exchangeId → ask user which exchange (e.g., binance, bybit, okx, hyperliquid)
Missing symbol → ask user which trading pair; format as CCXT standard (e.g., BTC/USDT for spot, BTC/USDT:USDT for perpetual)
Missing side → ask user: buy or sell?
Missing order type → suggest market for immediate execution, limit for price control
Missing quantity → ask user; for futures, help calculate based on notional value and leverage
Missing price → required for limit orders; call GET /market/ticker to show current price as reference
Missing leverage → check current setting with GET /leverage/current; suggest 1x-10x for beginners

Step 3: Execute & Display

Run the API call
Parse JSON response
Display human-readable summary with prices, quantities, P&L in friendly format
For order creation: show order ID, pair, side, type, quantity, price, status
For positions: show pair, side, entry/mark price, P&L, leverage
For account: show total/available balance, unrealized P&L

Step 4: Suggest Next Steps

Just completed	Suggest
Checked ticker	1. Place an order 2. View K-line for trend analysis
Checked balance	1. Place an order 2. Check positions
Placed order	1. Check open orders 2. View positions 3. Set stop-loss
Order filled	1. View positions 2. Set take-profit/stop-loss
Position opened	1. Monitor with ticker 2. Set stop-loss order 3. Close position
Position closed	1. Check realized P&L in trade history 2. Check updated balance
Set leverage	1. Place an order 2. Check position limits

Present conversationally — never expose endpoint paths to the user.

Risk Engine Notes

All risk-controlled endpoints (marked with "Risk: Yes" in Command Index) pass through a 4-layer risk engine before execution:

Rule	Name	Trigger	Default Threshold
1	Price Deviation Check	Limit orders	Max 10% deviation from market price
2	Position Size Limit	Order creation, position close	Single: 20% of balance, Total: 80% of balance
3	Rate Limit	All risk-controlled endpoints	30 requests per minute
4	Balance Check	Order creation	Min 5% balance reserve

What happens when risk check fails:

The API returns an error with a description of which rule was triggered
The order/action is NOT executed
Display the reason to the user clearly (e.g., "Order rejected: price deviates 15% from market price, max allowed is 10%")
Suggest corrective action (adjust price, reduce quantity, wait and retry, etc.)

Risk engine behavior:

Rules are checked in priority order (rate limit → price deviation → position limit → balance check)
First failure stops the chain — remaining rules are not checked
The risk engine uses a fail-open strategy: if market data or Redis is unavailable, the check passes (prioritizing availability)

Input / Output Examples

User says: "What's the BTC price on Binance?"

curl -s "$BASE_URL/open/trader/newsliquid/v1/market/ticker?symbol=BTC/USDT&exchangeId=binance" -H "$AUTH_HEADER"
# → BTC/USDT: $67,890.50 (Bid: $67,889 | Ask: $67,891)

User says: "Buy 0.01 BTC at $65,000"

curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/orders" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"symbol":"BTC/USDT:USDT","side":"buy","type":"limit","quantity":0.01,"price":65000,"exchangeId":"binance"}'
# → Order placed! Buy 0.01 BTC @ $65,000 (Limit) — ID: 123456789

User says: "Close my BTC position"

curl -s -X POST "$BASE_URL/open/trader/newsliquid/v1/positions/close" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"symbol":"BTC/USDT:USDT","side":"long","quantity":0,"exchangeId":"binance"}'
# → Position closed! Realized P&L: +$25.00

User says: "Set my ETH leverage to 20x"

curl -s -X PUT "$BASE_URL/open/trader/newsliquid/v1/leverage/current" \
  -H "$AUTH_HEADER" -H "Content-Type: application/json" \
  -d '{"symbol":"ETH/USDT:USDT","leverage":20,"exchangeId":"binance"}'
# → Leverage updated! ETH/USDT:USDT: 20x

Edge Cases

Risk engine rejects order: Display the rejection reason clearly. Common causes: price too far from market (>10%), position too large, rate limited, insufficient balance. Suggest the user adjust parameters and retry.
Insufficient balance: Check balance with GET /account/summary first. For futures, consider leverage — required margin = order value / leverage.
Rate limited: If 30+ requests in 1 minute, wait 60 seconds before retrying. Inform the user about the cooldown.
Invalid trading pair: Call GET /market/metadata to verify the symbol exists on the exchange.
Position mode conflict: Cannot switch position mode while holding open positions. Close all positions first.
Leverage change with open positions: Some exchanges restrict leverage changes when positions are open. Close positions or reduce size first.
Order quantity precision: Use GET /market/metadata to check amountMin and costMin. Ensure order meets minimum requirements.
Minimum notional: Orders below the minimum cost (e.g., $5 costMin) will be rejected by the exchange.
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: Service is not available in your region. Please switch to a supported region and try again.

Amount Display Rules

CEX amounts use standard units (e.g., 0.1 BTC, 100 USDT) — NOT minimal units like DEX
Always show currency symbol alongside amounts
Format large numbers with commas (e.g., $67,500.50)
Show P&L with sign and color hint: positive (+$250.00), negative (-$100.00)
Show percentage changes with sign (e.g., +1.89%, -0.52%)
Leverage shown as multiplier (e.g., 10x, 20x)

Global Notes

All endpoints require Authorization: Bearer <token> header
Supported exchanges: binance, bybit, okx, hyperliquid, aster
Trading pair format follows CCXT standard: BTC/USDT for spot, BTC/USDT:USDT for USDT perpetual contracts
The API routes through the CEX gateway with built-in risk controls — trades execute server-side
No private keys or transaction signing involved — this is CEX trading via API
CEX uses standard amount units (e.g., 0.1 BTC), unlike DEX which uses minimal units (wei/lamports)
Numeric values in request bodies use native types (numbers, not strings): "quantity": 0.01, "price": 65000.00
Risk-controlled endpoints may reject requests — always display the rejection reason to the user
Query parameters go in the URL, body parameters go in JSON request body
Wallet Agent feature only supports aster and hyperliquid exchanges
Each API request consumes 1 quota unit (shown in usage field of response)
Success response: {"success": true, "data": {...}, "usage": {"cost": 1, "quota": 99}}
Error response (upstream): {"success": false, "code": "INVALID_REQUEST", "error": "message"}
Error response (gateway): {"code": 400, "message": "error message", "error": "details"}
The skill uses the same OPEN_TOKEN as all other opentrade skills — no additional configuration needed