---
title: "Read an on-chain intent"
method: GET
path: "/v3/onchain-intents/{id}"
tags: ["On-chain intents (preview)"]
---

# Read an on-chain intent

`GET /v3/onchain-intents/{id}`

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/v3/onchain-intents/{id}`
- 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.

Returns 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.

## Path parameters

- `id` string, uuid, required

## Response `200`

The intent.

- 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`: Plain text — `{id}` is not a UUID.
- `401`: 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 <token>` 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
- `403`: `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`.
- `404`: `on-chain intent not found` — unknown, or not visible to this partner and wallet.
- `409`: `this wallet is not set up yet; run a setup action first` — the signer's account is no longer active.
- `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: `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`.

---

[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)