{ "openapi": "3.1.0", "info": { "title": "Clobber API", "version": "v1", "summary": "A hosted central limit order book: markets, accounts, orders, fills, settlement and webhooks over REST.", "description": "Clobber runs the matching engine, the double entry ledger inside it, and its durability and failover; you define currencies and markets, fund accounts, send orders and declare outcomes. Money and quantities are decimal strings (\"0.61\", never 0.61). Timestamps are RFC 3339 in UTC. Every write accepts an Idempotency-Key. Live book deltas, trades and private order events stream over the WebSocket feed at wss://feed.clobberhq.com, described at https://docs.clobberhq.com/#websocket. Generated from the published contract, https://docs.clobberhq.com/, which wins wherever the two disagree.\n\nVersioning and deprecation: the version is in the path (/v1). Additive changes (new fields, endpoints, enum values) ship without a version bump, so ignore fields you do not recognise. A breaking change ships as a new version, and the version it supersedes is deprecated, not removed: it keeps serving for at least 12 months of overlap before its sunset, and every change is listed in the changelog, https://docs.clobberhq.com/#changelog.", "contact": { "name": "Clobber", "url": "https://clobberhq.com/contact/", "email": "support@clobberhq.com" }, "termsOfService": "https://clobberhq.com/legal/terms/" }, "x-api-lifecycle": { "versioning": "path", "deprecationPolicy": "https://docs.clobberhq.com/#changelog", "minimumSunsetNoticeMonths": 12 }, "externalDocs": { "description": "The API reference", "url": "https://docs.clobberhq.com/" }, "servers": [ { "url": "https://api-sandbox.clobberhq.com", "description": "Sandbox" }, { "url": "https://api.clobberhq.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication" }, { "name": "Markets" }, { "name": "Accounts" }, { "name": "Orders" }, { "name": "Fills & trades" }, { "name": "Candles" }, { "name": "Webhooks" } ], "paths": { "/v1/accounts/{id}/keys": { "post": { "operationId": "createAccountKey", "summary": "Mints an account key for this account", "description": "Mints an account key for this account. Requires an admin or trading key. Same key material can also be minted from the dashboard, on the account's own page, for teams that would rather not wire a backend call for something a support workflow does by hand.\n\nThe key field is returned only in this response. Store it in the account holder's own client; Clobber never shows it again.", "tags": [ "Authentication" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "account": { "type": "string" }, "key": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "ak_7mQ2...", "account": "acc_2fRk8Wq4vNc6", "key": "ck_acct_live_9pL4vXq2...", "created_at": "2026-09-03T14:20:00Z" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listAccountKeys", "summary": "Lists this account's keys by id, prefix and created_at/last_used_at", "description": "Lists this account's keys by id, prefix and created_at/last_used_at. Never returns key material.", "tags": [ "Authentication" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts/{id}/keys/{key_id}": { "delete": { "operationId": "revokeAccountKey", "summary": "Revokes a key immediately", "description": "Revokes a key immediately. A revoked account key fails closed like any other: invalid_api_key, not a partial grant.", "tags": [ "Authentication" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The account key's id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/markets": { "post": { "operationId": "createMarket", "summary": "Creates a market", "description": "Creates a market. Returns the market object with status open unless you pass \"status\": \"draft\".", "tags": [ "Markets" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Unique per environment. Uppercase letters, digits and hyphens, 3–48 characters." }, "kind": { "type": "string", "enum": [ "binary", "scalar", "pair" ], "description": "binary, scalar or pair." }, "tick_size": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "Minimum price increment. Prices not on the tick grid are rejected." }, "settlement_currency": { "type": "string", "description": "Currency positions settle in. Any code you have configured, including play-money units." }, "base_currency": { "type": "string", "description": "The asset a pair market trades against the settlement currency. Required for pair, rejected for binary and scalar, which trade contracts rather than an asset." }, "lot_size": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "Minimum quantity increment. Defaults to \"1\"." }, "min_price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "Floor. Defaults to \"0\"." }, "max_price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "Ceiling. Defaults to \"1\" for binary markets, which settle at one or zero; required for scalar and pair, where nothing implies a ceiling and a market order sweeps to it." }, "maker_fee_bps": { "type": "integer", "description": "Basis points charged to the resting side. May be negative to pay a rebate. Default 0." }, "taker_fee_bps": { "type": "integer", "description": "Basis points charged to the aggressing side. Default 0." }, "closes_at": { "type": "string", "format": "date-time", "description": "When trading stops automatically. The market moves to closed." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 16 key/value pairs of your own. Returned on every market object, never interpreted." } }, "required": [ "symbol", "kind", "tick_size", "settlement_currency" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "symbol": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "tick_size": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "lot_size": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "min_price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "max_price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "settlement_currency": { "type": "string" }, "maker_fee_bps": { "type": "integer" }, "taker_fee_bps": { "type": "integer" }, "closes_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "properties": {} } } }, "example": { "id": "mkt_8Kd2nQr5vXw9", "symbol": "WILL-IT-RAIN-BA", "kind": "binary", "status": "open", "tick_size": "0.01", "lot_size": "1", "min_price": "0.00", "max_price": "1.00", "settlement_currency": "USDC", "maker_fee_bps": 0, "taker_fee_bps": 20, "closes_at": "2026-08-01T03:00:00Z", "created_at": "2026-07-29T14:22:07Z", "metadata": {} } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listMarkets", "summary": "Lists markets, ordered by symbol, so pages stay stable while markets are being created", "description": "Lists markets, ordered by symbol, so pages stay stable while markets are being created. Filter with status, kind or symbol_prefix; page with cursors.", "tags": [ "Markets" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on status." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on kind." }, { "name": "symbol_prefix", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on symbol_prefix." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/markets/{symbol}": { "get": { "operationId": "getMarket", "summary": "Fetches one market by symbol or by id", "description": "Fetches one market by symbol or by id. Includes last_price, best_bid, best_ask and rolling volume_24h.", "tags": [ "Markets" ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market symbol or market id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateMarket", "summary": "Updates a market", "description": "Updates a market. Only status, closes_at, the fee fields and metadata are mutable once a market is open. Set status to halted to pause trading while preserving the book, then back to open to resume.\n\nLegal status moves: draft to open; open to halted or closed; halted to open or closed; and closed back to open, which reopens a market that has not resolved. Setting the status a market already has is an idempotent no-op. Any other move answers 400 invalid_request; resolved and settled are only reachable through resolve.", "tags": [ "Markets" ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market symbol or market id." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "halted", "closed" ], "description": "Legal moves: draft to open; open to halted or closed; halted to open or closed; closed back to open." }, "closes_at": { "format": "date-time", "type": "string" }, "maker_fee_bps": { "type": "integer" }, "taker_fee_bps": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/markets/{symbol}/book": { "get": { "operationId": "getOrderBook", "summary": "A point-in-time snapshot of the book, aggregated by price level", "description": "A point-in-time snapshot of the book, aggregated by price level. depth caps levels per side (default 20, max 500). The seq in the response is the snapshot's position in the market's event stream, the anchor you use when joining the live feed.", "tags": [ "Markets" ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market symbol or market id." }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 20 }, "description": "Price levels per side." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string" }, "seq": { "type": "integer" }, "bids": { "type": "array", "items": { "type": "array", "items": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." } } }, "asks": { "type": "array", "items": { "type": "array", "items": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." } } }, "as_of": { "type": "string", "format": "date-time" } } }, "example": { "symbol": "WILL-IT-RAIN-BA", "seq": 48210, "bids": [ [ "0.61", "250" ], [ "0.60", "812" ] ], "asks": [ [ "0.62", "140" ], [ "0.63", "930" ] ], "as_of": "2026-07-29T14:31:55.204Z" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/markets/{symbol}/resolve": { "post": { "operationId": "resolveMarket", "summary": "Declares the outcome and settles every position atomically", "description": "Markets", "tags": [ "Markets" ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market symbol or market id." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "description": "For binary: yes, no or void. For scalar: a decimal inside the market's range." }, "evidence_url": { "type": "string", "description": "A link to your source of truth. Stored on the market and echoed to every participant." }, "cancel_resting": { "type": "boolean", "description": "Cancel any orders still on the book first. Default true; a market cannot resolve with live orders." } }, "required": [ "outcome" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts": { "post": { "operationId": "createAccount", "summary": "Creates an account for one of your users", "description": "Accounts", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "Your own identifier for the user. Unique per environment; we index it so you can look accounts up by it." }, "display_name": { "type": "string", "description": "Shown in any Clobber-rendered surface. Never used for matching." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 16 key/value pairs of your own." } }, "required": [ "reference" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listAccounts", "summary": "Lists accounts, sorted by id, with cursor pagination", "description": "Lists accounts, sorted by id, with cursor pagination. Pass reference to resolve your own user identifier to its account: the reference is unique per environment, so the filter answers at most one row.", "tags": [ "Accounts" ], "parameters": [ { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on reference." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts/{id}/balances": { "get": { "operationId": "getBalances", "summary": "Returns one entry per currency held", "description": "Returns one entry per currency held. total is everything the account owns; held is collateral locked behind resting orders; available is what a new order can spend.", "tags": [ "Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string" }, "balances": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "total": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "held": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "available": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." } } } } } }, "example": { "account": "acc_2fRk8Wq4vNc6", "balances": [ { "currency": "USDC", "total": "1000.00", "held": "152.50", "available": "847.50" } ] } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts/{id}/positions": { "get": { "operationId": "getPositions", "summary": "Open positions per market, with qty (negative when short), avg_price, and unrealized_pnl marked against the last trade", "description": "Open positions per market, with qty (negative when short), avg_price, and unrealized_pnl marked against the last trade.", "tags": [ "Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts/{id}/credits": { "post": { "operationId": "creditAccount", "summary": "Credits or debits an account in one currency", "description": "Takes currency, amount, and an optional reason string that is stored with the ledger entry and returned by the account ledger endpoint. Use it: a manual adjustment nobody can explain six months later is worse than no adjustment at all.\n\nMoves value into or out of an account: positive amount credits, negative debits. This is the seam between Clobber and your funding system: call it when a deposit clears on your side, and again when a withdrawal is confirmed.\n\nThe balance in the response is the account's position in that currency after the credit applied, so a funding flow needs no follow-up read.", "tags": [ "Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "amount" ], "properties": { "currency": { "type": "string", "description": "A configured currency code." }, "amount": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "Positive credits, negative debits." }, "reason": { "type": "string", "description": "Stored with the ledger entry and returned by the ledger." } } } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "reason": { "type": "string" }, "balance": { "type": "object", "properties": { "currency": { "type": "string" }, "total": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "held": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "available": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." } } }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "account": "acc_2fRk...", "currency": "USDC", "amount": "500.00", "reason": "initial deposit", "balance": { "currency": "USDC", "total": "500.00", "held": "0.00", "available": "500.00" }, "created_at": "2026-07-29T14:24:11Z" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/accounts/{id}/ledger": { "get": { "operationId": "getLedger", "summary": "The full double-entry history for an account: credits, holds, fills, fees and settlements, each with the seq and object that caused it", "description": "The full double-entry history for an account: credits, holds, fills, fees and settlements, each with the seq and object that caused it. This is the endpoint to reconcile against if you keep your own books.", "tags": [ "Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/currencies": { "get": { "operationId": "listCurrencies", "summary": "Lists the currencies configured in this environment", "description": "Lists the currencies configured in this environment.", "tags": [ "Accounts" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createCurrency", "summary": "Configures a currency code and its scale", "description": "There is no delete: a currency that appears in ledger history is part of the audit trail forever. Creating a market or a credit against a code you have not configured answers 400 invalid_request naming the field.", "tags": [ "Accounts" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Uppercase letters and digits, 2 to 10 characters. Unique per environment." }, "scale": { "type": "integer", "description": "Decimal places, 0 to 8. Immutable once created: a wrong scale means a new code, never a re-denomination of existing balances." }, "name": { "type": "string", "description": "A display name for your own surfaces." } }, "required": [ "code", "scale" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "scale": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "code": "GEMS", "scale": 0, "name": "Gems", "created_at": "2026-07-29T14:20:00Z" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders": { "post": { "operationId": "placeOrder", "summary": "Submits an order", "description": "Submits an order. Requires the Clobber-Account header. Returns once the engine has processed it, so the response already reflects any fills that happened on entry.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ClobberAccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "type": "string", "description": "Symbol or market id." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "buy or sell." }, "type": { "type": "string", "enum": [ "limit", "market" ], "description": "limit or market." }, "qty": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "Quantity in contracts. Must be a multiple of the market's lot_size." }, "price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "Required for limit orders, forbidden for market. Must sit on the tick grid." }, "time_in_force": { "type": "string", "enum": [ "gtc", "ioc", "fok", "day" ], "description": "gtc (default), ioc, fok or day. See order types." }, "post_only": { "type": "boolean", "description": "Reject rather than take liquidity. Guarantees the maker fee. Default false." }, "reduce_only": { "type": "boolean", "description": "Only shrink an existing position; never open or flip one. Default false." }, "client_order_id": { "type": "string", "description": "Your identifier, echoed on every event about this order. Unique per account." }, "expires_at": { "type": "string", "format": "date-time", "description": "Cancels automatically at this time. Only valid with gtc." }, "self_trade_prevention": { "type": "string", "enum": [ "cancel_maker", "cancel_taker", "decrement" ], "description": "cancel_maker (default), cancel_taker or decrement." } }, "required": [ "market", "side", "type", "qty" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "client_order_id": { "type": "string" }, "account": { "type": "string" }, "market": { "type": "string" }, "side": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "qty": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "filled_qty": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "remaining_qty": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "avg_fill_price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "status": { "type": "string" }, "time_in_force": { "type": "string" }, "fees_paid": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "seq": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "fills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "qty": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "liquidity": { "type": "string" } } } } } }, "example": { "id": "ord_5Tn7cWy2gLp8", "client_order_id": "alice-bid-0001", "account": "acc_2fRk8Wq4vNc6", "market": "WILL-IT-RAIN-BA", "side": "buy", "type": "limit", "price": "0.61", "qty": "250", "filled_qty": "140", "remaining_qty": "110", "avg_fill_price": "0.6071", "status": "partially_filled", "time_in_force": "gtc", "fees_paid": "0.17", "seq": 48211, "created_at": "2026-07-29T14:31:55.201Z", "fills": [ { "id": "fil_9Qw3", "price": "0.61", "qty": "100", "liquidity": "taker" }, { "id": "fil_9Qw4", "price": "0.60", "qty": "40", "liquidity": "taker" } ] } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listOrders", "summary": "Lists orders for the account in the Clobber-Account header, newest first", "description": "Lists orders for the account in the Clobber-Account header, newest first. Filter by market, status or client_order_id. Omit the header with an admin key to query across all accounts.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ClobberAccount" }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on market." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on status." }, { "name": "client_order_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on client_order_id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Fetches one order and its fills", "description": "Fetches one order and its fills. Accepts either a Clobber order id or your client_order_id prefixed with cid:.", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "$ref": "#/components/parameters/ClobberAccount" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "cancelOrder", "summary": "Cancels a resting order", "description": "Cancels a resting order. Idempotent: cancelling an already-terminal order returns 200 with the order unchanged rather than an error, so retries are always safe.", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "$ref": "#/components/parameters/ClobberAccount" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/cancel_all": { "post": { "operationId": "cancelAllOrders", "summary": "Cancels every resting order for an account, optionally scoped to one market", "description": "Cancels every resting order for an account, optionally scoped to one market. Returns the list of cancelled ids. This is the panic button: wire it to your own kill switch.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ClobberAccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "type": "string", "description": "Only this market's orders." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orders/batch": { "post": { "operationId": "batchOrders", "summary": "Submits up to 100 entries in one request", "description": "Submits up to 100 entries in one request. Each is processed independently and in array order; the response array mirrors the input positionally, with a per-entry error where one failed. A rejected entry never aborts the rest.\n\nAn entry is a placement by default, or a cancel when it carries \"op\": \"cancel\" and the order_id to cancel. This is how you move a ladder: cancel what is up and place what replaces it in the same request, instead of a cancel_all followed by a batch, which leaves your book empty on both sides for a round trip in between. Entries are applied in array order with nothing else of yours in between, so put the cancels first.\n\nA cancel entry answers with the order's id and status rather than a full order body, because a cancel names an id and the response is not a read. Cancelling an order that already reached a terminal state is not an error here, exactly as it is not on DELETE /v1/orders/{id}: the entry reports the state the order actually reached, so a maker requoting against active takers can cancel a ladder without special-casing the levels that filled while the request was in flight.\n\n{ \"orders\": [\n\n{ \"op\": \"cancel\", \"order_id\": \"ord_4Bv8kNs2\" },\n\n{ \"op\": \"cancel\", \"order_id\": \"ord_9Kq2mXp7\" },\n\n{ \"market\": \"RAIN-BA-0908\", \"side\": \"buy\", \"type\": \"limit\", \"price\": \"0.51\", \"qty\": \"5\" },\n\n{ \"market\": \"RAIN-BA-0908\", \"side\": \"sell\", \"type\": \"limit\", \"price\": \"0.53\", \"qty\": \"5\" }\n\n] }\n\nThe batch is not one atomic operation and does not claim to be: every entry is its own command, journaled on its own, and able to fail on its own. What it gives you is adjacency, which is what an order book needs.", "tags": [ "Orders" ], "parameters": [ { "$ref": "#/components/parameters/ClobberAccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "orders" ], "properties": { "orders": { "type": "array", "maxItems": 100, "description": "Placements (the POST /v1/orders body) or cancels ({\"op\": \"cancel\", \"order_id\": ...}), applied in array order.", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "cancel" ] }, "order_id": { "type": "string" }, "market": { "type": "string" }, "side": { "type": "string", "enum": [ "buy", "sell" ] }, "type": { "type": "string", "enum": [ "limit", "market" ] }, "price": { "type": "string" }, "qty": { "type": "string" }, "time_in_force": { "type": "string", "enum": [ "gtc", "ioc", "fok", "day" ] }, "client_order_id": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/markets/{symbol}/trades": { "get": { "operationId": "listTrades", "summary": "Public tape for a market, newest first: price, quantity, aggressing side and seq", "description": "Public tape for a market, newest first: price, quantity, aggressing side and seq. No account information is exposed.\n\nside is the aggressing (taker) side. Pagination is by seq: pass next_cursor back as cursor to walk older trades.", "tags": [ "Fills & trades" ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market symbol or market id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "qty": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "side": { "type": "string" }, "seq": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": "string" } } }, "example": { "data": [ { "id": "trd_4Bv8kNs2", "price": "0.61", "qty": "100", "side": "buy", "seq": 48211, "created_at": "2026-07-29T14:31:55.201Z" } ], "next_cursor": "cur_NDgyMTE" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/fills": { "get": { "operationId": "listFills", "summary": "Your side of the tape: one row per execution for the account in the header, including liquidity (maker or taker), the fee charged, and the order and trade it belongs to", "description": "Your side of the tape: one row per execution for the account in the header, including liquidity (maker or taker), the fee charged, and the order and trade it belongs to. Filter by market, order, or a since timestamp.", "tags": [ "Fills & trades" ], "parameters": [ { "$ref": "#/components/parameters/ClobberAccount" }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on market." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on order." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on since." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "trade": { "type": "string" }, "order": { "type": "string" }, "market": { "type": "string" }, "side": { "type": "string" }, "price": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "qty": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "liquidity": { "type": "string" }, "fee": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "seq": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": "string" } } }, "example": { "data": [ { "id": "fil_9Qw3mZx1", "trade": "trd_4Bv8kNs2", "order": "ord_5Tn7cWy2gLp8", "market": "WILL-IT-RAIN-BA", "side": "buy", "price": "0.61", "qty": "100", "liquidity": "taker", "fee": "0.12", "seq": 48211, "created_at": "2026-07-29T14:31:55.201Z" } ], "next_cursor": "cur_MTQ4MjEx" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/markets/{symbol}/candles": { "get": { "operationId": "getCandles", "summary": "OHLCV candles of the public tape, aligned to UTC", "description": "Buckets are aligned to UTC, always, and there is no timezone parameter: a client that wants local days aggregates hourly candles itself. Buckets in which nothing traded are omitted rather than zero-filled; a prediction market can sit quiet for hours, and a gap in time is not a gap in data. A response is capped at 1000 candles, and a wider range answers 400 invalid_request naming from. There is no cursor: narrow the range instead, which is what every charting client does anyway.\n\nThe last candle may be the one still forming, marked \"closed\": false, so a single call is enough for a first render; only the last can be open. volume is in quantity units, the same scale as an order's qty, not notional. time is the bucket's open. A market that has never traded answers 200 with an empty candles array, not 404.", "tags": [ "Candles" ], "parameters": [ { "name": "symbol", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Market symbol or market id." }, { "name": "interval", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "1m", "5m", "1h", "1d" ], "description": "Exactly 1m, 5m, 1h or 1d. Arbitrary durations are never accepted." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Inclusive start. Defaults to to minus 500 buckets." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Exclusive end. Defaults to now." } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "type": "string" }, "interval": { "type": "string" }, "candles": { "type": "array", "items": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time" }, "open": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "high": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "low": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "close": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "volume": { "type": "string", "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "description": "A decimal string, never a JSON number." }, "trades": { "type": "integer" }, "closed": { "type": "boolean" } } } } } }, "example": { "market": "WILL-IT-RAIN-BA", "interval": "1m", "candles": [ { "time": "2026-07-29T14:31:00Z", "open": "0.60", "high": "0.62", "low": "0.59", "close": "0.61", "volume": "1250", "trades": 14, "closed": true }, { "time": "2026-07-29T14:32:00Z", "open": "0.61", "high": "0.61", "low": "0.61", "close": "0.61", "volume": "75", "trades": 2, "closed": false } ] } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks": { "post": { "operationId": "createWebhook", "summary": "Registers an endpoint for webhook deliveries", "description": "The secret keys the Clobber-Signature HMAC below and is shown once, at creation. Store it; it is never returned again.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Where deliveries POST. https only." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Which events to deliver, from the list above." }, "description": { "type": "string", "description": "A label for your own bookkeeping." } }, "required": [ "url", "events" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" }, "secret": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "example": { "id": "wh_4kTm...", "url": "https://api.example.com/clobber", "events": [ "market.settled", "order.filled" ], "status": "enabled", "secret": "whsec_Zx81...", "created_at": "2026-07-29T14:18:30Z" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listWebhooks", "summary": "Lists your registrations, without secrets", "description": "Lists your registrations, without secrets. status is enabled normally and suspended for an endpoint we have stopped queueing for, which also carries suspended_at, suspended_reason and the running dropped_events count. That count is history: it survives the resume, because after you fix your server the question you have is how much you missed.", "tags": [ "Webhooks" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/resume": { "post": { "operationId": "resumeWebhook", "summary": "Puts a suspended endpoint back in service now, rather than waiting for the hourly probe, and answers with the registration", "description": "Puts a suspended endpoint back in service now, rather than waiting for the hourly probe, and answers with the registration. Requires an admin key, takes no body, and is idempotent: resuming an endpoint that is already live leaves it live and answers 200. Deliveries dropped while it was suspended are gone; the events themselves are still readable through the REST surface (orders, fills, ledger, positions), which is the reconciliation path after an outage.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}": { "delete": { "operationId": "deleteWebhook", "summary": "Stops deliveries immediately and answers the registration with status disabled", "description": "Stops deliveries immediately and answers the registration with status disabled. There is no partial update: to change a URL or rotate a secret, create the replacement first, then delete the old one.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "What this registration has been sent, newest first: the event, its type, the state of the delivery (pending, delivered, failed after the 24 hour window, or cancelled because it will never be sent: the registration was deleted, or its endpoint was suspended while this delivery was queued), how many attempts it has had, and when the next one is due", "description": "What this registration has been sent, newest first: the event, its type, the state of the delivery (pending, delivered, failed after the 24 hour window, or cancelled because it will never be sent: the registration was deleted, or its endpoint was suspended while this delivery was queued), how many attempts it has had, and when the next one is due. Filter with status and since; paginate with cursor and limit like every other listing. This is where an endpoint that answered 500 shows up, before anybody has to ask us.\n\nEvery row carries what your endpoint answered on the last attempt that reached it. last_status is the HTTP status, null while the delivery has not been attempted yet and 0 when the request never got a response at all, in which case last_error says what failed (a DNS answer, a refused connection, a TLS handshake, a timeout). last_duration_ms is how long that attempt took, and last_body is the first 512 bytes your endpoint wrote back, cut on a character boundary and stripped of control characters; both are omitted when there is nothing to report. attempts counts every time we knocked, the successful knock included.\n\nThe listing does not echo the payload we sent: it is your own event, and you either received it or you will.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on status." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter on since." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Rows per page." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "next_attempt": { "type": "string", "format": "date-time" }, "last_status": { "type": "integer" }, "last_duration_ms": { "type": "integer" }, "last_body": { "type": "string" } } } }, "next_cursor": { "type": [ "string", "null" ] } } }, "example": { "data": [ { "event": "evt_7Kq2mZ", "type": "order.filled", "status": "pending", "attempts": 3, "created_at": "2026-07-29T14:31:55.201Z", "next_attempt": "2026-07-29T14:35:55.201Z", "last_status": 500, "last_duration_ms": 84, "last_body": "{\"error\":\"unhandled event type\"}" }, { "event": "evt_4Bv8kN", "type": "order.filled", "status": "delivered", "attempts": 1, "created_at": "2026-07-29T14:31:55.201Z", "delivered_at": "2026-07-29T14:31:55.640Z", "last_status": 200, "last_duration_ms": 31 } ], "next_cursor": null } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries/{event}": { "get": { "operationId": "getWebhookDelivery", "summary": "One delivery, by the event id the listing hands out, with the same fields", "description": "One delivery, by the event id the listing hands out, with the same fields. The listing walks newest first, so following a single delivery through it means paging past everything queued since; this is that read in one request, and it is how you watch a delivery you have just retried until it settles. A delivery this registration does not have, including one the 3 day sweep has already taken, answers 404 not_found.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "name": "event", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The event id the deliveries listing hands out." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/{id}/deliveries/{event}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Sends one delivery again, now", "description": "Sends one delivery again, now. Two cases: the outage longer than the retry window (your endpoint was down for a day, the ladder ran out, the delivery reads failed, and the event is one you cannot reconstruct from a listing), and the delivery still on the ladder, whose next attempt is up to an hour away because that is where the backoff caps. The row goes back in the queue due immediately, with a fresh 24 hour window from the retry, and attempts keeps counting rather than resetting, so the record of how many times we knocked stays true. Requires an admin key, takes no body, and answers 200 with the delivery in its new state.\n\nEvery state is retryable. A pending one is pulled forward to due now, which is the point while you are fixing the endpoint it is waiting on: an hour of backoff is not something to sit through. A delivered one can be retried too, and your handler will see the event twice, which is what being idempotent on event.id is for. The endpoint takes no Idempotency-Key, because a repeat call is already answered by the state of the row.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object's id." }, { "name": "event", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The event id the deliveries listing hands out." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "next_attempt": { "type": "string", "format": "date-time" } } }, "example": { "event": "evt_7Kq2mZ", "type": "order.filled", "status": "pending", "attempts": 9, "created_at": "2026-07-29T14:31:55.201Z", "next_attempt": "2026-07-30T09:02:11.004Z" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/feed_tokens": { "post": { "operationId": "createFeedToken", "summary": "Mints a short lived, read only feed token scoped to one market, for a browser to authenticate to the WebSocket feed", "description": "Mints a short lived, read only feed token scoped to one market, for a browser to authenticate to the WebSocket feed. It expires in 15 minutes. Any key role can mint one, including read_only.", "tags": [ "Authentication" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "market": { "type": "string", "description": "Symbol or market id the token grants." } }, "required": [ "market" ] } } } }, "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "market": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } }, "example": { "token": "ft_9hK2...", "market": "WILL-IT-RAIN-BA", "expires_at": "2026-07-29T14:47:00Z" } } } }, "400": { "description": "Error: account_required, account_key_scope, invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error: invalid_api_key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error: insufficient_role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error: order_not_cancellable, idempotency_key_reused, market_not_resolvable, already_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error: invalid_tick, invalid_lot, price_out_of_bounds, insufficient_balance, market_halted, would_take_liquidity, self_trade_blocked, limit_exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error: internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Error: not_implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error: cell_halted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Any other failure, in the same shape.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key: ck_test_ or ck_live_ for an environment key, ck_acct_test_ or ck_acct_live_ for an account key." } }, "parameters": { "ClobberAccount": { "name": "Clobber-Account", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The sub-account the request acts for. Required on order endpoints with an environment key; omitted with an account key, which already names its account." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "A unique key per logical request (a UUID is ideal). A repeat within 24 hours replays the stored response verbatim." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "account_required", "account_key_scope", "invalid_request", "invalid_api_key", "insufficient_role", "not_found", "invalid_tick", "invalid_lot", "price_out_of_bounds", "insufficient_balance", "market_halted", "would_take_liquidity", "self_trade_blocked", "limit_exceeded", "order_not_cancellable", "idempotency_key_reused", "market_not_resolvable", "already_exists", "rate_limited", "internal", "cell_halted", "not_implemented" ], "description": "Stable and machine readable: branch on this, never on the message." }, "message": { "type": "string", "description": "For a human, and says how to fix it." }, "param": { "type": [ "string", "null" ], "description": "The field the error is about, when there is one." }, "request_id": { "type": "string", "description": "Quote it to support." } } } } } } } }