Place spot order
place_spot_orderPlace a simulated spot order on a paper trading account. Supports market, limit, and stop types. Use a unique idempotency key to safely retry timed-out requests without double execution.
Instructions
Place a paper spot order. coinId is a coin UCID, NOT a ticker. orderType market/limit/stop. limitPrice required for limit & stop; stopPrice required for stop. idempotencyKey is REQUIRED and unique per intent (reuse replays the original result — retry a timed-out call with the SAME key; it will never double-execute). Requires the trade:spot scope. CONFIRM with the user before calling. Paper trading only — virtual funds (50,000 mUSD). Not financial advice. Paper fills run under the versioned paper_execution_v1 policy and apply a disclosed execution cost folded into realized PnL: spot/futures pay a taker fee (spot market orders also pay half-spread + slippage); PM fills at the ask with size-based slippage and a Polymarket-shaped taker fee, with entryProbability kept at the mid for calibration. See the executionModel in quote/trade results — a rehearsal cost, not an exchange fill guarantee.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| side | Yes | Spot side: buy spends USDT; sell spends the base coin. | |
| coinId | Yes | Coin UCID (e.g. "1" = BTC). | |
| quantity | Yes | Base-coin amount (> 0). | |
| orderType | Yes | Order execution type: market, limit, or stop. | |
| stopPrice | No | USD trigger — required for stop. | |
| agentTrace | No | Optional private trace metadata stored in the caller's ledger. | |
| limitPrice | No | USD/coin — required for limit & stop. | |
| idempotencyKey | Yes | Unique per intent; reuse replays the original result. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | True when CoinRithm returned a successful 2xx response. | |
| body | No | Parsed CoinRithm response body, or raw text when the response is not JSON. | |
| httpStatus | Yes | HTTP status returned by CoinRithm, or 0 for network errors. | |
| ledgerStatus | No | Ledger write status header returned by CoinRithm, when present. | |
| ledgerEventId | No | Private AgentActionEvent id returned by /api/agent/*, when present. |