KAkairos
Trade plans (preview)

Post signatures for a trade plan's requests

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

Posts one or more signatures for the plan's requests[]. Answers may arrive in several batches; the whole batch is checked before anything is stored. When every required signature is in, status becomes ready_to_execute. You can also skip this call and send all signatures in the /execute body.

Each signature must be 65 bytes, low-s, and recover to wallet over that request's typed data. Re-sending an accepted signature is a no-op; a different signature for an accepted request is refused. With submission.funding: "client", keep the funding signatures — Kairos refuses them. Only kind: "signature" answers are accepted.

post/v3/trade-plans/{id}/answers

Request

  • Base URL
    https://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

Path parameters

idstring uuid required

Trade plan id.

Request body

planHashstring required

Must equal the plan's planHash.

Example request

{
  "planHash": "0xb3d5c6e930ee2015f733bd9ffa2a2302fedd2a5bf38628e220f0b675d50f6953",
  "answers": [
    {
      "kind": "signature",
      "requestId": "plan",
      "signature": "0xb2befc57fa7365cd671c908b8ba106005520bbd0fdb7212c8ea2134a6f2ff38a1b41a830b69eb1f51b7f1520681382729fdd1630ee70b131aac7b9059195de081c"
    },
    {
      "kind": "signature",
      "requestId": "trade",
      "signature": "0xe09dacdd8731b4d1d972464ff7c88b1b9bb892273460f5be18304747af897c5c0764badc6c1a57bf5c0f92bfa1ef908b34ab4eb4772381d72f5df6bb8007e3541c"
    }
  ]
}

Response

The plan; accepted requests show status: accepted and actionable: false.

contractVersion1 required
idstring uuid required
planHashstring required

Hash of the plan's terms; every answer must echo it.

revisionstring required

Increases on every stored change ("0" at prepare).

walletstring required

The signing wallet, lowercase.

partnerIdstring required
audiencestring required

Opaque signed field.

interactionMode'single_batch' | 'allow_followup' required
status'needs_signatures' | 'ready_to_execute' | 'funding_pending' | 'trade_pending' | 'reconciling' | 'completed' | 'expired' | 'failed' | 'funded_trade_failed' | 'funded_trade_expired' required
venue'polymarket' | 'predictfun' | 'hyperliquid' required

Venue id. predict.fun is accepted as an input alias of predictfun.

tradeExecutionRegionstring required

Opaque signed field.

tradingWalletstring required

Where the collateral must sit — Polymarket's trading wallet, or the wallet itself on Predict.fun and Hyperliquid.

tradePayloadDigeststring required

Signing digest of the trade request.

createdAtstring date-time required
executeBeforestring date-time required

Deadline for answers and /execute — funding.fundingSubmitBefore when funded, else tradeSubmitBefore.

tradeSubmitBeforestring date-time required

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.