On-chain intents (preview)

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": <native 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.

POST

onchain-intents

curl --request POST \
  --url https://execution.kairos.trade/v3/onchain-intents \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Kairos-Partner-Id: <api-key>' \
  --data '
{
  "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
  "account": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
  "market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a",
  "operation": "split",
  "amountRaw": "1000000",
  "submissionOwner": "kairos",
  "executeBefore": "2026-10-28T12:04:00Z"
}
'

{
  "intent": {
    "terms": {
      "contractVersion": 1,
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "partnerId": "<string>",
      "audience": "<string>",
      "executionRegion": "<string>",
      "signer": "<string>",
      "account": "<string>",
      "chainId": "137",
      "market": "<string>",
      "operation": "split",
      "submissionOwner": "kairos",
      "submissionEndpoint": "<string>",
      "batch": {
        "factory": "<string>",
        "nonce": "<string>",
        "deadline": "2023-11-07T05:31:56Z",
        "calls": [
          {
            "target": "<string>",
            "value": "0",
            "data": "<string>"
          }
        ]
      },
      "effects": [
        {
          "token": {
            "kind": "erc20",
            "contract": "<string>"
          },
          "direction": "debit",
          "amountRaw": "<string>"
        }
      ],
      "dependencies": [
        {
          "intentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "intentHash": "<string>",
          "account": "<string>",
          "chainId": "137",
          "effects": [
            {
              "token": {
                "kind": "erc20",
                "contract": "<string>"
              },
              "direction": "debit",
              "amountRaw": "<string>"
            }
          ]
        }
      ],
      "maxWalletGasCostRaw": "0",
      "createdAt": "2023-11-07T05:31:56Z",
      "executeBefore": "2023-11-07T05:31:56Z"
    },
    "intentHash": "<string>",
    "status": "needs_signatures",
    "committed": true,
    "dispatchClaimed": true,
    "transactionHash": "<string>",
    "proof": {
      "transactionHash": "<string>",
      "blockHash": "<string>",
      "blockNumber": "<string>",
      "intentHash": "<string>",
      "effects": [
        {
          "token": {
            "kind": "erc20",
            "contract": "<string>"
          },
          "direction": "debit",
          "amountRaw": "<string>"
        }
      ]
    }
  },
  "consentRequest": {
    "method": "personal_sign",
    "params": [
      "0x6b6169726f732e7472616465207761…",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ]
  },
  "nativeRequest": {
    "method": "personal_sign",
    "params": [
      "0x6b6169726f732e7472616465207761…",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ]
  },
  "submission": {
    "endpoint": "<string>",
    "method": "POST",
    "kind": "deposit_wallet_batch",
    "body": {}
  }
}

{
  "error": "unknown or expired action"
}

{
  "error": "sign-in token has expired; run a login action"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

{
  "error": "rate limit exceeded for this endpoint; retry later"
}

{
  "error": "internal error"
}

{
  "error": "unknown or expired action"
}

Authorizations

X-Kairos-Partner-Id

string

header

required

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.

Authorization

string

header

required

Wallet sign-in token: SIWE <token>, where <token> 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.

Headers

Idempotency-Key

string

required

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.

Required string length: 1 - 128

Pattern: ^[\x21-\x7E]+$

Body

application/json

Body of POST /v3/onchain-intents. Unknown fields (calls, nonce, chain, recipient, gas) are refused.

wallet

string

required

The owner that signs — lowercase 0x address.

Pattern: ^0x[0-9a-f]{40}$

Example:

"0x8ba1f109551bd432803012645ac136ddd64dba72"

account

string

required

The owner's Polymarket deposit wallet (its trading wallet) — lowercase, and not equal to wallet.

Pattern: ^0x[0-9a-f]{40}$

Example:

"0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b"

market

string

required

polymarket:0x<64-hex condition id> or a bare condition id. Binary markets only.

Example:

"polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a"

operation

enum<string>

required

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.

Available options:

split,

merge,

redeem

amountRaw

string

required

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"

submissionOwner

enum<string>

required

Who submits the signed batch. Use kairos unless you have arranged submission access with Kairos.

Available options:

kairos,

client

executeBefore

string<date-time>

required

In the future, at most 300 s out, whole seconds. Also the batch's on-chain deadline.

Example:

"2026-10-28T12:04:00Z"

outcome

enum<integer>

Outcome index to redeem. Required for redeem, refused otherwise.

Available options:

0,

1

dependencies

string<uuid>[]

Earlier intents on the same deposit wallet that must confirm first. At most 16, distinct.

Maximum array length: 16

Response

The prepared intent (needs_signatures) and the two requests to sign.

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

object

required

Show child attributes

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.

Show child attributes

Example:

{
  "method": "personal_sign",
  "params": [
    "0x6b6169726f732e7472616465207761…",
    "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
  ]
}

nativeRequest

object

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.

Show child attributes

Example:

{
  "method": "personal_sign",
  "params": [
    "0x6b6169726f732e7472616465207761…",
    "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
  ]
}

submission

object

required

For submissionOwner: client: add "signature": <native signature> to body and POST it to endpoint.

Show child attributes

curl --request POST \
  --url https://execution.kairos.trade/v3/onchain-intents \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Kairos-Partner-Id: <api-key>' \
  --data '
{
  "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
  "account": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
  "market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a",
  "operation": "split",
  "amountRaw": "1000000",
  "submissionOwner": "kairos",
  "executeBefore": "2026-10-28T12:04:00Z"
}
'

{
  "intent": {
    "terms": {
      "contractVersion": 1,
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "partnerId": "<string>",
      "audience": "<string>",
      "executionRegion": "<string>",
      "signer": "<string>",
      "account": "<string>",
      "chainId": "137",
      "market": "<string>",
      "operation": "split",
      "submissionOwner": "kairos",
      "submissionEndpoint": "<string>",
      "batch": {
        "factory": "<string>",
        "nonce": "<string>",
        "deadline": "2023-11-07T05:31:56Z",
        "calls": [
          {
            "target": "<string>",
            "value": "0",
            "data": "<string>"
          }
        ]
      },
      "effects": [
        {
          "token": {
            "kind": "erc20",
            "contract": "<string>"
          },
          "direction": "debit",
          "amountRaw": "<string>"
        }
      ],
      "dependencies": [
        {
          "intentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "intentHash": "<string>",
          "account": "<string>",
          "chainId": "137",
          "effects": [
            {
              "token": {
                "kind": "erc20",
                "contract": "<string>"
              },
              "direction": "debit",
              "amountRaw": "<string>"
            }
          ]
        }
      ],
      "maxWalletGasCostRaw": "0",
      "createdAt": "2023-11-07T05:31:56Z",
      "executeBefore": "2023-11-07T05:31:56Z"
    },
    "intentHash": "<string>",
    "status": "needs_signatures",
    "committed": true,
    "dispatchClaimed": true,
    "transactionHash": "<string>",
    "proof": {
      "transactionHash": "<string>",
      "blockHash": "<string>",
      "blockNumber": "<string>",
      "intentHash": "<string>",
      "effects": [
        {
          "token": {
            "kind": "erc20",
            "contract": "<string>"
          },
          "direction": "debit",
          "amountRaw": "<string>"
        }
      ]
    }
  },
  "consentRequest": {
    "method": "personal_sign",
    "params": [
      "0x6b6169726f732e7472616465207761…",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ]
  },
  "nativeRequest": {
    "method": "personal_sign",
    "params": [
      "0x6b6169726f732e7472616465207761…",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ]
  },
  "submission": {
    "endpoint": "<string>",
    "method": "POST",
    "kind": "deposit_wallet_batch",
    "body": {}
  }
}

{
  "error": "unknown or expired action"
}

{
  "error": "sign-in token has expired; run a login action"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

{
  "error": "rate limit exceeded for this endpoint; retry later"
}

{
  "error": "internal error"
}

{
  "error": "unknown or expired action"
}

Get started

Onboard users

Trade

Route and fund

Partner fees

Build

Endpoints

Prepare a split, merge or redeem on a Polymarket deposit wallet

Authorizations

Headers

Body

Response