Prepare a trade plan (one buy, optionally funded cross-chain)
Preview: available on staging (https://staging-execution.kairos.trade); production returns 503 until release.
A trade plan is one buy order on one venue, authorized up front in one batch of signatures, with an explicit fee ceiling (tradeBudget) and hard deadlines. When the venue account is short of collateral, the plan can also bridge exactly the shortfall from the same wallet's USDC on Polygon (137) or Arbitrum (42161) through gasless permits. Kairos runs funding first and submits the order only after the destination credit is final.
Use /v3/actions for sells, cancels, setup and login; trade plans are buy-only and the venue wallet must already be set up through a setup action.
Flow. Prepare → check order (the server may normalize it: canonical outcome; on Predict.fun a GTC order becomes a GTD order bounded by the venue session) → sign every requests[] entry whose actionable is true → POST /v3/trade-plans/{id}/answers and/or POST /v3/trade-plans/{id}/execute before executeBefore → poll GET /v3/trade-plans/{id}.
An unfunded plan needs 2 signatures (plan, trade); a funded plan adds funding-1 and funding-2, signed on the source chain. Every signature must be a plain 65-byte ECDSA signature (low-s) from wallet.
Idempotency. Idempotency-Key is required. The same key with the same body returns the stored plan in its current state; with a different body it is 409. clientOrderId is unique per wallet and venue across plans.
Fees. tradeBudget.maxPlatformFeeBps is the Kairos maximum plus the partner maximum (partnerFee.maxBps), never above 1000 bps (10%). Partner fees are configured by Kairos per partner and pinned into the plan the wallet signs. Fees are not deducted in the order: they accrue as debt and are paid through /v3/fees/settlements. When the wallet's debt is at or above the partner's threshold, prepare returns 409 FEE_SETTLEMENT_REQUIRED.
Request
- Base URLhttps://execution.kairos.trade
- Auth
- API key in header X-Kairos-Partner-Id and API key in header Authorization
- or 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
- or API key in header X-Client-Id and API key in header X-Api-Key and API key in header X-Api-Secret
- or 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
- or API key in header X-Kairos-Partner-Id and HTTP bearer
Headers
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.
Request body
Example request
{
"wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
"order": {
"market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a",
"outcome": "Yes",
"price": "0.05",
"size": "10",
"clientOrderId": "partner-trade-1042"
},
"funding": {
"sourceToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
"maxAmountRaw": "750000",
"maxGasCostRaw": "0",
"slippageBps": 50
},
"tradeSubmitBefore": "2026-10-28T12:04:00Z"
}Response
The prepared plan in needs_signatures. A replay with the same Idempotency-Key and body returns the stored plan in its current state.
Example response
{
"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
}Changes
No recorded changes to this operation across all 1 revision of this API.