---
title: "Read an action's current step"
method: GET
path: "/v3/actions/{id}"
tags: ["Actions"]
---

# Read an action's current step

`GET /v3/actions/{id}`

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/v3/actions/{id}`
- Auth: one of:
  - API key in header `X-Kairos-Partner-Id`
  - API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`

Returns the action's current step. Poll this while `status` is `working`; when the step carries `holdUntilMs` (an order the venue is still matching), wait until then before polling.

An action is readable for 10 minutes after its 15-minute lifetime ends. Unknown, expired, and other partners' actions all read `404`.

## Response `200`

The current step.

- WalletActionStep: The current step of an action. Every response from `/v3/actions` and `/v3/actions/{id}` is one of these.
  - `id` string, 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`.
  - `request` WalletEip1193Request, 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.
    - `method` 'eth_signTypedData_v4' | 'personal_sign' | 'wallet_sendCalls' | 'eth_sendTransaction', required
    - `params` unknown[], required
      - unknown
  - `description` string, nullable, required: Text to show with the wallet prompt (e.g. `Confirm this Hyperliquid order`), or progress text while `working`.
  - `chainId` string, 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`.
  - `fallbackRequests` WalletEip1193Request[]: Present with `wallet_sendCalls` requests only — the same calls as individual `eth_sendTransaction` requests, for wallets without EIP-5792. Send them in order and answer with `{"result": ["0xhash", …]}`.
    - `method` 'eth_signTypedData_v4' | 'personal_sign' | 'wallet_sendCalls' | 'eth_sendTransaction', required
    - `params` unknown[], required
      - unknown
  - `expiresAtMs` integer: Last accepted millisecond (Unix ms) for answering this prompt. Answers after it fail the action with `SIGNATURE_EXPIRED`.
  - `holdUntilMs` integer: 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`.
  - `result` union, required: Outcome on `done` (and the provisional outcome of a held order). Shape depends on `type`.
    - WalletSetupResult: `result` of a `setup` action.
      - `ready` boolean, required: Every requested venue is ready.
      - `venues` object: Outcome per requested venue.
      - `tradingWallet` string, nullable: Polymarket's trading wallet, when Polymarket was set up; `null` when Polymarket's setup failed.
      - `transactionHash` string, nullable: Polymarket's approval transaction, when Polymarket was set up.
    - WalletOrderResult: `result` of an `order` action. No fee fields: Kairos and venue fees are not reported here.
      - `orderId` string, uuid, required: Kairos order id — use it to cancel.
      - `status` string, required: Order status: Polymarket's answer (`matched`, `live`, `delayed`, `unmatched`) or the Kairos order status on Hyperliquid (`executing`, `live`, `partial`, `filled`, `cancelled`, `failed`, …). Read `final` and `success` rather than matching on this.
      - `venueOrderId` string, nullable
      - `venueStatus` string, nullable: The venue's first answer.
      - `filledSize` string, nullable: Shares filled; `null` when unknown.
      - `filledNotional` string, nullable: Collateral spent or received, before venue fees.
      - `avgPrice` string, nullable
      - `final` boolean, required: Matching is finished.
      - `success` boolean, required: `false` when the order did nothing, failed, or is not confirmed yet.
      - `message` string, nullable: Set when `success` is false: - `No fill: the venue matched none of this order` - `The order failed at the venue; any fills shown were reverted` - `The venue rejected the order` - `Outcome not confirmed yet; check this wallet's orders before placing it again`
      - `venue` 'polymarket' | 'predictfun' | 'hyperliquid': Venue id. `predict.fun` is accepted as an input alias of `predictfun`.
      - `market` string: `venue:market_id`.
    - WalletCancelResult: `result` of a `cancel` action. If nothing was confirmed and a venue may have acted, the action fails with `CANCEL_OUTCOME_UNKNOWN` and keeps this result.
      - `cancelled` string[], required: Order ids cancelled.
      - `alreadyClosed` string[]: By id — orders already filled, cancelled or expired.
      - `failed` union, required: By id — the failures; with `all` — the number of failures.
        - WalletCancelFailure[]
          - `orderId` string, required
          - `reason` string, required: The venue's reason, `cancel failed; retry`, `order not found` (also for ids that are not this wallet's), `venue unavailable; retry`, or an outcome-unknown message.
          - `code` string: `CANCEL_OUTCOME_UNKNOWN` when the venue may have cancelled.
        - integer
      - `venueDetail` object, required: Per venue: `{cancelled, failed}` counts for `all`, or `{error}` when the venue could not be reached (`{error, code: "CANCEL_OUTCOME_UNKNOWN"}` when it may have cancelled). Empty when every venue answered on a by-id cancel.
    - WalletLoginResult: `result` of a `login` action. Send it as `Authorization: SIWE <token>`.
      - `token` string, required: Opaque sign-in token (at most 4096 bytes).
      - `expiresAt` string, date-time, required: 24 hours after issue.
  - `error` string, nullable, required: Why the action failed; non-null on `failed`.
  - `errorCode` 'NO_MATCH' | 'VENUE_REJECTED' | 'ORDER_OUTCOME_UNKNOWN' | 'CANCEL_OUTCOME_UNKNOWN' | 'SIGNATURE_EXPIRED' | 'CLIENT_ORDER_ID_CONFLICT' | 'HYPERLIQUID_AGENT_MISSING': 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 |

## Other responses

- `400`: Plain text — `{id}` is not a UUID.
- `401`: `send X-Kairos-Partner-Id or your API key (X-Client-Id, X-Api-Key, X-Api-Secret)` — no partner id and no API key (a delegation header never qualifies); `invalid API key`.
- `403`: `unknown partner id` (unknown, or the Wallet API is not enabled for it); `this partner id is used with its API key; send the key instead of X-Kairos-Partner-Id`; `this API key lacks the trade:execute scope` (an API key must carry `trade:execute` to act as the tenant — a `trade:read`-only key is refused, even on reads); `the wallet API is not enabled for this account`.
- `404`: `unknown or expired action` — also returned for another partner's action.
- `429`: `rate limit exceeded for this endpoint; retry later`. The default limit is 120 requests per minute per client IP per path (1000 when `X-Client-Id` is sent), over a sliding 60 s window; `GET` and `POST` on one path share it. No `Retry-After` header is sent.
- `500`: `internal error`.
- `502`: A venue did not answer cleanly, e.g. `Hyperliquid is unavailable; retry shortly`, `Predict.fun is unavailable; retry shortly`. Retry.
- `503`: `partner registry unavailable; retry shortly`; `rate limiter unavailable` (the rate limiter fails closed); `wallet sign-in is not configured on this node`; `<venue> is not available right now`. Retry later.
- `504`: `… did not answer in time; GET /v3/actions/{id} before retrying`. The request may have taken effect: read the state before repeating it.

---

[API](https://skmtc.dev/kairos/apis/kairos-partner-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-partner-api/revisions/f4baf0e325ef?raw)