Starts one action for a self-custody wallet and returns its first step. Kairos never holds the wallet's key: each step either asks the wallet for one EIP-1193 request (status: needs_signature) or reports progress (working) or the outcome (done / failed).

The step loop.

1. POST /v3/actions → a step.
2. While status is needs_signature: switch the wallet to chainId (when non-null), run request through the wallet's EIP-1193 provider, and POST /v3/actions/{id} with {"signature": "0x…"} (or {"result": …} for wallet_sendCalls). Answer before expiresAtMs.
3. While status is working: GET /v3/actions/{id} every 1–2 s (or after holdUntilMs when present).
4. Stop at done (read result) or failed (read error and errorCode).

Action types. setup prepares the wallet on each requested venue; order places one order and runs any missing setup first, in the same action; cancel cancels orders on every venue with one Polygon signature; login returns a sign-in token for the private reads. There are no other action types.

Body rules. Field names are camelCase only: unknown fields — including snake_case spellings such as time_in_force, post_only, client_order_id, expires_at, order_ids — are silently ignored, so a snake_case order becomes a GTC, non-post-only order without a client id. price and size must be JSON strings; a JSON number is rejected with a plain-text 422. expiresAt is an integer (Unix seconds).

Idempotency. Idempotency-Key is not honoured here. Use clientOrderId on orders: the same clientOrderId with the same terms returns the existing order (nothing is signed), and different terms are refused with CLIENT_ORDER_ID_CONFLICT.

Timing. An action lives 15 minutes from creation and stays readable for 10 more minutes, then reads 404. Polymarket and Predict.fun order signatures are accepted for about 60 s, Hyperliquid order signatures for 300 s, and cancel signatures (every venue) for 300 s; expiresAtMs on the step is authoritative.

Errors before the first signature are HTTP errors. When the action fails before the wallet was ever asked to sign (for example every requested venue is unavailable), the response is that error's status and body rather than a failed step.

Send X-Kairos-Wallet-Api: 2; without it this route serves the original Polymarket-only contract.

{
  "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
  "action": {
    "market": "predictfun:1027194",
    "outcome": "Yes",
    "price": "0.52",
    "size": "10",
    "clientOrderId": "acme-7f3a91",
    "expiresAt": 1793300000
  }
}

{
  "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"
  }
}