> ## 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. # Prepare a split, merge or redeem on a Polymarket deposit wallet > Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release. Runs 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. **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. **Addresses** `wallet` and `account` must be **lowercase**; a checksummed address is refused. **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`. **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. **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`. **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`. ## OpenAPI ````yaml /openapi/wallet-api.json post /v3/onchain-intents 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/onchain-intents: post: tags: - On-chain intents (preview) 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. Runs 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. **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. **Addresses** `wallet` and `account` must be **lowercase**; a checksummed address is refused. **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`. **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. **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`. **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`. operationId: prepareOnchainIntent 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' security: - walletPartnerId: [] walletSignIn: [] - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] walletSignIn: [] - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] - walletPartnerId: [] apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] - walletPartnerId: [] bearerAuth: [] components: parameters: 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 schemas: 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 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): - `consentRequest` — `KairosOnchainIntent` typed data binding `signer`, `partnerId`, `audience`, `intentId`, `intentHash`, `executeBefore`. Always required. - `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`. Signatures 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' 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 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 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' 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' 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 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 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' 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' 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 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' WalletOnchainCall: type: object required: - target - value - data properties: target: type: string value: type: string example: '0' data: 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' 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 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' WalletUnsupportedMediaType: description: 'Plain text — the request has no `Content-Type: application/json` header.' content: text/plain: schema: $ref: '#/components/schemas/WalletPlainTextError' 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' 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 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.