{ "openapi": "3.1.0", "info": { "title": "Kairos Partner API", "version": "1.0.0", "description": "Self-custody trading for wallets and apps: Kairos builds each step, the user's wallet signs it. Every operation is under `/v3`. Guides: https://docs.kairos.trade/wallets/overview" }, "servers": [ { "url": "https://execution.kairos.trade", "description": "Production" }, { "url": "https://staging-execution.kairos.trade", "description": "Staging" } ], "tags": [ { "name": "Actions", "description": "Start `setup`, `order`, `cancel` and `login` actions and answer their steps. Live. Send `X-Kairos-Wallet-Api: 2`." }, { "name": "Reads", "description": "Wallet readiness and balances per venue (partner id or API key, no wallet proof), and the wallet's orders and positions (also needs `Authorization: SIWE ` from a `login` action). Live." }, { "name": "Trade plans (preview)", "description": "One buy order authorized up front in one signature batch, with a fee ceiling and deadlines, optionally funded by bridging the exact shortfall from Polygon or Arbitrum USDC. Preview: staging only; production returns `503` until release." }, { "name": "Fees (preview)", "description": "Trading fees from trade plans accrue as a debt per wallet and are paid in one settlement — a gasless signature on Polymarket, a USDT transfer on Predict.fun. Preview: staging only." }, { "name": "On-chain intents (preview)", "description": "Split, merge or redeem conditional tokens on a Polymarket deposit wallet with two signatures and no gas; Kairos confirms from the finalized receipt. Preview: staging only; production returns `503` until release." } ], "paths": { "/v3/actions": { "post": { "operationId": "startWalletAction", "summary": "Start a wallet action (setup, order, cancel, login)", "description": "Starts one action for a self-custody wallet and returns its first **step**. Kairos never holds the wallet's key: each step either asks the wallet for one EIP-1193 request (`status: needs_signature`) or reports progress (`working`) or the outcome (`done` / `failed`).\n\n**The step loop.**\n1. `POST /v3/actions` → a step.\n2. While `status` is `needs_signature`: switch the wallet to `chainId` (when non-null), run `request` through the wallet's EIP-1193 provider, and `POST /v3/actions/{id}` with `{\"signature\": \"0x…\"}` (or `{\"result\": …}` for `wallet_sendCalls`). Answer before `expiresAtMs`.\n3. While `status` is `working`: `GET /v3/actions/{id}` every 1–2 s (or after `holdUntilMs` when present).\n4. Stop at `done` (read `result`) or `failed` (read `error` and `errorCode`).\n\n**Action types.** `setup` prepares the wallet on each requested venue; `order` places one order and runs any missing setup first, in the same action; `cancel` cancels orders on every venue with one Polygon signature; `login` returns a sign-in token for the private reads. There are no other action types.\n\n**Body rules.** Field names are **camelCase only**: unknown fields — including snake_case spellings such as `time_in_force`, `post_only`, `client_order_id`, `expires_at`, `order_ids` — are silently ignored, so a snake_case order becomes a `GTC`, non-post-only order without a client id. `price` and `size` must be JSON **strings**; a JSON number is rejected with a plain-text `422`. `expiresAt` is an integer (Unix seconds).\n\n**Idempotency.** `Idempotency-Key` is **not** honoured here. Use `clientOrderId` on orders: the same `clientOrderId` with the same terms returns the existing order (nothing is signed), and different terms are refused with `CLIENT_ORDER_ID_CONFLICT`.\n\n**Timing.** An action lives 15 minutes from creation and stays readable for 10 more minutes, then reads `404`. Polymarket and Predict.fun order signatures are accepted for about 60 s, Hyperliquid order signatures for 300 s, and cancel signatures (every venue) for 300 s; `expiresAtMs` on the step is authoritative.\n\n**Errors before the first signature are HTTP errors.** When the action fails before the wallet was ever asked to sign (for example every requested venue is unavailable), the response is that error's status and body rather than a `failed` step.\n\nSend `X-Kairos-Wallet-Api: 2`; without it this route serves the original Polymarket-only contract.", "tags": [ "Actions" ], "x-kairos-auth": "partner id (X-Kairos-Partner-Id) or API key triple", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletActionRequest" }, "examples": { "setup": { "summary": "Set up Polymarket and Predict.fun", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "action": { "type": "setup", "venues": [ "polymarket", "predictfun" ] } } }, "order": { "summary": "GTD limit buy on Predict.fun", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "action": { "type": "order", "market": "predictfun:1027194", "outcome": "Yes", "side": "buy", "price": "0.52", "size": "10", "timeInForce": "GTD", "expiresAt": 1793300000, "clientOrderId": "acme-7f3a91" } } }, "hyperliquidOrder": { "summary": "Hyperliquid outcome-market buy", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "action": { "type": "order", "market": "hyperliquid:1", "outcome": "Yes", "side": "buy", "price": "0.45", "size": "25", "timeInForce": "GTC", "clientOrderId": "0x7d2f0c1e9a4b4f6c8e3d2a1b0c9f8e7d" } } }, "cancel": { "summary": "Cancel two orders", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "action": { "type": "cancel", "orderIds": [ "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b", "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f" ] } } }, "cancelAll": { "summary": "Cancel every open order on every venue", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "action": { "type": "cancel", "all": true } } }, "login": { "summary": "Get a sign-in token for private reads", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "action": { "type": "login" } } } } } } }, "responses": { "200": { "description": "The action's first step. Usually `needs_signature`; `done` when nothing needs signing (a wallet already set up, or a `clientOrderId` that already names this exact order).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletActionStep" }, "examples": { "needsSignature": { "summary": "Predict.fun order waiting for its signature", "value": { "id": "6a1f9e2c-3b4d-4c5e-8f6a-7b8c9d0e1f2a", "type": "order", "status": "needs_signature", "request": { "method": "eth_signTypedData_v4", "params": [ "0x8ba1f109551bD432803012645Ac136ddd64DBA72", "{\"types\":{\"EIP712Domain\":[…],\"Order\":[…]},\"domain\":{\"name\":\"predict.fun CTF Exchange\",\"version\":\"1\",\"chainId\":56,\"verifyingContract\":\"0x…\"},\"primaryType\":\"Order\",\"message\":{…}}" ] }, "description": "Confirm this Predict.fun order", "chainId": "0x38", "venue": "predictfun", "expiresAtMs": 1793130772999, "result": null, "error": null } }, "alreadyReady": { "summary": "Setup on a wallet that is already ready", "value": { "id": "0b7e4d2a-1c3f-4a5b-9d8e-7f6a5b4c3d2e", "type": "setup", "status": "done", "request": null, "description": null, "chainId": null, "venue": null, "result": { "ready": true, "venues": { "polymarket": { "ready": true, "tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "transactionHash": null } }, "tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "transactionHash": null }, "error": null } } } } } }, "400": { "description": "JSON `{\"error\": …}` for a request Kairos refuses before any signature, for example:\n- `wallet must be a 0x address`; `partner id header is not valid ASCII` or a malformed partner id\n- `unknown venue \"x\"`; `market is required`; `market must be venue:market_id, e.g. predictfun:1027194, or a Polymarket condition id`; `a Polymarket market is its condition id (0x + 64 hex)`; `a Predict.fun market is predictfun:`; `a Hyperliquid market is hyperliquid:`; `unknown venue in market \"…\"`\n- `unknown Polymarket market; for another venue use venue:market_id`; `unknown Predict.fun market`; `unknown Hyperliquid market or outcome: market=… outcome=\"…\"`\n- `side must be buy or sell`; `price must be a decimal string`; `timeInForce must be GTC, GTD, FOK, FAK, or IOC`; `expiresAt is required for GTD`\n- Hyperliquid: `timeInForce on Hyperliquid must be GTC, FAK, or IOC`; `postOnly needs timeInForce GTC`; `clientOrderId must be 0x followed by 32 lowercase hex characters on this exchange`; price, size and minimum-notional refusals\n- `clientOrderId uses a reserved prefix` (ids starting `trade-plan:` are reserved); a blank or over-128-character `clientOrderId`\n- `pass either orderIds or all: true`; `at most 100 orderIds per cancel`\n\nA **plain-text** `400` (not JSON) means the body is not valid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "pass either orderIds or all: true" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletTenantUnauthorized" }, "403": { "description": "Tenant refusals (`unknown partner id`; `this partner id is used with its API key; send the key instead of X-Kairos-Partner-Id`; `this API key lacks the trade:execute scope`; `the wallet API is not enabled for this account`), or a trading refusal: `API-key access to is disabled`, `this wallet is disabled`, `Hyperliquid trading is disabled for this wallet`, `external-signing execution is not enabled for this account`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "409": { "description": "- `this wallet is not set up yet; run a setup action first` — `cancel` and `login` need a wallet that has completed setup on at least one venue.\n- `this wallet is linked to a Kairos account; trade with it in the Kairos app`.\n- `client_order_id already names a different order` with `code` and `errorCode` = `CLIENT_ORDER_ID_CONFLICT`.\n- `code: POLYMARKET_V2_TRADING_DISABLED` — the market trades on a Polymarket contract version Kairos has not enabled yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "client_order_id already names a different order", "code": "CLIENT_ORDER_ID_CONFLICT", "errorCode": "CLIENT_ORDER_ID_CONFLICT" } } } }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "description": "**Plain text** when the body is valid JSON of the wrong shape: a missing required field, an unknown `type`, a non-UUID in `orderIds`, `price`/`size` sent as numbers, or `expiresAt` sent as a string.\n\nJSON when Hyperliquid refuses before signing: `not enough USDC on Hyperliquid for this order: it needs N, spot has S and perps can release W`.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "502": { "description": "A venue did not answer cleanly, e.g. `Hyperliquid is unavailable; retry shortly`, `Predict.fun is unavailable; retry shortly`. Nothing was signed; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "503": { "description": "`partner registry unavailable; retry shortly`; `rate limiter unavailable`; ` is not available right now`; `no venue is available right now`; `wallet sign-in is not configured` (login); `API-key access to is unavailable`. Nothing was signed; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "504": { "description": "`… did not answer in time; GET /v3/actions/{id} before retrying`. The action may have progressed: read it before starting another.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } } } } }, "/v3/actions/{id}": { "parameters": [ { "$ref": "#/components/parameters/WalletActionId" }, { "$ref": "#/components/parameters/WalletApiVersion" } ], "get": { "operationId": "getWalletAction", "summary": "Read an action's current step", "description": "Returns the action's current step. Poll this while `status` is `working`; when the step carries `holdUntilMs` (an order the venue is still matching), wait until then before polling.\n\nAn action is readable for 10 minutes after its 15-minute lifetime ends. Unknown, expired, and other partners' actions all read `404`.", "tags": [ "Actions" ], "x-kairos-auth": "partner id (X-Kairos-Partner-Id) or API key triple", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] } ], "responses": { "200": { "description": "The current step.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletActionStep" }, "examples": { "held": { "summary": "Polymarket order the venue is still matching", "value": { "id": "6a1f9e2c-3b4d-4c5e-8f6a-7b8c9d0e1f2a", "type": "order", "status": "working", "request": null, "description": "Waiting for the venue to match your order", "chainId": null, "venue": "polymarket", "holdUntilMs": 1793130776000, "result": { "orderId": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b", "status": "delayed", "venueOrderId": "0x9d1c5e0b7a3f2e4d6c8b0a1f3e5d7c9b2a4f6e8d0c1b3a5f7e9d2c4b6a8f0e1d", "venueStatus": "delayed", "filledSize": null, "filledNotional": null, "avgPrice": null, "final": false, "success": false, "message": null, "venue": "polymarket", "market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a" }, "error": null } }, "done": { "summary": "Filled order", "value": { "id": "6a1f9e2c-3b4d-4c5e-8f6a-7b8c9d0e1f2a", "type": "order", "status": "done", "request": null, "description": null, "chainId": null, "venue": null, "result": { "orderId": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b", "status": "matched", "venueOrderId": "0x9d1c5e0b7a3f2e4d6c8b0a1f3e5d7c9b2a4f6e8d0c1b3a5f7e9d2c4b6a8f0e1d", "venueStatus": "matched", "filledSize": "7.140348", "filledNotional": "4.069998", "avgPrice": "0.57", "final": true, "success": true, "message": null, "venue": "polymarket", "market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a" }, "error": null } }, "failed": { "summary": "Immediate order that found no liquidity", "value": { "id": "6a1f9e2c-3b4d-4c5e-8f6a-7b8c9d0e1f2a", "type": "order", "status": "failed", "request": null, "description": null, "chainId": null, "venue": null, "result": null, "error": "no orders found to match with FAK order", "errorCode": "NO_MATCH" } } } } } }, "400": { "description": "Plain text — `{id}` is not a UUID.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletTenantUnauthorized" }, "403": { "$ref": "#/components/responses/WalletTenantForbidden" }, "404": { "description": "`unknown or expired action` — also returned for another partner's action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "unknown or expired action" } } } }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "502": { "$ref": "#/components/responses/WalletVenueUnavailable" }, "503": { "$ref": "#/components/responses/WalletServiceUnavailable" }, "504": { "$ref": "#/components/responses/WalletGatewayTimeout" } } }, "post": { "operationId": "answerWalletAction", "summary": "Answer the current step (signature or wallet result)", "description": "Posts the wallet's answer to the step that is `needs_signature` and returns the next step.\n\n- **Signature steps** (`eth_signTypedData_v4`, `personal_sign`): send `{\"signature\": \"0x…\"}` — exactly 65 bytes, hex. A JSON string in `result` is accepted as the signature too. Smart-account (EIP-1271) signatures are refused.\n- **`wallet_sendCalls` steps** (Predict.fun approvals): send `{\"result\": }`, or `{\"result\": [\"0xhash\", …]}` after sending `fallbackRequests` one by one. The step moves to `working` while Kairos waits for the approvals on chain.\n\n**Failures after a signature are not HTTP errors.** A venue refusal, an expired signing window, a rate limit or an ambiguous submission comes back as **`200`** with `status: \"failed\"`, `error`, and — when there is one — `errorCode`. Read `errorCode` before retrying: `ORDER_OUTCOME_UNKNOWN` and `CANCEL_OUTCOME_UNKNOWN` mean the venue may have acted, so read `/v3/wallets/{address}/orders` before placing again.\n\n**Safe to repeat.** Posting to a step that is no longer `needs_signature` returns the current step unchanged; a step is never run twice. A wrong signer gets `400` and the same step stays open for another try.\n\nThis call waits up to about 45 s for the step to settle, then returns `working`; keep polling `GET /v3/actions/{id}`.", "tags": [ "Actions" ], "x-kairos-auth": "partner id (X-Kairos-Partner-Id) or API key triple", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletActionAnswer" }, "examples": { "signature": { "summary": "Typed-data or personal_sign signature", "value": { "signature": "0x4f8b2c1d9e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c3d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e1b" } }, "sendCalls": { "summary": "wallet_sendCalls result", "value": { "result": { "id": "0x1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c" } } } } } } }, "responses": { "200": { "description": "The next step — `needs_signature` (another prompt), `working`, `done`, or `failed` (with `error` and usually `errorCode`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletActionStep" }, "examples": { "signatureExpired": { "summary": "Answered after expiresAtMs", "value": { "id": "6a1f9e2c-3b4d-4c5e-8f6a-7b8c9d0e1f2a", "type": "order", "status": "failed", "request": null, "description": null, "chainId": null, "venue": null, "result": null, "error": "the signing window closed before a signature was accepted; nothing was placed; start a new action", "errorCode": "SIGNATURE_EXPIRED" } }, "loginDone": { "summary": "Login finished", "value": { "id": "2d4f6a8c-0e1b-4c3d-9e5f-7a9b1c3d5e7f", "type": "login", "status": "done", "request": null, "description": null, "chainId": null, "venue": null, "result": { "token": "TWVzc2FnZSBleGFtcGxl.4f8b2c1d9e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c1b", "expiresAt": "2026-10-29T12:00:00Z" }, "error": null } } } } } }, "400": { "description": "JSON: `signature is required`; `signature must be hex`; `signature must be 65 bytes`; `signature is not from this wallet` (the step stays open — sign with the right account and post again).\n\nPlain text: the body is not valid JSON, or `{id}` is not a UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "signature is not from this wallet" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletTenantUnauthorized" }, "403": { "$ref": "#/components/responses/WalletTenantForbidden" }, "404": { "description": "`unknown or expired action`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "409": { "description": "`this action is busy; GET it and retry` — another request is advancing this action. `GET /v3/actions/{id}`, then answer the step it shows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "this action is busy; GET it and retry" } } } }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/WalletUnprocessable" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "502": { "$ref": "#/components/responses/WalletVenueUnavailable" }, "503": { "$ref": "#/components/responses/WalletServiceUnavailable" }, "504": { "$ref": "#/components/responses/WalletGatewayTimeout" } } } }, "/v3/wallets/{address}": { "get": { "operationId": "getWalletStatus", "summary": "Read a wallet's readiness and balances per venue", "description": "Returns whether the wallet is ready to trade on each venue, what to do next, and the venue balance. Needs only the partner id or API key — no wallet sign-in — because it reports on-chain state and readiness, not orders.\n\n**`next`** tells the app what to do: `setup` (run a `setup` action), `wait` (approvals are confirming), `fund` (deposit collateral, or gas on Predict.fun), `blocked` (Hyperliquid cannot enroll this account; see `venueDetail.reason`), or `null`. The top-level `next` picks the most urgent across not-ready venues (`setup` > `wait` > `fund` > `blocked`); when every venue is ready it is `fund` if no ready venue reports a non-zero balance — including when a balance is unknown (`null`).\n\nVenues not offered on the deployment are omitted. A venue whose read failed appears as `{\"ready\": false, \"available\": false, \"error\": …}` and is left out of the top-level `ready` and `next`. Readings may be up to 30 s old (`asOf`); a setup action refreshes them.", "tags": [ "Reads" ], "x-kairos-auth": "partner id (X-Kairos-Partner-Id) or API key triple", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletAddressPath" }, { "$ref": "#/components/parameters/WalletApiVersion" } ], "responses": { "200": { "description": "Readiness and balances per venue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletStatus" } } } }, "400": { "description": "`wallet must be a 0x address`, or a malformed partner id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "401": { "$ref": "#/components/responses/WalletTenantUnauthorized" }, "403": { "$ref": "#/components/responses/WalletTenantForbidden" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "502": { "$ref": "#/components/responses/WalletVenueUnavailable" }, "503": { "$ref": "#/components/responses/WalletServiceUnavailable" }, "504": { "$ref": "#/components/responses/WalletGatewayTimeout" } } } }, "/v3/wallets/{address}/orders": { "get": { "operationId": "listWalletOrders", "summary": "List a wallet's orders across venues", "description": "Returns the wallet's orders on every venue, newest first. Requires proof of the wallet: send `Authorization: SIWE ` from a `login` action (or an API key whose Kairos account owns the wallet).\n\nEach venue is read with the same `limit`; the rows are merged, sorted by `createdAt` descending and cut to `limit`. There is no cursor: this route returns at most 500 orders. When a venue cannot be read its rows are missing and `venueDetail..error` says why.\n\nOrder rows carry no fee fields.", "tags": [ "Reads" ], "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key tenants)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletAddressPath" }, { "$ref": "#/components/parameters/WalletApiVersion" }, { "name": "open", "in": "query", "required": false, "description": "`true` returns only working orders; `false` (default) returns every status. Only the literal `true` / `false` are accepted.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum rows to return. Values outside 1–500 are clamped.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "$ref": "#/components/parameters/WalletVenueQuery" } ], "responses": { "200": { "description": "Orders, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOrdersResponse" } } } }, "400": { "description": "`unknown venue \"x\"`; `wallet must be a 0x address`. Plain text for a malformed query (e.g. `open=1`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "$ref": "#/components/responses/WalletTenantForbidden" }, "404": { "$ref": "#/components/responses/WalletNotFound" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "502": { "$ref": "#/components/responses/WalletVenueUnavailable" }, "503": { "$ref": "#/components/responses/WalletServiceUnavailable" }, "504": { "$ref": "#/components/responses/WalletGatewayTimeout" } } } }, "/v3/wallets/{address}/positions": { "get": { "operationId": "listWalletPositions", "summary": "List a wallet's positions across venues", "description": "Returns open, resolved and closed positions across venues. Requires `Authorization: SIWE ` from a `login` action (or an API key whose Kairos account owns the wallet).\n\n**The body is nested:** the rows are at `positions.positions`, with `positions.resolved`, `positions.closed` and `positions.asOf` beside them. When a venue cannot be read, `venueDetail..error` says why.", "tags": [ "Reads" ], "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key tenants)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletAddressPath" }, { "$ref": "#/components/parameters/WalletApiVersion" }, { "$ref": "#/components/parameters/WalletVenueQuery" } ], "responses": { "200": { "description": "Positions across venues.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletPositionsResponse" } } } }, "400": { "description": "`unknown venue \"x\"`; `wallet must be a 0x address`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "$ref": "#/components/responses/WalletTenantForbidden" }, "404": { "$ref": "#/components/responses/WalletNotFound" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "502": { "$ref": "#/components/responses/WalletVenueUnavailable" }, "503": { "$ref": "#/components/responses/WalletServiceUnavailable" }, "504": { "$ref": "#/components/responses/WalletGatewayTimeout" } } } }, "/v3/fees": { "get": { "operationId": "getWalletFees", "summary": "Read a wallet's unpaid trading fees per venue", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); not yet released in production, where trade plans — the only source of this fee debt — return `503`.\n\nTrades placed through **trade plans** on Polymarket and Predict.fun accrue the Kairos fee and the partner fee as a debt per wallet and collateral asset; nothing is deducted inside the order. This read returns the debt per venue, the threshold at which `POST /v3/trade-plans` refuses new trades with `FEE_SETTLEMENT_REQUIRED`, and any open settlement.\n\n`owedRaw` is a signed integer string in token base units: it is **negative** when confirmed payments exceed the fees booked so far (a credit carried against later fees). The threshold is set by Kairos per partner. A venue whose settlement rail is not offered is omitted.\n\nReading also advances settlements: it refreshes the open settlement from chain evidence and credits late payments. Hyperliquid has no fee debt on this API.", "tags": [ "Fees (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:read for API-key callers (plus trade:execute when the key is also the tenant)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletAddressQuery" } ], "responses": { "200": { "description": "Debt per venue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletFeeSummary" } } } }, "400": { "description": "`wallet must be a 0x address`. Plain text for a missing `wallet` or any other query parameter. With API-key wallet proof a malformed `wallet` is `404 wallet not found` instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "$ref": "#/components/responses/WalletScopeForbidden" }, "404": { "$ref": "#/components/responses/WalletNotFound" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "$ref": "#/components/responses/WalletFeesUnavailable" } } } }, "/v3/fees/settlements": { "post": { "operationId": "createFeeSettlement", "summary": "Open a settlement for a wallet's unpaid fees on one venue", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); not yet released in production, where trade plans — the only source of this fee debt — return `503`.\n\nFreezes the wallet's **whole current debt** on `venue` into one settlement and returns the wallet request that pays it. If a settlement is already open for the wallet and asset, that settlement is returned instead (exactly one is ever open).\n\n**Paying.**\n- **Polymarket:** `walletRequest.kind` is `signature` — an `eth_signTypedData_v4` for a deposit-wallet batch holding one pUSD transfer to `treasury`. The wallet pays no gas. Sign within 30 minutes (`expiresAt`) and post the signature to `/answer`.\n- **Predict.fun:** `walletRequest.kind` is `transaction` — an `eth_sendTransaction` on BNB Chain (`0x38`) transferring exactly `amountRaw` USDT to `treasury`. The wallet pays the BNB gas. Send it **unchanged and on its own** (a different amount, or any other USDT outflow in the same transaction, fails the settlement without credit), then post the hash to `/answer`. No deadline.\n\nThen poll `GET /v3/fees/settlements/{id}` until `confirmed`. Fees booked after the settlement opened stay owed; check `GET /v3/fees` again after it confirms.", "tags": [ "Fees (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletFeeSettlementCreateRequest" } } } }, "responses": { "200": { "description": "The open settlement, with `walletRequest` while it awaits the wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletFeeSettlement" } } } }, "400": { "description": "`wallet must be a 0x address`. Plain text for malformed JSON. With API-key wallet proof a malformed `wallet` is `404 wallet not found` instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "$ref": "#/components/responses/WalletScopeForbidden" }, "404": { "$ref": "#/components/responses/WalletNotFound" }, "409": { "description": "`this wallet has no unpaid fees` — nothing is owed (or the wallet holds a credit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "this wallet has no unpaid fees" } } } }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/WalletUnprocessable" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "$ref": "#/components/responses/WalletFeesUnavailable" } } } }, "/v3/fees/settlements/{id}": { "get": { "operationId": "getFeeSettlement", "summary": "Read (and advance) a fee settlement", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); not yet released in production, where trade plans — the only source of this fee debt — return `503`.\n\nReturns the settlement after refreshing it from chain evidence. **This read is what advances a settlement** — poll it until `status` is terminal (`confirmed`, `failed`, `expired`). `confirmed` requires the payment to be in a **finalized** block, so it can trail the transaction by minutes.\n\nStatuses: `awaiting_signature` → (answer) → `submitted` → `confirmed`. A Polymarket settlement left unsigned past `expiresAt` becomes `expired`; a Predict.fun hash that never appears on chain within an hour becomes `expired`. If that transaction lands within 7 days of expiring, `GET /v3/fees` or `POST /v3/fees/settlements` (not this read) credits it and moves the settlement to `confirmed`. A Polymarket batch the relayer fails, or never executes by 5 minutes after `expiresAt`, becomes `failed`. `failed` carries a reason in `failure`, for example `the transaction reverted`, `transfer differs from the settlement`, `receipt contains no settlement transfer`, `receipt pays the settlement more than once`, `transaction predates the settlement`.", "tags": [ "Fees (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:read for API-key callers (plus trade:execute when the key is also the tenant)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletSettlementId" }, { "$ref": "#/components/parameters/WalletAddressQuery" } ], "responses": { "200": { "description": "The refreshed settlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletFeeSettlement" } } } }, "400": { "description": "`wallet must be a 0x address`. Plain text for a non-UUID `{id}` or a bad query. With API-key wallet proof a malformed `wallet` is `404 wallet not found` instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "$ref": "#/components/responses/WalletScopeForbidden" }, "404": { "description": "`fee settlement not found`; `wallet not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "$ref": "#/components/responses/WalletFeesUnavailable" } } } }, "/v3/fees/settlements/{id}/answer": { "post": { "operationId": "answerFeeSettlement", "summary": "Post the wallet's signature or transaction hash for a settlement", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); not yet released in production, where trade plans — the only source of this fee debt — return `503`.\n\nAnswers a settlement in `awaiting_signature`: a `signature` on Polymarket, a `transactionHash` on Predict.fun — never both. On success the settlement is `submitted`; poll `GET /v3/fees/settlements/{id}` until it is `confirmed`.\n\nA Polymarket signature must be a plain 65-byte ECDSA signature from `wallet` (low-s); smart-account signatures are refused. It is accepted until 30 s before `expiresAt`. `wallet` must be the wallet that opened the settlement (`walletRequest.request.params[0]` on Polymarket).", "tags": [ "Fees (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletSettlementId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletFeeSettlementAnswer" }, "examples": { "polymarket": { "summary": "Polymarket — signature", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "signature": "0x4f8b2c1d9e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c3d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e1b" } }, "predictfun": { "summary": "Predict.fun — transaction hash", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "transactionHash": "0x7c3e9a1b5d2f4c6e8a0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c" } } } } } }, "responses": { "200": { "description": "The settlement, refreshed after the answer — usually `submitted`. If the payment transaction is already known and in a finalized block (a Predict.fun hash, or a batch the relayer reports mined), it may come back `confirmed` or `failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletFeeSettlement" } } } }, "400": { "description": "`answer with a signature on Polymarket or a transactionHash on Predict.fun`; `invalid transactionHash`; `wallet must be a 0x address`. Plain text for malformed JSON or a non-UUID `{id}`. With API-key wallet proof a malformed `wallet` is `404 wallet not found` instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "description": "`signature does not authorize this fee settlement` — malformed (not `0x` + 130 hex), high-s, or not signed by `wallet` over this batch; or a tenant or sign-in failure (see `GET /v3/wallets/{address}/orders`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "403": { "$ref": "#/components/responses/WalletScopeForbidden" }, "404": { "description": "`fee settlement not found` — unknown, or not this wallet's; `wallet not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "409": { "description": "`this fee settlement no longer accepts an answer`; `that transaction already paid another settlement`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "410": { "description": "`this fee settlement expired; create a new one` — fewer than 30 s were left before `expiresAt`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/WalletUnprocessable" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "502": { "description": "`the Polymarket relayer refused the settlement` — the settlement is now `failed`; open a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "503": { "$ref": "#/components/responses/WalletFeesUnavailable" } } } }, "/v3/trade-plans": { "post": { "operationId": "prepareTradePlan", "summary": "Prepare a trade plan (one buy, optionally funded cross-chain)", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.\n\nA trade plan is **one buy order on one venue**, authorized up front in one batch of signatures, with an explicit fee ceiling (`tradeBudget`) and hard deadlines. When the venue account is short of collateral, the plan can also bridge **exactly the shortfall** from the same wallet's USDC on Polygon (`137`) or Arbitrum (`42161`) through gasless permits. Kairos runs funding first and submits the order only after the destination credit is final.\n\nUse `/v3/actions` for sells, cancels, setup and login; trade plans are buy-only and the venue wallet must already be set up through a `setup` action.\n\n**Flow.** Prepare → check `order` (the server may normalize it: canonical `outcome`; on Predict.fun a `GTC` order becomes a `GTD` order bounded by the venue session) → sign every `requests[]` entry whose `actionable` is `true` → `POST /v3/trade-plans/{id}/answers` and/or `POST /v3/trade-plans/{id}/execute` before `executeBefore` → poll `GET /v3/trade-plans/{id}`.\n\nAn unfunded plan needs 2 signatures (`plan`, `trade`); a funded plan adds `funding-1` and `funding-2`, signed on the **source** chain. Every signature must be a plain 65-byte ECDSA signature (low-s) from `wallet`.\n\n**Idempotency.** `Idempotency-Key` is required. The same key with the same body returns the stored plan in its current state; with a different body it is `409`. `clientOrderId` is unique per wallet and venue across plans.\n\n**Fees.** `tradeBudget.maxPlatformFeeBps` is the Kairos maximum plus the partner maximum (`partnerFee.maxBps`), never above 1000 bps (10%). Partner fees are configured by Kairos per partner and pinned into the plan the wallet signs. Fees are not deducted in the order: they accrue as debt and are paid through `/v3/fees/settlements`. When the wallet's debt is at or above the partner's threshold, prepare returns `409 FEE_SETTLEMENT_REQUIRED`.", "tags": [ "Trade plans (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTradePlanPrepareRequest" }, "examples": { "funded": { "summary": "Polymarket buy funded from Arbitrum USDC", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "interactionMode": "single_batch", "order": { "market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a", "outcome": "Yes", "side": "buy", "price": "0.05", "size": "10", "timeInForce": "GTC", "postOnly": true, "clientOrderId": "partner-trade-1042" }, "funding": { "sourceChainId": "42161", "sourceToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "maxAmountRaw": "750000", "maxGasCostRaw": "0", "slippageBps": 50 }, "tradeSubmitBefore": "2026-10-28T12:04:00Z", "submission": { "funding": "kairos", "trade": "kairos" } } }, "unfunded": { "summary": "Predict.fun buy with collateral already in place", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "interactionMode": "single_batch", "order": { "market": "predictfun:1027194", "outcome": "Yes", "side": "buy", "price": "0.52", "size": "10", "timeInForce": "FOK", "postOnly": false, "clientOrderId": "partner-trade-1043" }, "funding": null, "tradeSubmitBefore": "2026-10-28T12:04:00Z" } } } } } }, "responses": { "200": { "description": "The prepared plan in `needs_signatures`. A replay with the same `Idempotency-Key` and body returns the stored plan in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTradePlan" } } } }, "400": { "description": "`Idempotency-Key is required`; `invalid Idempotency-Key`; `invalid trade plan: ` (e.g. `funded trade plans currently accept buys`, a non-canonical decimal such as `\"0.50\"`, a deadline outside the 5-minute window); market format errors; `size must align exactly with the venue share lot`; `unknown CTF prerequisite`; `CTF prerequisite belongs to another wallet or audience`; `unsupported source chain`; `clientOrderId uses a reserved prefix`. Plain text for malformed JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "description": "`API key missing trade:execute scope`; `wallet partner is disabled`; `API-key access to is disabled`; `external-signing execution is not enabled for this account`; or a tenant refusal (see `POST /v3/actions`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "404": { "description": "`wallet not found` — the wallet has no Kairos account, or the caller does not own it; `trade plan not found` — `wallet` differs from the wallet the API key is bound to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "409": { "description": "- `FEE_SETTLEMENT_REQUIRED` (structured body below) — settle through `/v3/fees/settlements`, wait for `confirmed`, then prepare again.\n- `Idempotency-Key already names a different request`; `clientOrderId already names another trade plan`.\n- `set up the venue wallet before preparing a trade plan`; `set up the Hyperliquid wallet before preparing a trade plan`; `renew the Predict.fun wallet session` — run a `setup` action first.\n- `collateral is short; supply an explicit funding source`.\n- `wait for canonical CTF prerequisite confirmation`; `trade plan changed; read it before retrying`.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WalletFeeSettlementRequiredError" }, { "$ref": "#/components/schemas/WalletApiError" } ] }, "examples": { "feeSettlementRequired": { "summary": "Unpaid fees at or above the threshold", "value": { "error": "unpaid trading fees must be settled before the next trade", "code": "FEE_SETTLEMENT_REQUIRED", "assetKey": "evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb", "owedRaw": "10400000", "thresholdRaw": "10000000" } }, "setupRequired": { "summary": "Venue wallet not set up", "value": { "error": "set up the venue wallet before preparing a trade plan" } } } } } }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "description": "JSON `the combined Kairos and partner fee exceeds the 10% platform ceiling`; or plain text for a body of the wrong shape (unknown or missing fields, wrong types).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "description": "Production: `trade plans are disabled` until the lane is released. Staging: a dependency is unavailable — `venue is unavailable for trade plans`; `wallet funding is unavailable`; `no verified gasless funding route is available` (unsupported source → destination pair, e.g. Polygon USDC → Polymarket); `confirmed Polymarket fee schedule is unavailable`; `partner fee policy is unavailable`; `trade plan fee storage is unavailable`; `Polygon balance is unavailable`; `canonical CTF collateral snapshot is unavailable`; `partner registry unavailable; retry shortly`; `rate limiter unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } } } } }, "/v3/trade-plans/{id}": { "get": { "operationId": "getTradePlan", "summary": "Read a trade plan", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.\n\nReturns the plan. Poll it after `/execute` until `status` is terminal: `completed`, `expired`, `failed`, `funded_trade_failed`, `funded_trade_expired`. `completed` means the venue **accepted** the order, not that it filled; follow the fill through `/v3/wallets/{address}/orders`.\n\nA plan that was never executed and is past `executeBefore` turns `expired` (`PLAN_EXPIRED`) on this read. `reconciling` with `error.code: OUTCOME_UNKNOWN` is the normal in-flight state while funding or the trade is being confirmed — keep polling. When funding landed but the trade failed or expired, the bridged collateral stays in `tradingWallet`; nothing is refunded automatically.", "tags": [ "Trade plans (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:read for API-key callers (plus trade:execute when the key is also the tenant)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletTradePlanId" } ], "responses": { "200": { "description": "The plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTradePlan" } } } }, "400": { "description": "Plain text — `{id}` is not a UUID.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "$ref": "#/components/responses/WalletScopeForbidden" }, "404": { "$ref": "#/components/responses/WalletTradePlanNotFound" }, "409": { "description": "`trade plan changed; read it before retrying` — the plan changed while this read was expiring it. Read it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "$ref": "#/components/responses/WalletPreviewUnavailable" } } } }, "/v3/trade-plans/{id}/answers": { "post": { "operationId": "answerTradePlan", "summary": "Post signatures for a trade plan's requests", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.\n\nPosts one or more signatures for the plan's `requests[]`. Answers may arrive in several batches; the whole batch is checked before anything is stored. When every required signature is in, `status` becomes `ready_to_execute`. You can also skip this call and send all signatures in the `/execute` body.\n\nEach signature must be 65 bytes, low-s, and recover to `wallet` over that request's typed data. Re-sending an accepted signature is a no-op; a different signature for an accepted request is refused. With `submission.funding: \"client\"`, keep the funding signatures — Kairos refuses them. Only `kind: \"signature\"` answers are accepted.", "tags": [ "Trade plans (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletTradePlanId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTradePlanAnswersRequest" } } } }, "responses": { "200": { "description": "The plan; accepted requests show `status: accepted` and `actionable: false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTradePlan" } } } }, "400": { "description": "`invalid trade plan: ` — plan hash mismatch, more than 32 answers, a duplicate or unknown request id, `client-owned funding signatures stay with the client`, `transaction answers require independent chain verification`; `a previously accepted answer cannot change`. Plain text for malformed JSON or a non-UUID `{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "description": "`signature does not authorize this plan request`, or a tenant or sign-in failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "403": { "$ref": "#/components/responses/WalletScopeForbidden" }, "404": { "$ref": "#/components/responses/WalletTradePlanNotFound" }, "409": { "description": "`the plan no longer accepts this operation` (already executed or finished); `trade plan changed; read it before retrying`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "410": { "$ref": "#/components/responses/WalletPlanExpired" }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/WalletUnprocessable" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "$ref": "#/components/responses/WalletPreviewUnavailable" } } } }, "/v3/trade-plans/{id}/execute": { "post": { "operationId": "executeTradePlan", "summary": "Commit a trade plan for execution", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.\n\nCommits the plan: Kairos checks balances, reserves `tradeBudget.maxDebitRaw` at the destination (and `funding.amountInRaw` at the source when funded) against the wallet's other plans, then runs it. The body is the same as `/answers`; `answers` may be empty when every signature was already posted. Call it before `executeBefore`.\n\nResult: `trade_pending` (no funding) or `funding_pending` (`execution.fundingStatus` `pending`, or `awaiting_client` when `submission.funding` is `client`). Calling it again after a successful commit returns the current plan with no new effect.\n\n**Client-owned funding.** After committing, POST each signed permit yourself to `requests[].externalSubmission.endpoint` (`funding-1` first), then report it with `POST /v3/trade-plans/{id}/reports`.", "tags": [ "Trade plans (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletTradePlanId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTradePlanAnswersRequest" }, "example": { "planHash": "0xb3d5c6e930ee2015f733bd9ffa2a2302fedd2a5bf38628e220f0b675d50f6953", "answers": [] } } } }, "responses": { "200": { "description": "The committed plan (`execution.committed: true`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTradePlan" } } } }, "400": { "description": "Same answer validation as `/answers`. Plain text for malformed JSON or a non-UUID `{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "description": "`signature does not authorize this plan request`, or a tenant or sign-in failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "403": { "description": "`API key missing trade:execute scope`; `wallet partner is disabled`; `API-key access to is disabled`; `external-signing execution is not enabled for this account`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "404": { "$ref": "#/components/responses/WalletTradePlanNotFound" }, "409": { "description": "`the plan is missing required signatures`; `the plan no longer accepts this operation`; `trade plan changed; read it before retrying` (the balance net of other reservations no longer covers the plan, or it changed while committing — read the plan, then retry or prepare a new one); `CTF prerequisite is unavailable`; `collateral observation predates the CTF prerequisite` (retry shortly); `Hyperliquid wallet readiness changed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "410": { "$ref": "#/components/responses/WalletPlanExpired" }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/WalletUnprocessable" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "$ref": "#/components/responses/WalletPreviewUnavailable" } } } }, "/v3/trade-plans/{id}/reports": { "post": { "operationId": "reportTradePlanFunding", "summary": "Report client-submitted funding permits", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.\n\nOnly for committed plans with `submission.funding: \"client\"`. After you POST a signed funding permit to its `externalSubmission.endpoint`, report it here so Kairos checks the funding right away. A report is only a hint: it never marks funding as confirmed — Kairos confirms from the provider and the destination chain. `requestHash` and `providerRequestId` must equal the values on the plan's request.", "tags": [ "Trade plans (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletTradePlanId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTradePlanReportsRequest" } } } }, "responses": { "200": { "description": "The latest plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTradePlan" } } } }, "400": { "description": "`invalid trade plan: ` — plan hash mismatch, no or more than 32 reports, duplicate ids, or a report that does not match a funding request. Plain text for malformed JSON or a non-UUID `{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "$ref": "#/components/responses/WalletScopeForbidden" }, "404": { "$ref": "#/components/responses/WalletTradePlanNotFound" }, "409": { "description": "`the plan no longer accepts this operation` — not committed, or funding is not client-owned; `trade plan changed; read it before retrying`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/WalletUnprocessable" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "$ref": "#/components/responses/WalletPreviewUnavailable" } } } }, "/v3/onchain-intents": { "post": { "operationId": "prepareOnchainIntent", "summary": "Prepare a split, merge or redeem on a Polymarket deposit wallet", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.\n\nRuns one conditional-token operation — `split`, `merge` or `redeem` — on the wallet's Polymarket deposit wallet on Polygon. Kairos builds the exact calls and returns two typed-data requests for the owner to sign; the wallet pays **no gas**. Kairos marks the intent `confirmed` only after it verifies a finalized receipt whose token transfers equal `intent.terms.effects` exactly.\n\n**Scope.** Polymarket on Polygon (`137`), binary markets only. `redeem` needs a resolved market and an `outcome`; markets on the legacy conditional-token contract cannot be redeemed here. Each batch is `[approval, operation]`: merge and redeem leave a standing operator approval (`setApprovalForAll`) for the operating contract on the deposit wallet. The wallet must already be set up through a `setup` action.\n\n**Addresses** `wallet` and `account` must be **lowercase**; a checksummed address is refused.\n\n**Flow.** Prepare → sign `consentRequest` (and `nativeRequest` when `submissionOwner` is `kairos`) → `POST /v3/onchain-intents/{id}/execute` before `executeBefore` (at most 5 minutes out) → poll `GET /v3/onchain-intents/{id}` until `confirmed`.\n\n**Do not broadcast the batch from the wallet or the deposit wallet**: a transaction sent from either never confirms. With `submissionOwner: \"client\"` (for integrators that have arranged submission access with Kairos), POST `submission.body` plus `\"signature\": ` to `submission.endpoint`, then report the transaction hash.\n\n**Chaining.** `dependencies` lists earlier intents on the same deposit wallet (for example a split, then a merge); an intent executes only after its dependencies are `confirmed`. A trade plan can also depend on a confirmed intent through `ctfDependencies`.\n\n**Idempotency.** `Idempotency-Key` is required. The same key with the same body returns the original intent in its current state; with a different body it is `409`.", "tags": [ "On-chain intents (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletIdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOnchainIntentPrepareRequest" }, "examples": { "split": { "summary": "Split 1 pUSD into both outcomes", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "account": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a", "operation": "split", "amountRaw": "1000000", "submissionOwner": "kairos", "executeBefore": "2026-10-28T12:04:00Z" } }, "redeem": { "summary": "Redeem 1 winning share of outcome 0", "value": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "account": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a", "operation": "redeem", "outcome": 0, "amountRaw": "1000000", "submissionOwner": "kairos", "executeBefore": "2026-10-28T12:04:00Z" } } } } } }, "responses": { "200": { "description": "The prepared intent (`needs_signatures`) and the two requests to sign.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOnchainIntentView" } } } }, "400": { "description": "`invalid on-chain intent request` (field rules: lowercase addresses, `account` ≠ `wallet`, canonical `amountRaw` > 0, `outcome` exactly when redeeming, `executeBefore` within 300 s with whole seconds, at most 16 distinct dependencies); `a valid Idempotency-Key is required`; `wallet must be a 0x address`; `account must be the registered signer's Polymarket deposit wallet`; `CTF intents require a Polymarket market`; `CTF intents require a binary market`; `unsupported CTF operation: legacy CTF redeem cannot enforce a signed token debit limit`; `deposit wallet is not deployed at finality`; `redemption must produce a positive bounded payout` (a losing outcome); `unknown CTF prerequisite`; `CTF prerequisite belongs to another account`; other market and condition checks. Plain text for malformed JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "description": "`API key missing trade:execute scope`; `wallet partner is disabled`; `wallet dispatch authority was revoked`; `external-signing execution is not enabled for this account`; `API-key access to polymarket is disabled`; or a tenant refusal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "404": { "description": "`wallet not found`; `on-chain intent not found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "409": { "description": "`Idempotency-Key already names another intent`; `Polymarket V2 trading is disabled`; `this wallet is not set up yet; run a setup action first`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/WalletUnprocessable" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "description": "Production: the lane is not released. Staging: `canonical Polygon state is unavailable` (an RPC or metadata failure — **or a `redeem` on a market that has not resolved yet**); `execution is disabled for this operation`; `trade plans are disabled`; `partner registry unavailable; retry shortly`; `rate limiter unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } } } } }, "/v3/onchain-intents/{id}": { "get": { "operationId": "getOnchainIntent", "summary": "Read an on-chain intent", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.\n\nReturns the intent and its signing requests. Poll until `intent.status` is `confirmed`; `intent.proof` then holds the verified transaction. A committed intent keeps being watched, including after `executeBefore`; an uncommitted one is not. A batch not mined by `executeBefore` (its on-chain deadline) can no longer land, so its intent never confirms — prepare a new one.", "tags": [ "On-chain intents (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:read for API-key callers (plus trade:execute when the key is also the tenant)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletOnchainIntentId" } ], "responses": { "200": { "description": "The intent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOnchainIntentView" } } } }, "400": { "description": "Plain text — `{id}` is not a UUID.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "$ref": "#/components/responses/WalletScopeForbidden" }, "404": { "$ref": "#/components/responses/WalletOnchainIntentNotFound" }, "409": { "description": "`this wallet is not set up yet; run a setup action first` — the signer's account is no longer active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "$ref": "#/components/responses/WalletPreviewUnavailable" } } } }, "/v3/onchain-intents/{id}/execute": { "post": { "operationId": "executeOnchainIntent", "summary": "Commit an on-chain intent with its signatures", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.\n\nCommits the intent before `executeBefore`. `consentSignature` is always required; `nativeSignature` is required when `submissionOwner` is `kairos` and must be **omitted** when it is `client`. Kairos checks every dependency is `confirmed`, checks the finalized token balances cover the debits net of the wallet's other reservations, then commits: `ready` (Kairos submits once, then `reconciling` → `confirmed`) or `awaiting_client` (you submit, see below).\n\nCalling it again after a successful commit, with valid signatures, returns the current intent.\n\n**Client submission.** POST `submission.body` with `\"signature\": ` added to `submission.endpoint`, then `POST /v3/onchain-intents/{id}/reports` with the transaction hash. Do not send the batch from the wallet or the deposit wallet.", "tags": [ "On-chain intents (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletOnchainIntentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOnchainIntentExecuteRequest" } } } }, "responses": { "200": { "description": "The committed intent (`committed: true`; `ready` or `awaiting_client`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOnchainIntentView" } } } }, "400": { "description": "`invalid trade plan: native signature does not match submission ownership` — `nativeSignature` sent for `client`, or missing for `kairos`. Plain text for malformed JSON or a non-UUID `{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "description": "`signature does not authorize this plan request` — a signature that is not `0x` + 65 bytes, is high-s, or does not recover to `terms.signer`; or a tenant or sign-in failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "403": { "description": "`API key missing trade:execute scope`; `wallet partner is disabled`; `wallet dispatch authority was revoked`; `external-signing execution is not enabled for this account`; `API-key access to polymarket is disabled`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "404": { "$ref": "#/components/responses/WalletOnchainIntentNotFound" }, "409": { "description": "`the plan is missing required signatures` — returned when a **dependency is not `confirmed` yet** (wait and retry); `CTF prerequisite is unavailable`; `the plan no longer accepts this operation` (`intentHash` mismatch); `trade plan changed; read it before retrying` — the finalized balance does not cover the debit net of other reservations, or the reading was stale; `this wallet is not set up yet; run a setup action first`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "410": { "$ref": "#/components/responses/WalletPlanExpired" }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/WalletUnprocessable" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "description": "Production: the lane is not released. Staging: `canonical Polygon state is unavailable`; `execution is disabled for this operation`; `partner registry unavailable; retry shortly`; `rate limiter unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } } } } }, "/v3/onchain-intents/{id}/reports": { "post": { "operationId": "reportOnchainIntentTransaction", "summary": "Report the transaction hash of a client-submitted intent", "description": "Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.\n\nOnly for committed intents with `submissionOwner: \"client\"`. The hash is a hint: it moves the intent to `reconciling` and Kairos confirms it from the finalized receipt. A later report can replace a hash that has not been verified; once the intent is `confirmed`, only the confirmed hash is accepted. Reports are optional — Kairos also finds the transaction on chain.", "tags": [ "On-chain intents (preview)" ], "x-kairos-status": "preview", "x-kairos-auth": "partner id or API key triple, plus wallet sign-in (Authorization SIWE) or an API key that owns the wallet", "x-kairos-scope": "trade:execute (API-key callers)", "x-kairos-rate-limit": "120 requests/minute per client IP per route; 1000/minute when X-Client-Id is sent", "security": [ { "walletPartnerId": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [], "walletSignIn": [] }, { "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "apiKeyClientId": [], "apiKeyKey": [], "apiKeySecret": [] }, { "walletPartnerId": [], "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/WalletOnchainIntentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOnchainIntentReportRequest" } } } }, "responses": { "200": { "description": "The intent, now `reconciling` (or `confirmed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletOnchainIntentView" } } } }, "400": { "description": "`invalid trade plan: noncanonical digest` (the hash must be lowercase `0x` + 64 hex); `a previously accepted answer cannot change` (a different hash on a confirmed intent). Plain text for malformed JSON or a non-UUID `{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "401": { "$ref": "#/components/responses/WalletSignInUnauthorized" }, "403": { "$ref": "#/components/responses/WalletScopeForbidden" }, "404": { "$ref": "#/components/responses/WalletOnchainIntentNotFound" }, "409": { "description": "`the plan no longer accepts this operation` — not committed, not client-submitted, or an `intentHash` mismatch; `trade plan changed; read it before retrying` — read the intent and send the same report again; `this wallet is not set up yet; run a setup action first`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "413": { "$ref": "#/components/responses/WalletPayloadTooLarge" }, "415": { "$ref": "#/components/responses/WalletUnsupportedMediaType" }, "422": { "$ref": "#/components/responses/WalletUnprocessable" }, "429": { "$ref": "#/components/responses/WalletRateLimited" }, "500": { "$ref": "#/components/responses/WalletInternalError" }, "503": { "$ref": "#/components/responses/WalletPreviewUnavailable" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "First-party Kairos session JWT (web app sessions). Not issued to API consumers." }, "walletPartnerId": { "type": "apiKey", "in": "header", "name": "X-Kairos-Partner-Id", "description": "Wallet API partner id, issued by Kairos together with the partner's base URL. Identifies the partner (tenant) on every `/v3` call; sent instead of an API key. Letters, digits and `._:-`, at most 64 characters, case-insensitive. A partner id issued for an individual account cannot be sent this way — that account sends its API key triple instead." }, "apiKeySecret": { "type": "apiKey", "in": "header", "name": "X-Api-Secret", "description": "64-char hex API secret." }, "apiKeyKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "64-char hex API key." }, "apiKeyClientId": { "type": "apiKey", "in": "header", "name": "X-Client-Id", "description": "Credential client id (`kairos_ck_...`). Must be sent together with X-Api-Key and X-Api-Secret." }, "walletSignIn": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Wallet sign-in token: `SIWE `, where `` is `result.token` from a `login` action (exactly one space after `SIWE`). Proves the wallet on reads of its orders and positions, and on trade plans, fee settlements and on-chain intents. The token is bound to the partner and the environment that issued it and lasts 24 hours; run a new `login` action to renew it." } }, "schemas": { "WalletOnchainIntentReportRequest": { "type": "object", "additionalProperties": false, "required": [ "intentHash", "transactionHash" ], "properties": { "intentHash": { "type": "string", "description": "Must equal `intent.intentHash`.", "pattern": "^0x[0-9a-f]{64}$" }, "transactionHash": { "type": "string", "description": "Lowercase `0x` + 64 hex.", "pattern": "^0x[0-9a-f]{64}$" } } }, "WalletOnchainIntentExecuteRequest": { "type": "object", "additionalProperties": false, "required": [ "intentHash", "consentSignature" ], "properties": { "intentHash": { "type": "string", "description": "Must equal `intent.intentHash`.", "pattern": "^0x[0-9a-f]{64}$" }, "consentSignature": { "type": "string", "description": "Signature of `consentRequest` — `0x` + 65 bytes (`r‖s‖v`, low-s, `v` 0/1/27/28).", "pattern": "^0x[0-9a-fA-F]{130}$" }, "nativeSignature": { "type": "string", "description": "Signature of `nativeRequest`, same format. Required when `submissionOwner` is `kairos`; must be omitted when `client`.", "pattern": "^0x[0-9a-fA-F]{130}$" } } }, "WalletApiError": { "type": "object", "description": "Wallet API error body. `error` is a human-readable message; `code` is set on a few structured refusals (e.g. `CLIENT_ORDER_ID_CONFLICT`, `POLYMARKET_V2_TRADING_DISABLED`, `SIGNATURE_EXPIRED`); `errorCode` mirrors `code` where the same refusal can also surface on a failed step. Most `/v3` errors carry only `error`. Framework rejections (malformed JSON, wrong shape, missing content type) are plain text, not this body.", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable message." }, "code": { "type": "string", "description": "Stable code, present on structured refusals only." }, "errorCode": { "type": "string", "description": "Same as `code`; present where the refusal can also appear as a failed step's `errorCode`." } }, "example": { "error": "unknown or expired action" } }, "WalletOnchainIntentView": { "type": "object", "description": "An on-chain intent with its two signing requests, both `eth_signTypedData_v4` by `terms.signer` on Polygon (`params[1]` is a JSON string — pass it unchanged):\n- `consentRequest` — `KairosOnchainIntent` typed data binding `signer`, `partnerId`, `audience`, `intentId`, `intentHash`, `executeBefore`. Always required.\n- `nativeRequest` — the deposit wallet's `Batch` authorization over `terms.batch`. Send it to Kairos when `submissionOwner` is `kairos`; keep it for your own submission when `client`.\n\nSignatures must be plain 65-byte ECDSA (low-s) from the owner key; smart-account signatures are refused.", "required": [ "intent", "consentRequest", "nativeRequest", "submission" ], "properties": { "intent": { "$ref": "#/components/schemas/WalletOnchainIntent" }, "consentRequest": { "$ref": "#/components/schemas/WalletEip1193Request" }, "nativeRequest": { "$ref": "#/components/schemas/WalletEip1193Request" }, "submission": { "$ref": "#/components/schemas/WalletOnchainSubmission" } } }, "WalletOnchainSubmission": { "type": "object", "description": "For `submissionOwner: client`: add `\"signature\": ` to `body` and POST it to `endpoint`.", "required": [ "endpoint", "method", "kind", "body" ], "properties": { "endpoint": { "type": "string" }, "method": { "type": "string", "const": "POST" }, "kind": { "type": "string", "const": "deposit_wallet_batch" }, "body": { "type": "object", "description": "`{type: \"WALLET\", from, to, nonce, depositWalletParams: {depositWallet, deadline, calls}}` — no signature.", "additionalProperties": true } } }, "WalletEip1193Request": { "type": "object", "description": "An EIP-1193 request to run through the wallet's provider exactly as given (`provider.request({method, params})`).\n- `eth_signTypedData_v4`: `params` = `[address, typedData]` — `typedData` is a **JSON string**; pass it unchanged.\n- `personal_sign`: `params` = `[hexMessage, address]`.\n- `wallet_sendCalls` (EIP-5792): `params` = `[{version, chainId, from, atomicRequired, calls}]`; the wallet pays gas.\n- `eth_sendTransaction`: `params` = `[{from, to, data, value, chainId?}]`; the wallet pays gas.", "required": [ "method", "params" ], "properties": { "method": { "type": "string", "enum": [ "eth_signTypedData_v4", "personal_sign", "wallet_sendCalls", "eth_sendTransaction" ] }, "params": { "type": "array", "items": {} } }, "example": { "method": "personal_sign", "params": [ "0x6b6169726f732e7472616465207761…", "0x8ba1f109551bD432803012645Ac136ddd64DBA72" ] } }, "WalletOnchainIntent": { "type": "object", "required": [ "terms", "intentHash", "status", "committed", "dispatchClaimed", "transactionHash", "proof" ], "properties": { "terms": { "$ref": "#/components/schemas/WalletOnchainIntentTerms" }, "intentHash": { "type": "string" }, "status": { "type": "string", "enum": [ "needs_signatures", "awaiting_client", "ready", "reconciling", "confirmed" ], "description": "`needs_signatures` → (`/execute`) `ready` (Kairos submits) or `awaiting_client` (you submit) → `reconciling` → `confirmed` (the only terminal status). A reverted transaction returns the intent to `reconciling`; the signed batch stays valid until `executeBefore`. There is no expired status: an intent whose batch was not mined by `executeBefore` stays where it is." }, "committed": { "type": "boolean" }, "dispatchClaimed": { "type": "boolean", "description": "Kairos has submitted (or is submitting) the batch." }, "transactionHash": { "type": [ "string", "null" ], "description": "The candidate transaction, once known (a report or Kairos's own submission); verified only when `proof` is set." }, "proof": { "oneOf": [ { "$ref": "#/components/schemas/WalletOnchainProof" }, { "type": "null" } ] } } }, "WalletOnchainProof": { "type": "object", "description": "The verified, finalized transaction.", "required": [ "transactionHash", "blockHash", "blockNumber", "intentHash", "effects" ], "properties": { "transactionHash": { "type": "string" }, "blockHash": { "type": "string" }, "blockNumber": { "type": "string", "description": "Decimal." }, "intentHash": { "type": "string" }, "effects": { "type": "array", "items": { "$ref": "#/components/schemas/WalletOnchainEffect" } } } }, "WalletOnchainEffect": { "type": "object", "description": "An exact gross token movement on the deposit wallet.", "required": [ "token", "direction", "amountRaw" ], "properties": { "token": { "$ref": "#/components/schemas/WalletOnchainToken" }, "direction": { "type": "string", "enum": [ "debit", "credit" ] }, "amountRaw": { "type": "string" } } }, "WalletOnchainToken": { "description": "A token, tagged by `kind`.", "oneOf": [ { "$ref": "#/components/schemas/WalletOnchainTokenErc20" }, { "$ref": "#/components/schemas/WalletOnchainTokenErc1155" } ], "discriminator": { "propertyName": "kind", "mapping": { "erc20": "#/components/schemas/WalletOnchainTokenErc20", "erc1155": "#/components/schemas/WalletOnchainTokenErc1155" } } }, "WalletOnchainTokenErc1155": { "type": "object", "required": [ "kind", "contract", "tokenId" ], "properties": { "kind": { "type": "string", "const": "erc1155" }, "contract": { "type": "string" }, "tokenId": { "type": "string", "description": "Decimal token id." } } }, "WalletOnchainTokenErc20": { "type": "object", "required": [ "kind", "contract" ], "properties": { "kind": { "type": "string", "const": "erc20" }, "contract": { "type": "string" } } }, "WalletOnchainIntentTerms": { "type": "object", "description": "The immutable terms; `intentHash` is their hash. `audience`, `executionRegion` and `submissionEndpoint` are opaque values pinned into the signed terms — do not change them.", "required": [ "contractVersion", "id", "partnerId", "audience", "executionRegion", "signer", "account", "chainId", "market", "operation", "submissionOwner", "submissionEndpoint", "batch", "effects", "dependencies", "maxWalletGasCostRaw", "createdAt", "executeBefore" ], "properties": { "contractVersion": { "type": "integer", "const": 1 }, "id": { "type": "string", "format": "uuid" }, "partnerId": { "type": "string" }, "audience": { "type": "string", "description": "Opaque signed field." }, "executionRegion": { "type": "string", "description": "Opaque signed field." }, "signer": { "type": "string" }, "account": { "type": "string" }, "chainId": { "type": "string", "const": "137" }, "market": { "type": "string" }, "operation": { "type": "string", "enum": [ "split", "merge", "redeem" ] }, "submissionOwner": { "type": "string", "enum": [ "kairos", "client" ] }, "submissionEndpoint": { "type": "string", "description": "Opaque pinned submission URL. Equals `submission.endpoint`." }, "batch": { "$ref": "#/components/schemas/WalletOnchainBatch" }, "effects": { "type": "array", "description": "Exactly what the batch moves on the deposit wallet — the receipt must match.", "items": { "$ref": "#/components/schemas/WalletOnchainEffect" } }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/WalletOnchainDependency" } }, "maxWalletGasCostRaw": { "type": "string", "const": "0", "description": "The wallet pays no gas." }, "createdAt": { "type": "string", "format": "date-time" }, "executeBefore": { "type": "string", "format": "date-time" } } }, "WalletOnchainDependency": { "type": "object", "description": "A confirmed-before-me intent, pinned by hash.", "required": [ "intentId", "intentHash", "account", "chainId", "effects" ], "properties": { "intentId": { "type": "string", "format": "uuid" }, "intentHash": { "type": "string" }, "account": { "type": "string" }, "chainId": { "type": "string", "example": "137" }, "effects": { "type": "array", "items": { "$ref": "#/components/schemas/WalletOnchainEffect" } } } }, "WalletOnchainBatch": { "type": "object", "description": "The deposit-wallet batch the owner signs. Calls are `[approval, operation]`.", "required": [ "factory", "nonce", "deadline", "calls" ], "properties": { "factory": { "type": "string" }, "nonce": { "type": "string", "description": "Decimal." }, "deadline": { "type": "string", "format": "date-time", "description": "Equals `executeBefore`." }, "calls": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "$ref": "#/components/schemas/WalletOnchainCall" } } } }, "WalletOnchainCall": { "type": "object", "required": [ "target", "value", "data" ], "properties": { "target": { "type": "string" }, "value": { "type": "string", "example": "0" }, "data": { "type": "string" } } }, "WalletOnchainIntentPrepareRequest": { "type": "object", "additionalProperties": false, "description": "Body of `POST /v3/onchain-intents`. Unknown fields (calls, nonce, chain, recipient, gas) are refused.", "required": [ "wallet", "account", "market", "operation", "amountRaw", "submissionOwner", "executeBefore" ], "properties": { "wallet": { "type": "string", "description": "The owner that signs — **lowercase** `0x` address.", "pattern": "^0x[0-9a-f]{40}$", "example": "0x8ba1f109551bd432803012645ac136ddd64dba72" }, "account": { "type": "string", "description": "The owner's Polymarket deposit wallet (its trading wallet) — **lowercase**, and not equal to `wallet`.", "pattern": "^0x[0-9a-f]{40}$", "example": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b" }, "market": { "type": "string", "description": "`polymarket:0x<64-hex condition id>` or a bare condition id. Binary markets only.", "example": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a" }, "operation": { "type": "string", "enum": [ "split", "merge", "redeem" ], "description": "`split` — pUSD into one of each outcome token; `merge` — one of each outcome token back into pUSD; `redeem` — winning outcome tokens into pUSD on a resolved market." }, "amountRaw": { "type": "string", "description": "Canonical integer string > 0, 6-decimal base units (`\"1000000\"` = 1 pUSD or 1 share). Split and merge: the collateral and the per-outcome amount. Redeem: outcome tokens burned.", "example": "1000000" }, "outcome": { "type": "integer", "enum": [ 0, 1 ], "description": "Outcome index to redeem. Required for `redeem`, refused otherwise." }, "submissionOwner": { "type": "string", "enum": [ "kairos", "client" ], "description": "Who submits the signed batch. Use `kairos` unless you have arranged submission access with Kairos." }, "executeBefore": { "type": "string", "format": "date-time", "description": "In the future, at most 300 s out, whole seconds. Also the batch's on-chain deadline.", "example": "2026-10-28T12:04:00Z" }, "dependencies": { "type": "array", "description": "Earlier intents on the same deposit wallet that must confirm first. At most 16, distinct.", "maxItems": 16, "default": [], "items": { "type": "string", "format": "uuid" } } } }, "WalletTradePlanReportsRequest": { "type": "object", "additionalProperties": false, "required": [ "planHash", "reports" ], "properties": { "planHash": { "type": "string" }, "reports": { "type": "array", "minItems": 1, "maxItems": 32, "items": { "type": "object", "additionalProperties": false, "required": [ "requestId", "requestHash", "providerRequestId" ], "properties": { "requestId": { "type": "string", "example": "funding-1" }, "requestHash": { "type": "string", "description": "The request's `requestHash`." }, "providerRequestId": { "type": "string", "description": "Equals `funding.providerRequestId`." } } } } } }, "WalletTradePlanAnswersRequest": { "type": "object", "additionalProperties": false, "description": "Body of `/answers` and `/execute`.", "required": [ "planHash", "answers" ], "properties": { "planHash": { "type": "string", "description": "Must equal the plan's `planHash`." }, "answers": { "type": "array", "maxItems": 32, "items": { "$ref": "#/components/schemas/WalletTradePlanAnswer" } } }, "example": { "planHash": "0xb3d5c6e930ee2015f733bd9ffa2a2302fedd2a5bf38628e220f0b675d50f6953", "answers": [ { "kind": "signature", "requestId": "plan", "signature": "0xb2befc57fa7365cd671c908b8ba106005520bbd0fdb7212c8ea2134a6f2ff38a1b41a830b69eb1f51b7f1520681382729fdd1630ee70b131aac7b9059195de081c" }, { "kind": "signature", "requestId": "trade", "signature": "0xe09dacdd8731b4d1d972464ff7c88b1b9bb892273460f5be18304747af897c5c0764badc6c1a57bf5c0f92bfa1ef908b34ab4eb4772381d72f5df6bb8007e3541c" } ] } }, "WalletTradePlanAnswer": { "description": "One answer, tagged by `kind`. Only `signature` answers are accepted; `transaction` answers are refused.", "oneOf": [ { "$ref": "#/components/schemas/WalletTradePlanSignatureAnswer" }, { "$ref": "#/components/schemas/WalletTradePlanTransactionAnswer" } ], "discriminator": { "propertyName": "kind", "mapping": { "signature": "#/components/schemas/WalletTradePlanSignatureAnswer", "transaction": "#/components/schemas/WalletTradePlanTransactionAnswer" } } }, "WalletTradePlanTransactionAnswer": { "type": "object", "additionalProperties": false, "description": "Reserved; currently refused with `400 invalid trade plan: transaction answers require independent chain verification`.", "required": [ "kind", "requestId", "transactionHash" ], "properties": { "kind": { "type": "string", "const": "transaction" }, "requestId": { "type": "string" }, "transactionHash": { "type": "string" } } }, "WalletTradePlanSignatureAnswer": { "type": "object", "additionalProperties": false, "required": [ "kind", "requestId", "signature" ], "properties": { "kind": { "type": "string", "const": "signature" }, "requestId": { "type": "string", "description": "`requests[].id`.", "example": "plan" }, "signature": { "type": "string", "description": "65-byte ECDSA signature (low-s) from `wallet`." } } }, "WalletFeeSettlementRequiredError": { "type": "object", "description": "`409` from `POST /v3/trade-plans` when the trading wallet's unpaid fees on the plan's collateral are at or above the partner's settlement threshold. Settle through `POST /v3/fees/settlements`, poll until `confirmed`, then prepare again.", "required": [ "error", "code", "assetKey", "owedRaw", "thresholdRaw" ], "properties": { "error": { "type": "string", "example": "unpaid trading fees must be settled before the next trade" }, "code": { "type": "string", "const": "FEE_SETTLEMENT_REQUIRED" }, "assetKey": { "type": "string", "description": "Collateral asset, `evm::`.", "example": "evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb" }, "owedRaw": { "type": "string", "description": "Unpaid fees, integer string in token base units.", "example": "10400000" }, "thresholdRaw": { "type": "string", "description": "The partner's settlement threshold in the same units.", "example": "10000000" } } }, "WalletTradePlan": { "type": "object", "description": "A trade plan. Statuses: `needs_signatures` → `ready_to_execute` → (`/execute`) `funding_pending` → `trade_pending` → `completed`, with `reconciling` while an outcome is being confirmed. Terminal: `completed`, `expired`, `failed`, `funded_trade_failed`, `funded_trade_expired`.\n\n`audience` and `tradeExecutionRegion` are opaque values signed into the plan — do not interpret or change them.", "required": [ "contractVersion", "id", "planHash", "revision", "wallet", "partnerId", "audience", "interactionMode", "submission", "status", "venue", "tradeExecutionRegion", "order", "tradingWallet", "tradePayloadDigest", "tradeBudget", "funding", "createdAt", "executeBefore", "tradeSubmitBefore", "requests", "execution", "error" ], "properties": { "contractVersion": { "type": "integer", "const": 1 }, "id": { "type": "string", "format": "uuid" }, "planHash": { "type": "string", "description": "Hash of the plan's terms; every answer must echo it." }, "revision": { "type": "string", "description": "Increases on every stored change (`\"0\"` at prepare)." }, "wallet": { "type": "string", "description": "The signing wallet, lowercase." }, "ctfDependencies": { "type": "array", "items": { "$ref": "#/components/schemas/WalletCtfDependency" } }, "partnerId": { "type": "string" }, "audience": { "type": "string", "description": "Opaque signed field." }, "interactionMode": { "type": "string", "enum": [ "single_batch", "allow_followup" ] }, "submission": { "$ref": "#/components/schemas/WalletTradePlanSubmission" }, "status": { "type": "string", "enum": [ "needs_signatures", "ready_to_execute", "funding_pending", "trade_pending", "reconciling", "completed", "expired", "failed", "funded_trade_failed", "funded_trade_expired" ] }, "venue": { "$ref": "#/components/schemas/WalletVenue" }, "tradeExecutionRegion": { "type": "string", "description": "Opaque signed field." }, "order": { "$ref": "#/components/schemas/WalletTradePlanOrderTerms" }, "tradingWallet": { "type": "string", "description": "Where the collateral must sit — Polymarket's trading wallet, or the wallet itself on Predict.fun and Hyperliquid." }, "tradePayloadDigest": { "type": "string", "description": "Signing digest of the `trade` request." }, "tradeBudget": { "$ref": "#/components/schemas/WalletTradePlanBudget" }, "funding": { "oneOf": [ { "$ref": "#/components/schemas/WalletTradePlanFunding" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "executeBefore": { "type": "string", "format": "date-time", "description": "Deadline for answers and `/execute` — `funding.fundingSubmitBefore` when funded, else `tradeSubmitBefore`." }, "tradeSubmitBefore": { "type": "string", "format": "date-time" }, "requests": { "type": "array", "minItems": 2, "maxItems": 32, "items": { "$ref": "#/components/schemas/WalletTradePlanRequest" } }, "execution": { "$ref": "#/components/schemas/WalletTradePlanExecution" }, "error": { "oneOf": [ { "$ref": "#/components/schemas/WalletPlanErrorView" }, { "type": "null" } ] } }, "example": { "contractVersion": 1, "id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "planHash": "0xb3d5c6e930ee2015f733bd9ffa2a2302fedd2a5bf38628e220f0b675d50f6953", "revision": "0", "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "partnerId": "acme", "audience": "https://staging-execution.kairos.trade", "interactionMode": "single_batch", "submission": { "funding": "kairos", "trade": "kairos" }, "status": "needs_signatures", "venue": "polymarket", "tradeExecutionRegion": "opaque-region-id", "order": { "market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a", "outcome": "Yes", "side": "buy", "price": "0.05", "size": "10", "timeInForce": "GTC", "postOnly": true, "clientOrderId": "partner-trade-1042" }, "tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "tradePayloadDigest": "0xa3612e136ad81349bbc469dbc02ebd85d3cfcd3f76f90fc06a5c33d6bd03a67a", "tradeBudget": { "collateral": { "kind": "evm", "chainId": "137", "token": "0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb" }, "decimals": 6, "notionalRaw": "500000", "maxCollateralFeeRaw": "16750", "maxPlatformFeeBps": 75, "maxDebitRaw": "516750", "existingSpendableRaw": "0", "partnerFee": { "scheduleId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d", "maxBps": 25, "maker": { "model": "flat", "bps": 10 }, "taker": { "model": "flat", "bps": 25 } } }, "funding": { "sourceChainId": "42161", "sourceToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "sourceDecimals": 6, "quoteId": "wallet-funding:0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "providerRequestId": "0x5d7e9f1a3b5c7d9e1f3a5b7c9d1e3f5a7b9c1d3e5f7a9b1c3d5e7f9a1b3c5d7e", "amountInRaw": "531200", "maxGasCostRaw": "0", "destination": { "kind": "evm", "chainId": "137", "token": "0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb" }, "destinationDecimals": 6, "recipient": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "refundRecipient": "0x8ba1f109551bd432803012645ac136ddd64dba72", "requiredArrivalRaw": "516750", "minimumArrivalRaw": "516750", "expectedArrivalRaw": "517900", "quoteExpiresAt": "2026-10-28T12:02:00Z", "fundingSubmitBefore": "2026-10-28T12:02:00Z", "maxAmountRaw": "750000", "slippageBps": 50 }, "createdAt": "2026-10-28T12:00:00Z", "executeBefore": "2026-10-28T12:02:00Z", "tradeSubmitBefore": "2026-10-28T12:04:00Z", "requests": [ { "id": "plan", "purpose": "plan", "kind": "signature", "signer": "0x8ba1f109551bd432803012645ac136ddd64dba72", "chainId": "0x89", "request": { "method": "eth_signTypedData_v4", "params": [ "0x8ba1f109551bd432803012645ac136ddd64dba72", "{\"domain\":{\"chainId\":137,\"name\":\"KairosTradePlan\",\"version\":\"1\"},\"message\":{\"audience\":\"https://staging-execution.kairos.trade\",\"executeBefore\":\"1793188920\",\"partnerId\":\"acme\",\"planHash\":\"0xb3d5…6953\",\"planId\":\"0b1c2d3e-…\",\"tradeSubmitBefore\":\"1793189040\",\"wallet\":\"0x8ba1…ba72\"},\"primaryType\":\"TradePlan\",\"types\":{…}}" ] }, "requestHash": "0x164f42fed95c09f82995ceb0d79c95e4074f81d9165c7ec449ffe4f5e15ace6e", "collectAfter": [], "executeAfter": [], "status": "ready", "actionable": true }, { "id": "funding-1", "purpose": "funding", "kind": "signature", "signer": "0x8ba1f109551bd432803012645ac136ddd64dba72", "chainId": "0xa4b1", "request": { "method": "eth_signTypedData_v4", "params": [ "0x8ba1f109551bd432803012645ac136ddd64dba72", "{…}" ] }, "requestHash": "0x2a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c", "collectAfter": [], "executeAfter": [], "status": "ready", "actionable": true }, { "id": "funding-2", "purpose": "funding", "kind": "signature", "signer": "0x8ba1f109551bd432803012645ac136ddd64dba72", "chainId": "0xa4b1", "request": { "method": "eth_signTypedData_v4", "params": [ "0x8ba1f109551bd432803012645ac136ddd64dba72", "{…}" ] }, "requestHash": "0x3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d", "collectAfter": [], "executeAfter": [ "funding-1" ], "status": "ready", "actionable": true }, { "id": "trade", "purpose": "trade", "kind": "signature", "signer": "0x8ba1f109551bd432803012645ac136ddd64dba72", "chainId": "0x89", "request": { "method": "eth_signTypedData_v4", "params": [ "0x8ba1f109551bd432803012645ac136ddd64dba72", "{…}" ] }, "requestHash": "0x0949c4fc3fec5036e82047f68491e76ea6d7a10b11c8bb5c5b04aa62969a1297", "collectAfter": [], "executeAfter": [ "funding-1", "funding-2" ], "status": "ready", "actionable": true } ], "execution": { "committed": false, "phase": "collecting", "fundingStatus": "not_started", "tradeStatus": "not_started" }, "error": null } }, "WalletPlanErrorView": { "type": "object", "description": "Why a plan is in flight or stopped (returned with HTTP `200`).\n\n| `code` | Meaning |\n|---|---|\n| `OUTCOME_UNKNOWN` | Funding or the trade is in flight; keep polling (`nextAction: reconcile`). |\n| `PLAN_EXPIRED` | Not executed before `executeBefore`. |\n| `TRADE_EXPIRED` | The order was not submitted by `tradeSubmitBefore`, or funding arrived after it. |\n| `FUNDING_SHORTFALL` | Less than `minimumArrivalRaw` arrived. |\n| `COLLATERAL_CHANGED` | The balance fell below `maxDebitRaw` before submission. |\n| `VENUE_REJECTED` | The venue refused the signed order. |\n| `PREFLIGHT_REFUSED` | A pre-submission check refused the order. |\n| `NATIVE_NOT_DISPATCHED` | The trade authorization expired before submission. |\n\n`nextAction` is `reconcile` (keep polling) or `inspect_funds` (terminal: check where the collateral is — bridged funds stay in `tradingWallet`).", "required": [ "code", "message", "nextAction" ], "properties": { "code": { "type": "string", "enum": [ "OUTCOME_UNKNOWN", "PLAN_EXPIRED", "TRADE_EXPIRED", "FUNDING_SHORTFALL", "COLLATERAL_CHANGED", "VENUE_REJECTED", "PREFLIGHT_REFUSED", "NATIVE_NOT_DISPATCHED" ] }, "message": { "type": "string" }, "nextAction": { "type": "string", "enum": [ "reconcile", "inspect_funds" ] } } }, "WalletTradePlanExecution": { "type": "object", "description": "Progress of a committed plan.", "required": [ "committed", "phase", "fundingStatus", "tradeStatus" ], "properties": { "committed": { "type": "boolean" }, "phase": { "type": "string", "enum": [ "collecting", "funding", "trade", "finished" ] }, "fundingStatus": { "type": "string", "enum": [ "not_required", "not_started", "pending", "awaiting_client", "unknown", "confirmed" ], "description": "`unknown` while the bridge is in flight or uncertain." }, "tradeStatus": { "type": "string", "enum": [ "not_started", "unknown", "accepted", "failed", "expired" ], "description": "`accepted` — the venue acknowledged the order (not necessarily filled)." }, "movementId": { "type": "string", "description": "The bridge provider's request id, once known." }, "orderId": { "type": "string", "description": "Kairos order id." }, "venueOrderId": { "type": "string" }, "venueOrderStatus": { "type": "string", "example": "live" }, "confirmedArrivalRaw": { "type": "string", "description": "Collateral confirmed at the destination." } } }, "WalletTradePlanRequest": { "type": "object", "description": "One signature the plan needs, in order:\n- `plan` — `KairosTradePlan` typed data binding `wallet`, `partnerId`, `audience`, `planId`, `planHash`, `executeBefore`, `tradeSubmitBefore`; on the venue's chain.\n- `funding-1`, `funding-2` — funded plans only, on the **source** chain: the bridge authorization, then the USDC `ReceiveWithAuthorization` permit.\n- `trade` — the venue order (Polymarket and Predict.fun native orders; a Kairos `PlaceOrder` authorization on Hyperliquid); on the venue's chain.\n\nSign every request whose `actionable` is `true`. `params[1]` of typed-data requests is a JSON string — pass it unchanged.", "required": [ "id", "purpose", "kind", "signer", "chainId", "request", "requestHash", "collectAfter", "executeAfter", "status", "actionable" ], "properties": { "id": { "type": "string", "example": "plan" }, "purpose": { "type": "string", "enum": [ "plan", "trade", "funding" ] }, "kind": { "type": "string", "const": "signature" }, "signer": { "type": "string", "description": "Equals `wallet`." }, "chainId": { "type": [ "string", "null" ], "description": "Chain to sign on, hex.", "example": "0x89" }, "request": { "$ref": "#/components/schemas/WalletEip1193Request" }, "requestHash": { "type": "string", "description": "Hash of the canonical request; pinned by `planHash`." }, "collectAfter": { "type": "array", "items": { "type": "string" } }, "executeAfter": { "type": "array", "description": "Requests that must run before this one (e.g. `trade` after the funding ids).", "items": { "type": "string" } }, "externalSubmission": { "$ref": "#/components/schemas/WalletTradePlanExternalSubmission" }, "status": { "type": "string", "enum": [ "ready", "accepted", "confirmed" ], "description": "`ready` → `accepted` (signature stored) → `confirmed` (executed)." }, "actionable": { "type": "boolean", "description": "`true` when the client should sign this request now." } } }, "WalletTradePlanExternalSubmission": { "type": "object", "description": "Client-owned funding only: POST the signed permit here yourself, `funding-1` first, with `{kind, requestId, api}` as the body and the signature as the `signature` query parameter.", "required": [ "endpoint", "method", "kind", "requestId", "api" ], "properties": { "endpoint": { "type": "string", "format": "uri" }, "method": { "type": "string", "const": "POST" }, "kind": { "type": "string", "enum": [ "multicall-authorization", "eip3009" ] }, "requestId": { "type": "string", "description": "Equals `funding.providerRequestId`." }, "api": { "type": [ "string", "null" ], "description": "The Relay API to call; `swap` on every current route." } } }, "WalletTradePlanFunding": { "type": "object", "description": "The funding quote. Raw amounts are integer strings in base units.", "required": [ "sourceChainId", "sourceToken", "sourceDecimals", "quoteId", "providerRequestId", "amountInRaw", "maxGasCostRaw", "destination", "destinationDecimals", "recipient", "refundRecipient", "requiredArrivalRaw", "minimumArrivalRaw", "expectedArrivalRaw", "quoteExpiresAt", "fundingSubmitBefore", "maxAmountRaw", "slippageBps" ], "properties": { "sourceChainId": { "type": "string" }, "sourceToken": { "type": "string" }, "sourceDecimals": { "type": "integer" }, "quoteId": { "type": "string", "description": "Opaque quote id." }, "providerRequestId": { "type": "string", "description": "The bridge provider's request id." }, "amountInRaw": { "type": "string", "description": "Source debit including bridge fees (at most `maxAmountRaw`)." }, "maxGasCostRaw": { "type": "string", "description": "Always `\"0\"`." }, "destination": { "$ref": "#/components/schemas/WalletCollateral" }, "destinationDecimals": { "type": "integer" }, "recipient": { "type": "string", "description": "Equals `tradingWallet`." }, "refundRecipient": { "type": "string", "description": "Equals `wallet`; the bridge provider returns a failed bridge here, on the source chain." }, "requiredArrivalRaw": { "type": "string", "description": "The shortfall — `maxDebitRaw` minus what is already spendable." }, "minimumArrivalRaw": { "type": "string", "description": "Guaranteed floor, at least `requiredArrivalRaw`. Arrival below it fails the plan (`FUNDING_SHORTFALL`)." }, "expectedArrivalRaw": { "type": "string", "description": "Estimate." }, "quoteExpiresAt": { "type": "string", "format": "date-time" }, "fundingSubmitBefore": { "type": "string", "format": "date-time", "description": "Deadline for the funding permits; also the plan's `executeBefore`." }, "maxAmountRaw": { "type": "string" }, "slippageBps": { "type": "integer" } } }, "WalletCollateral": { "description": "A collateral asset, tagged by `kind`.", "oneOf": [ { "$ref": "#/components/schemas/WalletCollateralEvm" }, { "$ref": "#/components/schemas/WalletCollateralHypercore" } ], "discriminator": { "propertyName": "kind", "mapping": { "evm": "#/components/schemas/WalletCollateralEvm", "hypercore": "#/components/schemas/WalletCollateralHypercore" } } }, "WalletCollateralHypercore": { "type": "object", "required": [ "kind", "environment", "ledger", "token" ], "properties": { "kind": { "type": "string", "const": "hypercore" }, "environment": { "type": "string", "enum": [ "mainnet", "testnet" ] }, "ledger": { "type": "string", "const": "spot" }, "token": { "type": "string", "const": "USDC" } } }, "WalletCollateralEvm": { "type": "object", "required": [ "kind", "chainId", "token" ], "properties": { "kind": { "type": "string", "const": "evm" }, "chainId": { "type": "string", "description": "Decimal chain id.", "example": "137" }, "token": { "type": "string", "description": "Token address.", "example": "0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb" } } }, "WalletTradePlanBudget": { "type": "object", "description": "The collateral ceiling the wallet authorizes. Raw amounts are integer strings in collateral base units.", "required": [ "collateral", "decimals", "notionalRaw", "maxCollateralFeeRaw", "maxPlatformFeeBps", "maxDebitRaw", "existingSpendableRaw" ], "properties": { "collateral": { "$ref": "#/components/schemas/WalletCollateral" }, "decimals": { "type": "integer", "description": "6 (pUSD, Hyperliquid USDC) or 18 (BNB Chain USDT)." }, "notionalRaw": { "type": "string", "description": "Order notional." }, "maxCollateralFeeRaw": { "type": "string", "description": "Upper bound on fees: `notional × maxPlatformFeeBps / 10000` plus the venue's own fee bound, rounded up." }, "maxPlatformFeeBps": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Kairos maximum plus `partnerFee.maxBps`. Prepare is refused (`422`) above 1000 (10%)." }, "maxDebitRaw": { "type": "string", "description": "`notionalRaw + maxCollateralFeeRaw` — the most this plan can take from the trading account." }, "existingSpendableRaw": { "type": "string", "description": "Collateral already available at the venue, net of other plans' holds, when prepared (a snapshot, not a reservation)." }, "partnerFee": { "$ref": "#/components/schemas/WalletPartnerFeeTerms" } } }, "WalletPartnerFeeTerms": { "type": "object", "description": "The partner fee this plan pins, signed by the wallet as part of the plan. Partner fee schedules are configured by Kairos for each partner — a default, optionally per venue, optionally per user — as up to 16 bands selected by order notional (USD) and the user's 30-day trading volume; each band has a maker and a taker shape. The band in force when the plan is prepared is pinned here; later schedule changes do not affect the plan.\n\nAt fill time the partner rate is `maker` or `taker` evaluated at the fill price, charged on notional. Combined with the Kairos rate it never exceeds `tradeBudget.maxPlatformFeeBps` (at most 1000 bps, 10%). Polymarket and Predict.fun only.", "required": [ "scheduleId", "maxBps", "maker", "taker" ], "properties": { "scheduleId": { "type": "string", "format": "uuid" }, "maxBps": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "The highest rate either shape reaches." }, "maker": { "$ref": "#/components/schemas/WalletFeeShape" }, "taker": { "$ref": "#/components/schemas/WalletFeeShape" } } }, "WalletFeeShape": { "description": "How a partner fee rate varies with the fill price `p` (0–1). Rates are integer bps, 0–1000.", "oneOf": [ { "$ref": "#/components/schemas/WalletFeeShapeFlat" }, { "$ref": "#/components/schemas/WalletFeeShapeCurve" }, { "$ref": "#/components/schemas/WalletFeeShapeParabolic" } ], "discriminator": { "propertyName": "model", "mapping": { "flat": "#/components/schemas/WalletFeeShapeFlat", "curve": "#/components/schemas/WalletFeeShapeCurve", "parabolic": "#/components/schemas/WalletFeeShapeParabolic" } } }, "WalletFeeShapeParabolic": { "type": "object", "description": "`edgeBps + 4·(centerBps − edgeBps)·p·(1 − p)` — `edgeBps` at prices 0 and 1, `centerBps` at 0.5 (may be lower than the edge).", "required": [ "model", "edgeBps", "centerBps" ], "properties": { "model": { "type": "string", "const": "parabolic" }, "edgeBps": { "type": "integer", "minimum": 0, "maximum": 1000 }, "centerBps": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "example": { "model": "parabolic", "edgeBps": 5, "centerBps": 40 } }, "WalletFeeShapeCurve": { "type": "object", "description": "Linear between points (2–32, prices strictly increasing within 0–1), flat beyond the end points.", "required": [ "model", "points" ], "properties": { "model": { "type": "string", "const": "curve" }, "points": { "type": "array", "minItems": 2, "maxItems": 32, "items": { "type": "object", "required": [ "price", "feeBps" ], "properties": { "price": { "type": "string", "description": "Decimal string, 0–1." }, "feeBps": { "type": "integer", "minimum": 0, "maximum": 1000 } } } } }, "example": { "model": "curve", "points": [ { "price": "0", "feeBps": 10 }, { "price": "0.5", "feeBps": 60 }, { "price": "1", "feeBps": 10 } ] } }, "WalletFeeShapeFlat": { "type": "object", "description": "The same rate at every price.", "required": [ "model", "bps" ], "properties": { "model": { "type": "string", "const": "flat" }, "bps": { "type": "integer", "minimum": 0, "maximum": 1000 } }, "example": { "model": "flat", "bps": 25 } }, "WalletTradePlanOrderTerms": { "type": "object", "additionalProperties": false, "description": "The order. Decimals must be **canonical** (`\"0.5\"`, not `\"0.50\"`; `\"1\"`, not `\"1.0\"`). `size` must match the venue's share lot exactly.\nHyperliquid: whole-share `size`, at most 5 price decimals, `GTC`/`FAK`/`IOC` only.\nIn a response this is the **effective** order — check it before signing: `outcome` is canonical and on Predict.fun a `GTC` order may come back as `GTD` with `expiresAt` set.", "required": [ "market", "outcome", "side", "price", "size", "timeInForce", "postOnly", "clientOrderId" ], "properties": { "market": { "type": "string", "description": "`venue:market_id` (required form here) — `polymarket:0x<64-hex>`, `predictfun:`, `hyperliquid:`.", "example": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a" }, "outcome": { "type": "string", "minLength": 1, "maxLength": 64, "example": "Yes" }, "side": { "type": "string", "const": "buy", "description": "Trade plans are buy-only." }, "price": { "type": "string", "description": "Canonical decimal, above 0 and below 1.", "example": "0.05" }, "size": { "type": "string", "description": "Canonical decimal, shares.", "example": "10" }, "timeInForce": { "type": "string", "enum": [ "GTC", "GTD", "FOK", "FAK", "IOC" ] }, "postOnly": { "type": "boolean", "description": "Only with `GTC` or `GTD`." }, "clientOrderId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Required. Printable ASCII, unique per wallet and venue across plans; must not start with `trade-plan:`.", "example": "partner-trade-1042" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Required exactly when `timeInForce` is `GTD`. RFC 3339, whole seconds, after `tradeSubmitBefore`." } } }, "WalletVenue": { "type": "string", "description": "Venue id. `predict.fun` is accepted as an input alias of `predictfun`.", "enum": [ "polymarket", "predictfun", "hyperliquid" ] }, "WalletTradePlanSubmission": { "type": "object", "additionalProperties": false, "description": "Who submits each part. Defaults to Kairos for both. `trade` accepts only `kairos`.", "properties": { "funding": { "type": "string", "enum": [ "kairos", "client" ], "default": "kairos", "description": "`client` — you POST the signed funding permits yourself (see `requests[].externalSubmission`) and report them." }, "trade": { "type": "string", "enum": [ "kairos" ], "default": "kairos" } } }, "WalletCtfDependency": { "type": "object", "description": "An on-chain intent this plan depends on, with the collateral it is expected to free.", "required": [ "intent", "anticipatedCreditRaw" ], "properties": { "intent": { "$ref": "#/components/schemas/WalletOnchainDependency" }, "anticipatedCreditRaw": { "type": "string" } } }, "WalletTradePlanPrepareRequest": { "type": "object", "additionalProperties": false, "description": "Body of `POST /v3/trade-plans`. camelCase; unknown fields are refused.", "required": [ "wallet", "interactionMode", "order", "tradeSubmitBefore" ], "properties": { "wallet": { "$ref": "#/components/schemas/WalletAddress" }, "ctfDependencies": { "type": "array", "description": "Polymarket only — ids of on-chain intents this buy depends on (e.g. a merge that frees collateral). At most 16, distinct.", "maxItems": 16, "items": { "type": "string", "format": "uuid" } }, "interactionMode": { "type": "string", "enum": [ "single_batch", "allow_followup" ], "description": "Both values currently behave the same — every request is a signature collected up front." }, "submission": { "$ref": "#/components/schemas/WalletTradePlanSubmission" }, "order": { "$ref": "#/components/schemas/WalletTradePlanOrderTerms" }, "funding": { "description": "Omit or `null` when the collateral is already at the venue.", "oneOf": [ { "$ref": "#/components/schemas/WalletTradePlanFundingInput" }, { "type": "null" } ] }, "tradeSubmitBefore": { "type": "string", "format": "date-time", "description": "Last moment Kairos may submit the order. RFC 3339 UTC, whole seconds, in the future and at most 5 minutes out.", "example": "2026-10-28T12:04:00Z" } } }, "WalletTradePlanFundingInput": { "type": "object", "additionalProperties": false, "description": "Bridge the shortfall from the wallet's USDC on another chain. Gasless permits; Kairos quotes exactly the amount the plan needs. Routes:\n\n| Source | → Polymarket (pUSD, Polygon) | → Predict.fun (USDT, BNB Chain) | → Hyperliquid (spot USDC, mainnet) |\n|---|---|---|---|\n| Polygon USDC (`137`, `0x3c499c542cef5e3811e1192ce70d8cc03d5c3359`) | no | yes | yes |\n| Arbitrum USDC (`42161`, `0xaf88d065e77c8cc2239327c5edb3a432268e5831`) | yes | yes | yes |\n\nAn unsupported route returns `503 no verified gasless funding route is available`.", "required": [ "sourceChainId", "sourceToken", "maxAmountRaw", "maxGasCostRaw", "slippageBps" ], "properties": { "sourceChainId": { "type": "string", "enum": [ "137", "42161" ], "description": "Decimal chain id." }, "sourceToken": { "type": "string", "description": "That chain's native USDC address.", "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" }, "maxAmountRaw": { "type": "string", "description": "Most the wallet will spend on the source chain, bridge fees included (integer string, base units, > 0).", "example": "750000" }, "maxGasCostRaw": { "type": "string", "description": "Gas cap; routes are gasless, so `\"0\"` works.", "example": "0" }, "slippageBps": { "type": "integer", "minimum": 0, "maximum": 10000, "example": 50 } } }, "WalletAddress": { "type": "string", "description": "EVM address, `0x` + 40 hex.", "pattern": "^0x[0-9a-fA-F]{40}$", "example": "0x8ba1f109551bd432803012645ac136ddd64dba72" }, "WalletFeeSettlementAnswer": { "type": "object", "additionalProperties": false, "description": "Send `signature` (Polymarket) or `transactionHash` (Predict.fun) — exactly one.", "required": [ "wallet" ], "properties": { "wallet": { "$ref": "#/components/schemas/WalletAddress" }, "signature": { "type": "string", "description": "Polymarket — 65-byte ECDSA signature of `walletRequest`, `0x`-prefixed hex (`v` of 0, 1, 27 or 28; low-s).", "pattern": "^0x[0-9a-fA-F]{130}$" }, "transactionHash": { "type": "string", "description": "Predict.fun — `0x` + 64 hex hash of the payment transaction (not all zeros).", "pattern": "^0x[0-9a-fA-F]{64}$" } } }, "WalletFeeSettlement": { "type": "object", "description": "A payment of a wallet's unpaid fees on one venue. The amount is frozen when the settlement opens.", "required": [ "id", "venue", "status", "holdingWallet", "assetKey", "chainId", "token", "treasury", "decimals", "amountRaw", "transactionHash", "expiresAt", "failure", "walletRequest" ], "properties": { "id": { "type": "string", "format": "uuid" }, "venue": { "type": "string", "enum": [ "polymarket", "predictfun" ] }, "status": { "type": "string", "enum": [ "awaiting_signature", "submitted", "confirmed", "failed", "expired" ], "description": "`awaiting_signature` → `submitted` → `confirmed`. Terminal: `confirmed` and `failed`. `expired` is final unless it is a Predict.fun settlement whose reported transaction lands within 7 days of expiring: `GET /v3/fees` or `POST /v3/fees/settlements` then credits it and it becomes `confirmed` (`GET /v3/fees/settlements/{id}` does not re-check an expired settlement)." }, "holdingWallet": { "type": "string", "description": "Address the fee is paid from — Polymarket's trading wallet, or the wallet itself on Predict.fun." }, "assetKey": { "type": "string", "example": "evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb" }, "chainId": { "type": "string", "description": "Chain id as a **decimal** string (`walletRequest.chainId` is hex).", "example": "137" }, "token": { "type": "string", "description": "Fee token (pUSD on Polygon, USDT on BNB Chain)." }, "treasury": { "type": "string", "description": "The payee address." }, "decimals": { "type": "integer", "description": "Token decimals (6 for pUSD, 18 for BNB Chain USDT)." }, "amountRaw": { "type": "string", "description": "Amount to pay, integer string in token base units." }, "transactionHash": { "type": [ "string", "null" ], "description": "The payment transaction, once known." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Polymarket — sign before this (30 minutes after opening). `null` on Predict.fun." }, "failure": { "type": [ "string", "null" ], "description": "Why the settlement failed or expired. Kept when a late Predict.fun payment later confirms an `expired` settlement." }, "walletRequest": { "description": "Present only while `awaiting_signature`.", "oneOf": [ { "$ref": "#/components/schemas/WalletFeeWalletRequest" }, { "type": "null" } ] } }, "example": { "id": "4e1d2c3b-5a6f-4b7c-8d9e-0f1a2b3c4d5e", "venue": "polymarket", "status": "awaiting_signature", "holdingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "assetKey": "evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb", "chainId": "137", "token": "0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb", "treasury": "0x3333333333333333333333333333333333333333", "decimals": 6, "amountRaw": "12500000", "transactionHash": null, "expiresAt": "2026-10-28T12:30:00Z", "failure": null, "walletRequest": { "kind": "signature", "chainId": "0x89", "request": { "method": "eth_signTypedData_v4", "params": [ "0x8ba1f109551bd432803012645ac136ddd64dba72", "{\"types\":{\"EIP712Domain\":[…],\"Batch\":[{\"name\":\"wallet\",\"type\":\"address\"},{\"name\":\"nonce\",\"type\":\"uint256\"},{\"name\":\"deadline\",\"type\":\"uint256\"},{\"name\":\"calls\",\"type\":\"Call[]\"}],\"Call\":[…]},\"domain\":{\"name\":\"DepositWallet\",\"version\":\"1\",\"chainId\":\"137\",\"verifyingContract\":\"0x2f9c…4c3b\"},\"primaryType\":\"Batch\",\"message\":{…}}" ] } } } }, "WalletFeeWalletRequest": { "type": "object", "description": "What the wallet runs to pay a settlement. `kind: signature` (Polymarket) — sign it and answer with `signature`; `kind: transaction` (Predict.fun) — send it unchanged and answer with `transactionHash`.", "required": [ "kind", "chainId", "request" ], "properties": { "kind": { "type": "string", "enum": [ "signature", "transaction" ] }, "chainId": { "type": "string", "description": "Chain to switch to, **hex** (`0x89` or `0x38`)." }, "request": { "$ref": "#/components/schemas/WalletEip1193Request" } }, "example": { "kind": "transaction", "chainId": "0x38", "request": { "method": "eth_sendTransaction", "params": [ { "from": "0x8ba1f109551bd432803012645ac136ddd64dba72", "to": "0x55d398326f99059ff775485246999027b3197955", "value": "0x0", "data": "0xa9059cbb0000000000000000000000003333333333333333333333333333333333333333000000000000000000000000000000000000000000000000ad78ebc5ac620000", "chainId": "0x38" } ] } } }, "WalletFeeSettlementCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "wallet", "venue" ], "properties": { "wallet": { "$ref": "#/components/schemas/WalletAddress" }, "venue": { "type": "string", "enum": [ "polymarket", "predictfun" ] } } }, "WalletFeeSummary": { "type": "object", "description": "Response of `GET /v3/fees`.", "required": [ "venues" ], "properties": { "venues": { "type": "array", "items": { "$ref": "#/components/schemas/WalletFeeVenue" } } }, "example": { "venues": [ { "venue": "polymarket", "holdingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "assetKey": "evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb", "decimals": 6, "owedRaw": "400000", "thresholdRaw": "10000000", "settlement": null }, { "venue": "predictfun", "holdingWallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "assetKey": "evm:56:0x55d398326f99059ff775485246999027b3197955", "decimals": 18, "owedRaw": "0", "thresholdRaw": "10000000000000000000", "settlement": null } ] } }, "WalletFeeVenue": { "type": "object", "description": "Fee debt on one venue. Values are integer strings in token base units.", "required": [ "venue", "holdingWallet", "assetKey", "decimals", "owedRaw", "thresholdRaw", "settlement" ], "properties": { "venue": { "type": "string", "enum": [ "polymarket", "predictfun" ] }, "holdingWallet": { "type": "string" }, "assetKey": { "type": "string", "example": "evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb" }, "decimals": { "type": "integer", "example": 6 }, "owedRaw": { "type": "string", "description": "Unpaid Kairos and partner fees, minus confirmed payments. **May be negative** (a credit against later fees).", "example": "-250000" }, "thresholdRaw": { "type": "string", "description": "At or above this, new trade plans are refused with `FEE_SETTLEMENT_REQUIRED`.", "example": "10000000" }, "settlement": { "description": "The settlement that was open when this read started, refreshed by it — so it may already be `confirmed`, `failed` or `expired`. `null` when none was open.", "oneOf": [ { "$ref": "#/components/schemas/WalletFeeSettlement" }, { "type": "null" } ] } } }, "WalletPositionsResponse": { "type": "object", "description": "Response of `GET /v3/wallets/{address}/positions`. **Nested:** the rows are at `positions.positions`.", "required": [ "positions" ], "properties": { "positions": { "type": "object", "required": [ "positions", "resolved", "closed", "asOf" ], "properties": { "positions": { "type": "array", "description": "Open positions.", "items": { "$ref": "#/components/schemas/WalletPosition" } }, "resolved": { "type": "array", "description": "Positions in resolved markets.", "items": { "$ref": "#/components/schemas/WalletResolvedPosition" } }, "closed": { "type": "array", "description": "Positions closed out.", "items": { "type": "object", "required": [ "venue", "tokenId" ], "properties": { "venue": { "$ref": "#/components/schemas/WalletVenue" }, "tokenId": { "type": [ "string", "null" ] } } } }, "asOf": { "type": "string", "format": "date-time" } } }, "venueDetail": { "$ref": "#/components/schemas/WalletVenueReadError" } }, "example": { "positions": { "positions": [ { "venue": "polymarket", "market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a", "marketId": "0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a", "outcome": "Yes", "tokenId": "71321045679252212594626385532706912750332728571942532289631379312455583992563", "size": "4.5", "availableToSell": "4.5", "avgPrice": "0.52", "realizedPnl": "0", "holdingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "lastTradeAt": "2026-10-28T11:58:00Z" } ], "resolved": [], "closed": [], "asOf": "2026-10-28T12:00:00Z" } } }, "WalletVenueReadError": { "type": "object", "description": "Per-venue read failures, keyed by venue. Present only when some venue could not be read.", "additionalProperties": { "type": "object", "properties": { "error": { "type": "string" } } } }, "WalletResolvedPosition": { "type": "object", "required": [ "venue", "market", "marketId", "outcome", "tokenId", "size", "redeemable", "holdingWallet" ], "properties": { "venue": { "$ref": "#/components/schemas/WalletVenue" }, "market": { "type": "string" }, "marketId": { "type": "string" }, "outcome": { "type": [ "string", "null" ] }, "tokenId": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ] }, "redeemable": { "type": [ "boolean", "null" ], "description": "The shares can be redeemed for collateral." }, "holdingWallet": { "type": [ "string", "null" ] } } }, "WalletPosition": { "type": "object", "required": [ "venue", "market", "marketId", "outcome", "tokenId", "size", "availableToSell", "avgPrice", "realizedPnl", "holdingWallet", "lastTradeAt" ], "properties": { "venue": { "$ref": "#/components/schemas/WalletVenue" }, "market": { "type": "string" }, "marketId": { "type": "string" }, "outcome": { "type": [ "string", "null" ] }, "tokenId": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ], "description": "Shares held." }, "availableToSell": { "type": [ "string", "null" ], "description": "Shares not reserved by open sell orders." }, "avgPrice": { "type": [ "string", "null" ], "description": "Average entry price, 0–1." }, "realizedPnl": { "type": [ "string", "null" ] }, "holdingWallet": { "type": [ "string", "null" ], "description": "The address that holds the shares." }, "lastTradeAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "WalletOrdersResponse": { "type": "object", "required": [ "orders" ], "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/WalletOrder" } }, "venueDetail": { "$ref": "#/components/schemas/WalletVenueReadError" } }, "example": { "orders": [ { "orderId": "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b", "venue": "predictfun", "market": "predictfun:1027194", "marketId": "1027194", "outcome": "Yes", "tokenId": "81517620335745318418347838710345678901234567890", "side": "buy", "type": "limit", "price": "0.52", "size": "10", "filledSize": "0", "avgFillPrice": null, "timeInForce": "GTD", "postOnly": false, "expiresAt": "2026-10-29T00:00:00Z", "status": "live", "venueOrderId": "512334:0x3c9a…", "clientOrderId": "acme-7f3a91", "createdAt": "2026-10-28T12:00:00Z", "updatedAt": "2026-10-28T12:00:01Z" } ] } }, "WalletOrder": { "type": "object", "description": "One order, in the shape every venue shares. Prices are 0–1 and sizes are shares, as decimal strings. No fee fields.", "required": [ "orderId", "venue", "market", "marketId", "outcome", "tokenId", "side", "type", "price", "size", "filledSize", "avgFillPrice", "timeInForce", "postOnly", "expiresAt", "status", "venueOrderId", "clientOrderId", "createdAt", "updatedAt" ], "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Kairos order id — use it to cancel." }, "venue": { "$ref": "#/components/schemas/WalletVenue" }, "market": { "type": "string", "description": "`venue:market_id`." }, "marketId": { "type": "string" }, "outcome": { "type": [ "string", "null" ] }, "tokenId": { "type": [ "string", "null" ] }, "side": { "$ref": "#/components/schemas/OrderSide" }, "type": { "$ref": "#/components/schemas/OrderKind" }, "price": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ] }, "filledSize": { "type": [ "string", "null" ] }, "avgFillPrice": { "type": [ "string", "null" ] }, "timeInForce": { "$ref": "#/components/schemas/OrderTimeInForce" }, "postOnly": { "type": [ "boolean", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "venueOrderId": { "type": [ "string", "null" ] }, "clientOrderId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "OrderStatus": { "type": "string", "description": "Lifecycle status. `partial` is the wire spelling of a partially-filled order (NOT\n`partially_filled`).\n\nThe internal states `queued`, `locked` and `orphaned` are **persisted as `pending`**, so\nan order read back from `GET /orders` or `GET /orders/{order_id}` reports `pending` for\nall three — they are listed here because they are part of the type and can appear on\nin-process/streamed values. `executing` is the exception: once a worker claims the order\nfor submission it is persisted as `executing`, and read-back endpoints report `executing`\nuntil the venue acknowledges (then `live`) or the attempt fails. The one place a caller\nsees `queued` directly is the `status` field of a fresh `POST /orders` response, which is\nthe literal string `\"queued\"`.", "enum": [ "pending", "queued", "locked", "executing", "live", "partial", "filled", "cancelled", "expired", "failed", "orphaned" ], "example": "live" }, "OrderTimeInForce": { "type": "string", "description": "Time-in-force, always UPPER-CASE on the wire. `GTC`/`GTD` are resting (limit-style); `FOK`/`FAK`/`IOC` are immediate taker executions.", "enum": [ "GTC", "GTD", "FOK", "FAK", "IOC" ], "example": "GTC" }, "OrderKind": { "type": "string", "description": "Order type. `market` orders still require a `price` (the limit you'll cross to); `limit` orders rest at `price` until filled or cancelled.", "enum": [ "market", "limit" ], "example": "limit" }, "OrderSide": { "type": "string", "description": "Order/intent side. Lower-case on the wire.", "enum": [ "buy", "sell" ], "example": "buy" }, "WalletStatus": { "type": "object", "description": "Response of `GET /v3/wallets/{address}`.", "required": [ "wallet", "ready", "next", "venues" ], "properties": { "wallet": { "$ref": "#/components/schemas/WalletAddress" }, "ready": { "type": "boolean", "description": "Every venue that could be read is ready, and at least one could be read." }, "next": { "type": [ "string", "null" ], "enum": [ "setup", "wait", "fund", "blocked", null ], "description": "The most urgent next step across venues." }, "venues": { "type": "object", "description": "Readiness per venue offered on this deployment.", "additionalProperties": { "$ref": "#/components/schemas/WalletVenueStatus" } }, "tradingWallet": { "type": [ "string", "null" ], "description": "Polymarket's trading wallet, when Polymarket is offered." }, "balance": { "type": [ "string", "null" ], "description": "Polymarket's balance, when Polymarket is offered." } }, "example": { "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "ready": false, "next": "fund", "venues": { "polymarket": { "ready": true, "next": null, "tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "balance": "25", "currency": "pUSD", "venueDetail": { "chainId": "0x89" }, "asOf": "2026-10-28T12:00:00.125Z" }, "predictfun": { "ready": false, "next": "fund", "tradingWallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "balance": "0", "currency": "USDT", "venueDetail": { "chainId": "0x38", "gasBalance": "0", "missingApprovals": 3, "sessionExpiresAt": null }, "asOf": "2026-10-28T12:00:00.140Z" }, "hyperliquid": { "ready": true, "next": "fund", "tradingWallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "balance": "0", "currency": "USDC", "venueDetail": { "chainId": "0xa4b1", "network": "Mainnet", "transferFromPerps": { "available": "12.5", "note": "your next order asks you to move what it needs from perps to spot" } }, "asOf": "2026-10-28T12:00:00.180Z" } }, "tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "balance": "25" } }, "WalletVenueStatus": { "type": "object", "description": "One venue's readiness. A venue whose read failed is `{ready: false, available: false, error}`.", "required": [ "ready" ], "properties": { "ready": { "type": "boolean" }, "next": { "type": [ "string", "null" ], "enum": [ "setup", "wait", "fund", "blocked", null ], "description": "What to do on this venue." }, "tradingWallet": { "type": [ "string", "null" ], "description": "Where this venue's collateral sits — Polymarket's trading wallet, or the wallet itself on Predict.fun and Hyperliquid." }, "balance": { "type": [ "string", "null" ], "description": "Collateral available to trade, whole units (decimal string); `null` when unknown.", "example": "25" }, "currency": { "type": "string", "description": "`pUSD` (Polymarket), `USDT` (Predict.fun), `USDC` (Hyperliquid spot)." }, "venueDetail": { "$ref": "#/components/schemas/WalletVenueDetail" }, "asOf": { "type": "string", "format": "date-time", "description": "When the venue was read." }, "available": { "type": "boolean", "const": false, "description": "Present (and `false`) only when the venue could not be read." }, "error": { "type": "string", "description": "Why the venue could not be read." } } }, "WalletVenueDetail": { "type": "object", "description": "Venue-specific detail. Keys appear only where they apply.", "properties": { "chainId": { "type": "string", "description": "Chain the venue settles on (hex).", "example": "0x89" }, "gasBalance": { "type": [ "string", "null" ], "description": "Predict.fun — BNB balance for gas, whole units." }, "missingApprovals": { "type": "integer", "description": "Predict.fun — approvals still to send." }, "sessionExpiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Predict.fun — when the venue session ends." }, "network": { "type": "string", "description": "Hyperliquid — `Mainnet` or `Testnet`." }, "transferFromPerps": { "type": "object", "description": "Hyperliquid — USDC in perps the next order can move to spot (with an extra prompt).", "properties": { "available": { "type": "string", "example": "12.5" }, "note": { "type": "string" } } }, "code": { "type": "string", "description": "Hyperliquid — `HYPERLIQUID_AGENT_MISSING` when the trading approval must be renewed by `setup`." }, "reason": { "type": "string", "description": "Why the venue is not ready (fund, blocked, or approval renewal)." }, "blocked": { "type": "boolean", "description": "Hyperliquid — this account cannot be enrolled." }, "accountMode": { "type": "string", "description": "Hyperliquid — the account mode that blocks enrollment." }, "approvals": { "type": "integer", "description": "Setup result, Predict.fun — approvals the wallet needs gas for." }, "gasWei": { "type": "string", "description": "Setup result, Predict.fun — estimated BNB gas needed, in wei." } }, "additionalProperties": true }, "WalletPlainTextError": { "type": "string", "description": "A plain-text (non-JSON) rejection from request parsing — malformed JSON, a body of the wrong shape, a missing `Content-Type`, a malformed path id or query. Do not JSON-parse it.", "example": "Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string" }, "WalletActionAnswer": { "type": "object", "description": "Answer to a `needs_signature` step. Send `signature` for signature prompts (65 bytes, hex, `0x` optional); a JSON string in `result` is read as the signature. For `wallet_sendCalls`, send the wallet's return value (or the transaction hashes from `fallbackRequests`) as `result`.", "properties": { "signature": { "type": "string", "pattern": "^(0x)?[0-9a-fA-F]{130}$", "description": "65-byte ECDSA signature, hex (`0x` optional).", "example": "0x4f8b2c1d9e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c3d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e1b" }, "result": { "description": "The wallet's return value for `wallet_sendCalls`, or an array of transaction hashes." } } }, "WalletActionStep": { "type": "object", "description": "The current step of an action. Every response from `/v3/actions` and `/v3/actions/{id}` is one of these.", "required": [ "id", "type", "status", "request", "description", "chainId", "venue", "result", "error" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Action id. One id for the whole action, across venues." }, "type": { "type": "string", "enum": [ "setup", "order", "cancel", "login" ] }, "status": { "$ref": "#/components/schemas/WalletStepStatus" }, "request": { "description": "What the wallet must run. Non-null only while `needs_signature`.", "oneOf": [ { "$ref": "#/components/schemas/WalletEip1193Request" }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ], "description": "Text to show with the wallet prompt (e.g. `Confirm this Hyperliquid order`), or progress text while `working`." }, "chainId": { "type": [ "string", "null" ], "description": "EIP-155 chain id (hex) the wallet must be on to answer — `0x89` Polygon, `0x38` BNB Chain, `0xa4b1` Arbitrum One (`0x66eee` Arbitrum Sepolia on Hyperliquid testnet). `null` for `personal_sign` and when nothing is asked.", "example": "0x38" }, "venue": { "oneOf": [ { "$ref": "#/components/schemas/WalletVenue" }, { "type": "null" } ], "description": "Venue of the current prompt; `null` when finished and on cancels." }, "fallbackRequests": { "type": "array", "description": "Present with `wallet_sendCalls` requests only — the same calls as individual `eth_sendTransaction` requests, for wallets without EIP-5792. Send them in order and answer with `{\"result\": [\"0xhash\", …]}`.", "items": { "$ref": "#/components/schemas/WalletEip1193Request" } }, "expiresAtMs": { "type": "integer", "format": "int64", "description": "Last accepted millisecond (Unix ms) for answering this prompt. Answers after it fail the action with `SIGNATURE_EXPIRED`.", "example": 1793130772999 }, "holdUntilMs": { "type": "integer", "format": "int64", "description": "On a `working` order the venue is still matching — poll again after this time (Unix ms). `result` then holds a provisional outcome with `final: false`." }, "result": { "description": "Outcome on `done` (and the provisional outcome of a held order). Shape depends on `type`.", "oneOf": [ { "$ref": "#/components/schemas/WalletSetupResult" }, { "$ref": "#/components/schemas/WalletOrderResult" }, { "$ref": "#/components/schemas/WalletCancelResult" }, { "$ref": "#/components/schemas/WalletLoginResult" }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ], "description": "Why the action failed; non-null on `failed`." }, "errorCode": { "$ref": "#/components/schemas/WalletErrorCode" } } }, "WalletErrorCode": { "type": "string", "description": "Machine-readable reason on a `failed` step; the key is omitted when the failure has no code. Codes may be added; treat an unknown code as a failure whose order was not placed.\n\n| Code | Meaning | Order placed? |\n|---|---|---|\n| `NO_MATCH` | An immediate order (FOK/FAK/IOC) found nothing to match. | No |\n| `VENUE_REJECTED` | The venue refused the order. | No |\n| `ORDER_OUTCOME_UNKNOWN` | The submission's outcome is unknown. Read the wallet's orders before placing again. | Maybe |\n| `CANCEL_OUTCOME_UNKNOWN` | Some venue may have cancelled. Read the wallet's orders. | Maybe |\n| `SIGNATURE_EXPIRED` | The signing window closed before a signature was accepted. Nothing was sent. | No |\n| `CLIENT_ORDER_ID_CONFLICT` | The `clientOrderId` names an order with different terms. | No |\n| `HYPERLIQUID_AGENT_MISSING` | Hyperliquid no longer lists this wallet's trading approval. Run `setup` again. | No |", "enum": [ "NO_MATCH", "VENUE_REJECTED", "ORDER_OUTCOME_UNKNOWN", "CANCEL_OUTCOME_UNKNOWN", "SIGNATURE_EXPIRED", "CLIENT_ORDER_ID_CONFLICT", "HYPERLIQUID_AGENT_MISSING" ] }, "WalletLoginResult": { "type": "object", "description": "`result` of a `login` action. Send it as `Authorization: SIWE `.", "required": [ "token", "expiresAt" ], "properties": { "token": { "type": "string", "description": "Opaque sign-in token (at most 4096 bytes)." }, "expiresAt": { "type": "string", "format": "date-time", "description": "24 hours after issue." } } }, "WalletCancelResult": { "type": "object", "description": "`result` of a `cancel` action. If nothing was confirmed and a venue may have acted, the action fails with `CANCEL_OUTCOME_UNKNOWN` and keeps this result.", "required": [ "cancelled", "failed", "venueDetail" ], "properties": { "cancelled": { "type": "array", "items": { "type": "string" }, "description": "Order ids cancelled." }, "alreadyClosed": { "type": "array", "items": { "type": "string" }, "description": "By id — orders already filled, cancelled or expired." }, "failed": { "description": "By id — the failures; with `all` — the number of failures.", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/WalletCancelFailure" } }, { "type": "integer" } ] }, "venueDetail": { "type": "object", "description": "Per venue: `{cancelled, failed}` counts for `all`, or `{error}` when the venue could not be reached (`{error, code: \"CANCEL_OUTCOME_UNKNOWN\"}` when it may have cancelled). Empty when every venue answered on a by-id cancel.", "additionalProperties": { "type": "object", "properties": { "cancelled": { "type": "integer" }, "failed": { "type": "integer" }, "error": { "type": "string" }, "code": { "type": "string" } } } } }, "example": { "cancelled": [ "3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b" ], "alreadyClosed": [], "failed": [ { "orderId": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f", "reason": "order not found" } ], "venueDetail": {} } }, "WalletCancelFailure": { "type": "object", "required": [ "orderId", "reason" ], "properties": { "orderId": { "type": "string" }, "reason": { "type": "string", "description": "The venue's reason, `cancel failed; retry`, `order not found` (also for ids that are not this wallet's), `venue unavailable; retry`, or an outcome-unknown message." }, "code": { "type": "string", "description": "`CANCEL_OUTCOME_UNKNOWN` when the venue may have cancelled." } } }, "WalletOrderResult": { "type": "object", "description": "`result` of an `order` action. No fee fields: Kairos and venue fees are not reported here.", "required": [ "orderId", "status", "final", "success" ], "properties": { "orderId": { "type": "string", "format": "uuid", "description": "Kairos order id — use it to cancel." }, "status": { "type": "string", "description": "Order status: Polymarket's answer (`matched`, `live`, `delayed`, `unmatched`) or the Kairos order status on Hyperliquid (`executing`, `live`, `partial`, `filled`, `cancelled`, `failed`, …). Read `final` and `success` rather than matching on this.", "example": "matched" }, "venueOrderId": { "type": [ "string", "null" ] }, "venueStatus": { "type": [ "string", "null" ], "description": "The venue's first answer." }, "filledSize": { "type": [ "string", "null" ], "description": "Shares filled; `null` when unknown.", "example": "7.140348" }, "filledNotional": { "type": [ "string", "null" ], "description": "Collateral spent or received, before venue fees.", "example": "4.069998" }, "avgPrice": { "type": [ "string", "null" ], "example": "0.57" }, "final": { "type": "boolean", "description": "Matching is finished." }, "success": { "type": "boolean", "description": "`false` when the order did nothing, failed, or is not confirmed yet." }, "message": { "type": [ "string", "null" ], "description": "Set when `success` is false:\n- `No fill: the venue matched none of this order`\n- `The order failed at the venue; any fills shown were reverted`\n- `The venue rejected the order`\n- `Outcome not confirmed yet; check this wallet's orders before placing it again`" }, "venue": { "$ref": "#/components/schemas/WalletVenue" }, "market": { "type": "string", "description": "`venue:market_id`." } } }, "WalletSetupResult": { "type": "object", "description": "`result` of a `setup` action.", "required": [ "ready" ], "properties": { "ready": { "type": "boolean", "description": "Every requested venue is ready." }, "venues": { "type": "object", "description": "Outcome per requested venue.", "additionalProperties": { "$ref": "#/components/schemas/WalletSetupVenueResult" } }, "tradingWallet": { "type": [ "string", "null" ], "description": "Polymarket's trading wallet, when Polymarket was set up; `null` when Polymarket's setup failed." }, "transactionHash": { "type": [ "string", "null" ], "description": "Polymarket's approval transaction, when Polymarket was set up." } }, "example": { "ready": false, "venues": { "polymarket": { "ready": true, "tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "transactionHash": "0x7c3e9a1b5d2f4c6e8a0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c" }, "predictfun": { "ready": false, "next": "fund", "tradingWallet": "0x8ba1f109551bd432803012645ac136ddd64dba72", "venueDetail": { "reason": "needs about 0.0004 BNB on BNB Chain to pay gas for 2 Predict.fun approvals", "approvals": 2, "gasWei": "400000000000000" } } }, "tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b", "transactionHash": "0x7c3e9a1b5d2f4c6e8a0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c" } }, "WalletSetupVenueResult": { "type": "object", "description": "One venue's setup outcome.", "required": [ "ready" ], "properties": { "ready": { "type": "boolean" }, "tradingWallet": { "$ref": "#/components/schemas/WalletAddress" }, "transactionHash": { "type": [ "string", "null" ], "description": "Polymarket — the approval transaction, or `null` when none was needed." }, "sessionExpiresAt": { "type": "string", "format": "date-time", "description": "Predict.fun — when the venue session ends." }, "next": { "type": "string", "enum": [ "fund", "blocked" ], "description": "Why a venue that finished setup is not ready: `fund` (deposit, or BNB for gas) or `blocked`." }, "venueDetail": { "$ref": "#/components/schemas/WalletVenueDetail" }, "error": { "type": "string", "description": "This venue failed; the others may still have succeeded." } } }, "WalletStepStatus": { "type": "string", "description": "`needs_signature` — run `request` and answer; `working` — poll; `done` — read `result`; `failed` — read `error` and `errorCode`.", "enum": [ "needs_signature", "working", "done", "failed" ] }, "WalletActionRequest": { "type": "object", "description": "Body of `POST /v3/actions`. **camelCase only** — unknown fields, including snake_case spellings, are ignored without error.", "required": [ "wallet", "action" ], "properties": { "wallet": { "$ref": "#/components/schemas/WalletAddress" }, "action": { "$ref": "#/components/schemas/WalletAction" } } }, "WalletAction": { "description": "The action to run, tagged by `type`.", "oneOf": [ { "$ref": "#/components/schemas/WalletSetupAction" }, { "$ref": "#/components/schemas/WalletOrderAction" }, { "$ref": "#/components/schemas/WalletCancelAction" }, { "$ref": "#/components/schemas/WalletLoginAction" } ], "discriminator": { "propertyName": "type", "mapping": { "setup": "#/components/schemas/WalletSetupAction", "order": "#/components/schemas/WalletOrderAction", "cancel": "#/components/schemas/WalletCancelAction", "login": "#/components/schemas/WalletLoginAction" } } }, "WalletLoginAction": { "type": "object", "description": "Sign in with Ethereum (`personal_sign`, no gas) to get a 24-hour token for `Authorization: SIWE `. The wallet must have completed setup on at least one venue. The token is stateless: a second login does not revoke the first.", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "login" } } }, "WalletCancelAction": { "type": "object", "description": "Cancel orders on every venue with one signature. Send exactly one of `orderIds` (1–100 Kairos order ids) or `all: true`. The cancel is signed as Kairos typed data on Polygon (`chainId 0x89`) for every venue, so the wallet may be asked to switch to Polygon.", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "cancel" }, "orderIds": { "type": "array", "description": "Kairos `orderId`s (UUIDs), not venue order ids. A non-UUID is a plain-text `422`.", "minItems": 1, "maxItems": 100, "items": { "type": "string", "format": "uuid" } }, "all": { "type": "boolean", "description": "Cancel every open order of this wallet on every venue." } } }, "WalletOrderAction": { "type": "object", "description": "Place one order. Missing setup on the order's venue runs first, inside the same action. Signatures per order: Polymarket and Predict.fun one; Hyperliquid one, plus a perps-to-spot transfer prompt when spot USDC is short and perps can cover it.\n\nHyperliquid (HIP-4 outcome markets): `price` above 0 and below 1 with at most 5 decimals, whole-share `size`, `timeInForce` `GTC`, `FAK` or `IOC` only, `postOnly` only with `GTC`, a minimum notional on buys, and `clientOrderId` as `0x` + 32 lowercase hex.", "required": [ "type", "market", "outcome", "side", "price", "size" ], "properties": { "type": { "type": "string", "const": "order" }, "market": { "type": "string", "description": "`venue:market_id` — `polymarket:0x<64-hex condition id>`, `predictfun:`, `hyperliquid:` — or a bare Polymarket condition id.", "example": "predictfun:1027194" }, "outcome": { "type": "string", "description": "Outcome name as the venue lists it, e.g. `Yes`.", "example": "Yes" }, "side": { "type": "string", "description": "Case-insensitive.", "enum": [ "buy", "sell" ] }, "price": { "type": "string", "description": "Limit price on the 0–1 scale, as a **string**. A JSON number is rejected (`422`).", "example": "0.52" }, "size": { "type": "string", "description": "Shares, as a **string**.", "example": "10" }, "timeInForce": { "type": "string", "description": "Case-insensitive. `GTD` requires `expiresAt`. On Predict.fun a `GTC` order rests until shortly before the venue session ends.", "enum": [ "GTC", "GTD", "FOK", "FAK", "IOC" ], "default": "GTC" }, "postOnly": { "type": "boolean", "default": false }, "clientOrderId": { "type": "string", "maxLength": 128, "description": "Your idempotency key for this order. The same id with the same terms returns the existing order without a new signature; different terms fail with `CLIENT_ORDER_ID_CONFLICT`. Must not be blank or start with `trade-plan:`. Hyperliquid requires `0x` + 32 lowercase hex.", "example": "acme-7f3a91" }, "expiresAt": { "type": "integer", "format": "int64", "description": "Expiry for `GTD`, Unix **seconds** (an integer, not a string). Predict.fun caps it shortly before the venue session ends.", "example": 1793300000 } } }, "WalletSetupAction": { "type": "object", "description": "Prepare the wallet to trade. Per venue:\n- **Polymarket** (Polygon, `0x89`): one or two signatures, no gas — connect the wallet, then approve its trading wallet (a smart wallet owned by the user's address) when it is not approved yet.\n- **Predict.fun** (BNB Chain, `0x38`): when approvals are missing, one `wallet_sendCalls` batch the wallet pays BNB gas for; then a sign-in signature, no gas. Without enough BNB the venue ends `ready: false, next: \"fund\"`.\n- **Hyperliquid** (Arbitrum, `0xa4b1`; `0x66eee` on testnet): one or two signatures, no gas — allow Kairos to place trades for the account (it cannot withdraw), plus a builder-fee approval where one applies. An account that was never funded on Hyperliquid ends `ready: false, next: \"fund\"`.\n\nSetup continues past a venue that fails and fails only when every venue failed. A wallet already ready returns `done` at once.", "required": [ "type" ], "properties": { "type": { "type": "string", "const": "setup" }, "venues": { "type": "array", "description": "Venues to set up. Omitted or empty means every venue offered on this deployment. Case-insensitive; duplicates are ignored.", "items": { "$ref": "#/components/schemas/WalletVenue" } } } } }, "responses": { "WalletOnchainIntentNotFound": { "description": "`on-chain intent not found` — unknown, or not visible to this partner and wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "on-chain intent not found" } } } }, "WalletPlanExpired": { "description": "`plan authorization has expired` — `executeBefore` has passed. Prepare a new one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "plan authorization has expired" } } } }, "WalletPreviewUnavailable": { "description": "Production: `trade plans are disabled` until this lane is released (the trade-plan reads and writes other than prepare can return `500 internal error` there instead). Staging: a dependency is unavailable, `partner registry unavailable; retry shortly`, or `rate limiter unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "WalletTradePlanNotFound": { "description": "`trade plan not found` — unknown, or not visible to this partner and wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "trade plan not found" } } } }, "WalletFeesUnavailable": { "description": "`fee settlement storage is unavailable`; `the BNB Chain treasury is unavailable`; another settlement dependency is unavailable; `the chain RPC is unavailable`; `partner registry unavailable; retry shortly`; `rate limiter unavailable`. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "WalletScopeForbidden": { "description": "`API key missing trade:read scope` (reads) or `API key missing trade:execute scope` (writes) when an API key is the caller — `trade:execute` does not imply `trade:read`; or a tenant refusal: `unknown partner id`, `this partner id is used with its API key; send the key instead of X-Kairos-Partner-Id`, `this API key lacks the trade:execute scope`, `the wallet API is not enabled for this account`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "API key missing trade:read scope" } } } }, "WalletNotFound": { "description": "`wallet not found` — the sign-in token was signed by a different wallet, the API key's account does not own the wallet, or the wallet has never been set up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "wallet not found" } } } }, "WalletSignInUnauthorized": { "description": "Tenant failures (`send X-Kairos-Partner-Id or your API key (X-Client-Id, X-Api-Key, X-Api-Secret)`, `invalid API key`), or the wallet proof failed:\n- `malformed sign-in token` — not `SIWE ` as issued, over 4096 bytes, or an invalid lifetime\n- `sign-in token was issued for another partner or node` — issued for another partner or environment\n- `sign-in token has expired; run a login action`\n- `sign-in token signature is not from its wallet`\n- `Missing authorization` — no `Authorization` header and no API key to prove the wallet; `Invalid API credentials`, `API credential has been revoked` or `Invalid token` when the proving credential is not `SIWE` and fails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "sign-in token has expired; run a login action" } } } }, "WalletUnprocessable": { "description": "Plain text — the body is valid JSON of the wrong shape (a missing or unknown field, or a wrong type).", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "WalletGatewayTimeout": { "description": "`… did not answer in time; GET /v3/actions/{id} before retrying`. The request may have taken effect: read the state before repeating it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "WalletServiceUnavailable": { "description": "`partner registry unavailable; retry shortly`; `rate limiter unavailable` (the rate limiter fails closed); `wallet sign-in is not configured on this node`; ` is not available right now`. Retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "WalletVenueUnavailable": { "description": "A venue did not answer cleanly, e.g. `Hyperliquid is unavailable; retry shortly`, `Predict.fun is unavailable; retry shortly`. Retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "WalletTenantForbidden": { "description": "`unknown partner id` (unknown, or the Wallet API is not enabled for it); `this partner id is used with its API key; send the key instead of X-Kairos-Partner-Id`; `this API key lacks the trade:execute scope` (an API key must carry `trade:execute` to act as the tenant — a `trade:read`-only key is refused, even on reads); `the wallet API is not enabled for this account`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "unknown partner id" } } } }, "WalletInternalError": { "description": "`internal error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "internal error" } } } }, "WalletRateLimited": { "description": "`rate limit exceeded for this endpoint; retry later`. The default limit is 120 requests per minute per client IP per path (1000 when `X-Client-Id` is sent), over a sliding 60 s window; `GET` and `POST` on one path share it. No `Retry-After` header is sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "rate limit exceeded for this endpoint; retry later" } } } }, "WalletUnsupportedMediaType": { "description": "Plain text — the request has no `Content-Type: application/json` header.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } } } }, "WalletPayloadTooLarge": { "description": "Plain text (`Failed to buffer the request body: length limit exceeded`) when the body is over the limit: 16 KiB for fee settlements, 64 KiB for trade plans and on-chain intents, the server-wide 2 MiB for actions. Above 64 KiB the answer may instead be `{\"error\": \"request body too large\"}`.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/WalletPlainTextError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" } } } }, "WalletTenantUnauthorized": { "description": "`send X-Kairos-Partner-Id or your API key (X-Client-Id, X-Api-Key, X-Api-Secret)` — no partner id and no API key (a delegation header never qualifies); `invalid API key`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletApiError" }, "example": { "error": "send X-Kairos-Partner-Id or your API key (X-Client-Id, X-Api-Key, X-Api-Secret)" } } } } }, "parameters": { "WalletOnchainIntentId": { "name": "id", "in": "path", "required": true, "description": "On-chain intent id (`intent.terms.id`).", "schema": { "type": "string", "format": "uuid" } }, "WalletTradePlanId": { "name": "id", "in": "path", "required": true, "description": "Trade plan id.", "schema": { "type": "string", "format": "uuid" } }, "WalletIdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1–128 printable ASCII characters, no spaces. Scoped to the wallet's account and the partner, and never expires. The same key with the same body returns the original object in its current state; the same key with a different body is refused with `409`. Not honoured on `/v3/actions` — use `clientOrderId` there.", "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7E]+$" }, "example": "7f0c2d0e8a7b4c35a1b0f3f1c9e2d4a6" }, "WalletSettlementId": { "name": "id", "in": "path", "required": true, "description": "Settlement id.", "schema": { "type": "string", "format": "uuid" } }, "WalletAddressQuery": { "name": "wallet", "in": "query", "required": true, "description": "The wallet's EVM address. No other query parameter is accepted.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "example": "0x8ba1f109551bd432803012645ac136ddd64dba72" }, "WalletVenueQuery": { "name": "venue", "in": "query", "required": false, "description": "Read one venue only. Case-insensitive; `predict.fun` is accepted for `predictfun`. An unknown name is `400 unknown venue \"\"`; a venue not offered on this deployment returns an empty list.", "schema": { "$ref": "#/components/schemas/WalletVenue" } }, "WalletAddressPath": { "name": "address", "in": "path", "required": true, "description": "The wallet's EVM address (`0x` + 40 hex; checksum not required).", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "example": "0x8ba1f109551bd432803012645ac136ddd64dba72" }, "WalletActionId": { "name": "id", "in": "path", "required": true, "description": "Action id returned by `POST /v3/actions`.", "schema": { "type": "string", "format": "uuid" } }, "WalletApiVersion": { "name": "X-Kairos-Wallet-Api", "in": "header", "required": true, "description": "Wallet API contract version. Send `2` — the multi-venue contract this reference documents. Without the header (or with any other value) `/v3/actions` and `/v3/wallets/*` serve the original Polymarket-only contract, which ignores venue prefixes, `expiresAt` and `setup.venues`, omits `chainId`, `venue` and `fallbackRequests` from steps, refuses orders on a wallet that is not set up (`409`), and returns snake_case order and position rows.", "schema": { "type": "string", "enum": [ "2" ] }, "example": "2" } } } }