execute_previewed_order
Execute a previewed order · changes money or positions: confirm first, idempotent ·
scopes: trade:propose
Execute a preview from preview_perp_order: re-checked at a fresh price, then sent to the exchange with its stop-loss placed there. Use only after a successful preview. Not for new or changed orders (preview again). If a person must approve (propose level, or no trade:execute scope) it waits; wait_seconds (0-30) holds the call open for the decision. Inputs: preview_id, client_order_id (idempotency key: repeating it returns the first result). A fill cannot be undone; the remedy is close_perp_position_reduce_only. Next: get_order_request_status(request_id) while pending.
Call it
MCP tools/call
{"name": "execute_previewed_order", "arguments": {"preview_id": "pv_\u2026", "client_order_id": "my-order-1"}}REST
POST /v1/orders
{"preview_id": "pv_\u2026", "client_order_id": "my-order-1"}Inputs
| Name | Meaning (* required) |
|---|---|
preview_id * | From preview_perp_order, within 30 seconds |
client_order_id * | Your idempotency key, unique per agent; repeating it returns the first result instead of a second order |
wait_seconds | If the order needs a person's approval, wait up to this long for the decision before returning |
Returns
| Field | Meaning and unit |
|---|---|
ok | False when rejected or failed |
request_id | Order request id; get_order_request_status(request_id) follows it |
status | pending_approval, armed (a trigger entry waiting for its price), executed, rejected, failed, expired, declined, cancelled, or executing (TradeHub has not confirmed the outcome yet: check get_order_request_status) |
venue | Venue name |
order_id | Venue order id of the fill |
sl_oid | Venue order id of the protective stop |
fill_price | Average fill, USD per coin |
filled_size | Filled size, in the base coin (e.g. BTC), not USD |
approval_expires_at | While pending: when the approval request lapses, ISO 8601 UTC |
error | Why it was rejected or failed |
checks | Checks run at execution |
receipt | Signed receipt (compact JWS, EdDSA) once executed: request, checks, preview price, fill, slippage, order ids, delegation. Verify with /.well-known/tradehub-receipts.jwks |
take_profits | set_take_profit_levels: the take-profits now on the exchange |
trigger_price | status armed: opens at market when the mark reaches this, USD per coin |
trigger_expires_at | status armed: when it lapses unless reached, ISO 8601 UTC |
fee | Once executed: the trading fee, estimated at once and replaced by the amount the exchange charged once its fill records show it |
Rejections: error codes, each with what to do.