Actions

Answer the current step (signature or wallet result)

Posts the wallet's answer to the step that is needs_signature and returns the next step.

Signature steps (eth_signTypedData_v4, personal_sign): send {"signature": "0x…"} — exactly 65 bytes, hex. A JSON string in result is accepted as the signature too. Smart-account (EIP-1271) signatures are refused.
wallet_sendCalls steps (Predict.fun approvals): send {"result": <the wallet_sendCalls return value>}, or {"result": ["0xhash", …]} after sending fallbackRequests one by one. The step moves to working while Kairos waits for the approvals on chain.

Failures after a signature are not HTTP errors. A venue refusal, an expired signing window, a rate limit or an ambiguous submission comes back as 200 with status: "failed", error, and — when there is one — errorCode. Read errorCode before retrying: ORDER_OUTCOME_UNKNOWN and CANCEL_OUTCOME_UNKNOWN mean the venue may have acted, so read /v3/wallets/{address}/orders before placing again.

Safe to repeat. Posting to a step that is no longer needs_signature returns the current step unchanged; a step is never run twice. A wrong signer gets 400 and the same step stays open for another try.

This call waits up to about 45 s for the step to settle, then returns working; keep polling GET /v3/actions/{id}.

post/v3/actions/{id}

Request

Base URL
https://execution.kairos.trade
Auth
- API key in header X-Kairos-Partner-Id
- or API key in header X-Client-Id and API key in header X-Api-Key and API key in header X-Api-Secret

Request body

signaturestring

65-byte ECDSA signature, hex (0x optional).

resultunknown

Example request

{
  "signature": "0x4f8b2c1d9e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c3d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e1b"
}

Response

The next step — needs_signature (another prompt), working, done, or failed (with error and usually errorCode).

idstring uuid required

Action id. One id for the whole action, across venues.

type'setup' | 'order' | 'cancel' | 'login' required

status'needs_signature' | 'working' | 'done' | 'failed' required

needs_signature — run request and answer; working — poll; done — read result; failed — read error and errorCode.

descriptionstring nullable required

Text to show with the wallet prompt (e.g. Confirm this Hyperliquid order), or progress text while working.

chainIdstring nullable required

EIP-155 chain id (hex) the wallet must be on to answer — 0x89 Polygon, 0x38 BNB Chain, 0xa4b1 Arbitrum One (0x66eee Arbitrum Sepolia on Hyperliquid testnet). null for personal_sign and when nothing is asked.

venue'polymarket' | 'predictfun' | 'hyperliquid' required

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

expiresAtMsinteger

Last accepted millisecond (Unix ms) for answering this prompt. Answers after it fail the action with SIGNATURE_EXPIRED.

holdUntilMsinteger

On a working order the venue is still matching — poll again after this time (Unix ms). result then holds a provisional outcome with final: false.

errorstring nullable required

Why the action failed; non-null on failed.

Machine-readable reason on a failed step; the key is omitted when the failure has no code. Codes may be added; treat an unknown code as a failure whose order was not placed.

Code	Meaning	Order placed?
NO_MATCH	An immediate order (FOK/FAK/IOC) found nothing to match.	No
VENUE_REJECTED	The venue refused the order.	No
ORDER_OUTCOME_UNKNOWN	The submission's outcome is unknown. Read the wallet's orders before placing again.	Maybe
CANCEL_OUTCOME_UNKNOWN	Some venue may have cancelled. Read the wallet's orders.	Maybe
SIGNATURE_EXPIRED	The signing window closed before a signature was accepted. Nothing was sent.	No
CLIENT_ORDER_ID_CONFLICT	The clientOrderId names an order with different terms.	No
HYPERLIQUID_AGENT_MISSING	Hyperliquid no longer lists this wallet's trading approval. Run setup again.	No

Example response

{
  "request": {
    "method": "personal_sign",
    "params": [
      "0x6b6169726f732e7472616465207761…",
      "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    ]
  },
  "chainId": "0x38",
  "fallbackRequests": [
    {
      "method": "personal_sign",
      "params": [
        "0x6b6169726f732e7472616465207761…",
        "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
      ]
    }
  ],
  "expiresAtMs": 1793130772999,
  "result": {
    "ready": false,
    "venues": {
      "polymarket": {
        "ready": true,
        "tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
        "transactionHash": "0x7c3e9a1b5d2f4c6e8a0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c"
      },
      "predictfun": {
        "ready": false,
        "next": "fund",
        "tradingWallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
        "venueDetail": {
          "reason": "needs about 0.0004 BNB on BNB Chain to pay gas for 2 Predict.fun approvals",
          "approvals": 2,
          "gasWei": "400000000000000"
        }
      }
    },
    "tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
    "transactionHash": "0x7c3e9a1b5d2f4c6e8a0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.