Execute live CEX order
execute_tradeDestructive
Execute a live CEX order immediately (real money) via stored exchange keys. Needs the trade:execute scope AND user YOLO eligibility (kill switch off, autonomy != propose_only); caps enforced per order. Fee-aware: pass stop to refuse stops that cannot survive round-trip fees (min-move gate), or risk_usd to size from risk (needs stop, else an ATR stop from venue klines). Returns the fee estimate + min-move in the result. CEX spot/futures only — never on-chain.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"exchange": "<exchange>",
"pair": "<pair>",
"side": "<side>"
},
"name": "execute_trade"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tp | No | Take-profit price (> 0) armed with the entry as a single 100%-share venue-native TP exit leg across all CEX venues. Must sit on the profit side of the entry (long: above, short: below). | |
| pair | Yes | e.g. BTC/USDT | |
| side | Yes | Order side: buy|sell | |
| stop | No | Protective stop price (> 0). Gated server-side: stops inside round-trip fees x factor are refused with the shortfall spelled out, and armed as a venue-native SL exit leg after the entry across all CEX venues. | |
| type | No | Order type. Defaults to 'limit' when a price is given, else 'market'. Use 'market' for a live entry: the exit legs are venue-native conditionals that attach to a POSITION, so a RESTING LIMIT has no position to protect and rests on the book unprotected until it fills. | |
| actor | No | WHO is placing the order. 'machine' for the trading machine; 'owner' for the account owner's own manual trading. The account is SHARED, so this is what tells the machine's trades from the owner's when a closed trade is reconciled against the machine's daily loss cap. Defaults to 'owner'. | |
| price | No | Limit price. OMIT for a market order. When the order type is 'market' the price is only a reference for sizing and is NOT sent to the venue — a resting limit has no position to protect, so the exit legs cannot attach to it. | |
| amount | No | Base units, e.g. 0.05 (omit when risk_usd sizes the order) | |
| market | No | Which market to trade (default spot) | |
| tpLegs | No | Optional 1-3 split take-profit legs ({ price, share }, where share is 1..100 percent of entry size) armed as venue-native TP orders after the entry. | |
| tpPrice | No | Deprecated alias of tp. | |
| exchange | Yes | CEX slug, e.g. kucoin | |
| leverage | No | Futures only; rides the order (KuCoin has no venue-level setting) | |
| risk_usd | No | Max USD loss at the stop — sizes the order as risk_usd / stop distance (needs stop, else ATR stop from venue klines; capped by max_position_usd + lot step). | |
| clientOid | No | Optional caller-supplied identity tag for the order (max 36 chars, [A-Za-z0-9_-]). A later session uses it to attribute the order to its owner instead of classifying it as foreign/unknown-origin. Omit it and the server generates a random UUID. | |
| marginMode | No | Futures only; isolated bounds max loss to position margin (default cross) | |
| connectionId | No | CEX connection id (see list_connections). Takes precedence over exchange. | |
| referencePrice | No | For a MARKET order only: the price the exit legs were derived from. The venue may fill the entry at a different price, and the server REBASES the stop and target onto the actual fill (each keeps its distance from this reference). Omit it and the legs are placed at their original absolute prices, which can land on the wrong side of the fill. | |
| idempotency_key | No | Optional per-INTENT key. Two submits with the same key are the same intent: the second is deduped and never dispatched again. Use it when a submission may be retried (a timeout, a reconnect) so a retry cannot double-fill. |