> ## Documentation Index > Fetch the complete documentation index at: https://docs.kairos.trade/llms.txt > Use this file to discover all available pages before exploring further. # Read a trade plan > Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release. Returns 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`. A 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. ## OpenAPI ````yaml /openapi/wallet-api.json get /v3/trade-plans/{id} 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 security: [] 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/trade-plans/{id}: get: tags: - Trade plans (preview) summary: Read a trade plan description: >- Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release. Returns 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`. A 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. operationId: getTradePlan 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' security: - walletPartnerId: [] walletSignIn: [] - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] walletSignIn: [] - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] - walletPartnerId: [] apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] - walletPartnerId: [] bearerAuth: [] components: parameters: WalletTradePlanId: name: id in: path required: true description: Trade plan id. schema: type: string format: uuid schemas: 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`. `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 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 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 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 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 WalletVenue: type: string description: Venue id. `predict.fun` is accepted as an input alias of `predictfun`. enum: - polymarket - predictfun - hyperliquid 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. Hyperliquid: whole-share `size`, at most 5 price decimals, `GTC`/`FAK`/`IOC` only. In 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`. 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' 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 WalletTradePlanRequest: type: object description: >- One signature the plan needs, in order: - `plan` — `KairosTradePlan` typed data binding `wallet`, `partnerId`, `audience`, `planId`, `planHash`, `executeBefore`, `tradeSubmitBefore`; on the venue's chain. - `funding-1`, `funding-2` — funded plans only, on the **source** chain: the bridge authorization, then the USDC `ReceiveWithAuthorization` permit. - `trade` — the venue order (Polymarket and Predict.fun native orders; a Kairos `PlaceOrder` authorization on Hyperliquid); on the venue's chain. Sign 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.' 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. WalletPlanErrorView: type: object description: >- Why a plan is in flight or stopped (returned with HTTP `200`). | `code` | Meaning | |---|---| | `OUTCOME_UNKNOWN` | Funding or the trade is in flight; keep polling (`nextAction: reconcile`). | | `PLAN_EXPIRED` | Not executed before `executeBefore`. | | `TRADE_EXPIRED` | The order was not submitted by `tradeSubmitBefore`, or funding arrived after it. | | `FUNDING_SHORTFALL` | Less than `minimumArrivalRaw` arrived. | | `COLLATERAL_CHANGED` | The balance fell below `maxDebitRaw` before submission. | | `VENUE_REJECTED` | The venue refused the signed order. | | `PREFLIGHT_REFUSED` | A pre-submission check refused the order. | | `NATIVE_NOT_DISPATCHED` | The trade authorization expired before submission. | `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 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' 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' 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. At 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' WalletEip1193Request: type: object description: >- An EIP-1193 request to run through the wallet's provider exactly as given (`provider.request({method, params})`). - `eth_signTypedData_v4`: `params` = `[address, typedData]` — `typedData` is a **JSON string**; pass it unchanged. - `personal_sign`: `params` = `[hexMessage, address]`. - `wallet_sendCalls` (EIP-5792): `params` = `[{version, chainId, from, atomicRequired, calls}]`; the wallet pays gas. - `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' 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. 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 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' 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 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' 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' 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 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 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 WalletOnchainTokenErc20: type: object required: - kind - contract properties: kind: type: string const: erc20 contract: type: string WalletOnchainTokenErc1155: type: object required: - kind - contract - tokenId properties: kind: type: string const: erc1155 contract: type: string tokenId: type: string description: Decimal token id. responses: 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: - `malformed sign-in token` — not `SIWE ` as issued, over 4096 bytes, or an invalid lifetime - `sign-in token was issued for another partner or node` — issued for another partner or environment - `sign-in token has expired; run a login action` - `sign-in token signature is not from its wallet` - `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 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 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 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 WalletInternalError: description: '`internal error`.' content: application/json: schema: $ref: '#/components/schemas/WalletApiError' example: error: internal error 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' securitySchemes: 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. 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. 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. apiKeyKey: type: apiKey in: header name: X-Api-Key description: 64-char hex API key. apiKeySecret: type: apiKey in: header name: X-Api-Secret description: 64-char hex API secret. bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- First-party Kairos session JWT (web app sessions). Not issued to API consumers. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.