---
title: "Commit an on-chain intent with its signatures"
method: POST
path: "/v3/onchain-intents/{id}/execute"
tags: ["On-chain intents (preview)"]
---

# Commit an on-chain intent with its signatures

`POST /v3/onchain-intents/{id}/execute`

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/v3/onchain-intents/{id}/execute`
- Auth: one of:
  - API key in header `X-Kairos-Partner-Id` and API key in header `Authorization`
  - API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret` and API key in header `Authorization`
  - API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`
  - API key in header `X-Kairos-Partner-Id` and API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`
  - API key in header `X-Kairos-Partner-Id` and HTTP bearer

Preview: available on staging (`https://staging-execution.kairos.trade`); production returns `503` until release.

Commits 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).

Calling it again after a successful commit, with valid signatures, returns the current intent.

**Client submission.** POST `submission.body` with `"signature": <native 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.

## Path parameters

- `id` string, uuid, required

## Request body

- WalletOnchainIntentExecuteRequest
  - `intentHash` string, required: Must equal `intent.intentHash`.
  - `consentSignature` string, required: Signature of `consentRequest` — `0x` + 65 bytes (`r‖s‖v`, low-s, `v` 0/1/27/28).
  - `nativeSignature` string: Signature of `nativeRequest`, same format. Required when `submissionOwner` is `kairos`; must be omitted when `client`.

## Response `200`

The committed intent (`committed: true`; `ready` or `awaiting_client`).

- WalletOnchainIntentView: 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.
  - `intent` WalletOnchainIntent, required
    - `terms` WalletOnchainIntentTerms, required: The immutable terms; `intentHash` is their hash. `audience`, `executionRegion` and `submissionEndpoint` are opaque values pinned into the signed terms — do not change them.
      - `contractVersion` 1, required
      - `id` string, uuid, required
      - `partnerId` string, required
      - `audience` string, required: Opaque signed field.
      - `executionRegion` string, required: Opaque signed field.
      - `signer` string, required
      - `account` string, required
      - `chainId` '137', required
      - `market` string, required
      - `operation` 'split' | 'merge' | 'redeem', required
      - `submissionOwner` 'kairos' | 'client', required
      - `submissionEndpoint` string, required: Opaque pinned submission URL. Equals `submission.endpoint`.
      - `batch` WalletOnchainBatch, required: The deposit-wallet batch the owner signs. Calls are `[approval, operation]`.
        - `factory` string, required
        - `nonce` string, required: Decimal.
        - `deadline` string, date-time, required: Equals `executeBefore`.
        - `calls` WalletOnchainCall[], required
          - `target` string, required
          - `value` string, required
          - `data` string, required
      - `effects` WalletOnchainEffect[], required: Exactly what the batch moves on the deposit wallet — the receipt must match.
        - `token` union, required: A token, tagged by `kind`.
          - WalletOnchainTokenErc20
            - `kind` 'erc20', required
            - `contract` string, required
          - WalletOnchainTokenErc1155
            - `kind` 'erc1155', required
            - `contract` string, required
            - `tokenId` string, required: Decimal token id.
        - `direction` 'debit' | 'credit', required
        - `amountRaw` string, required
      - `dependencies` WalletOnchainDependency[], required
        - `intentId` string, uuid, required
        - `intentHash` string, required
        - `account` string, required
        - `chainId` string, required
        - `effects` WalletOnchainEffect[], required
          - `token` union, required: A token, tagged by `kind`.
            - WalletOnchainTokenErc20
              - …
            - WalletOnchainTokenErc1155
              - …
          - `direction` 'debit' | 'credit', required
          - `amountRaw` string, required
      - `maxWalletGasCostRaw` '0', required: The wallet pays no gas.
      - `createdAt` string, date-time, required
      - `executeBefore` string, date-time, required
    - `intentHash` string, required
    - `status` 'needs_signatures' | 'awaiting_client' | 'ready' | 'reconciling' | 'confirmed', required: `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` boolean, required
    - `dispatchClaimed` boolean, required: Kairos has submitted (or is submitting) the batch.
    - `transactionHash` string, nullable, required: The candidate transaction, once known (a report or Kairos's own submission); verified only when `proof` is set.
    - `proof` WalletOnchainProof, required: The verified, finalized transaction.
      - `transactionHash` string, required
      - `blockHash` string, required
      - `blockNumber` string, required: Decimal.
      - `intentHash` string, required
      - `effects` WalletOnchainEffect[], required
        - `token` union, required: A token, tagged by `kind`.
          - WalletOnchainTokenErc20
            - `kind` 'erc20', required
            - `contract` string, required
          - WalletOnchainTokenErc1155
            - `kind` 'erc1155', required
            - `contract` string, required
            - `tokenId` string, required: Decimal token id.
        - `direction` 'debit' | 'credit', required
        - `amountRaw` string, required
  - `consentRequest` WalletEip1193Request, required: 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.
    - `method` 'eth_signTypedData_v4' | 'personal_sign' | 'wallet_sendCalls' | 'eth_sendTransaction', required
    - `params` unknown[], required
      - unknown
  - `nativeRequest` WalletEip1193Request, required: 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.
    - `method` 'eth_signTypedData_v4' | 'personal_sign' | 'wallet_sendCalls' | 'eth_sendTransaction', required
    - `params` unknown[], required
      - unknown
  - `submission` WalletOnchainSubmission, required: For `submissionOwner: client`: add `"signature": <native signature>` to `body` and POST it to `endpoint`.
    - `endpoint` string, required
    - `method` 'POST', required
    - `kind` 'deposit_wallet_batch', required
    - `body` object, required: `{type: "WALLET", from, to, nonce, depositWalletParams: {depositWallet, deadline, calls}}` — no signature.

## Other responses

- `400`: `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}`.
- `401`: `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.
- `403`: `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`.
- `404`: `on-chain intent not found` — unknown, or not visible to this partner and wallet.
- `409`: `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`.
- `410`: `plan authorization has expired` — `executeBefore` has passed. Prepare a new one.
- `413`: 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"}`.
- `415`: Plain text — the request has no `Content-Type: application/json` header.
- `422`: Plain text — the body is valid JSON of the wrong shape (a missing or unknown field, or a wrong type).
- `429`: `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.
- `500`: `internal error`.
- `503`: 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`.

---

[API](https://skmtc.dev/kairos/apis/kairos-partner-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-partner-api/revisions/f4baf0e325ef?raw)