---
title: "List a wallet's orders across venues"
method: GET
path: "/v3/wallets/{address}/orders"
tags: ["Reads"]
---

# List a wallet's orders across venues

`GET /v3/wallets/{address}/orders`

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/v3/wallets/{address}/orders`
- Auth: one of:
  - API key in header `X-Kairos-Partner-Id` and API key in header `Authorization`
  - 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`
  - API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`
  - 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`
  - API key in header `X-Kairos-Partner-Id` and HTTP bearer

Returns the wallet's orders on every venue, newest first. Requires proof of the wallet: send `Authorization: SIWE <token>` from a `login` action (or an API key whose Kairos account owns the wallet).

Each venue is read with the same `limit`; the rows are merged, sorted by `createdAt` descending and cut to `limit`. There is no cursor: this route returns at most 500 orders. When a venue cannot be read its rows are missing and `venueDetail.<venue>.error` says why.

Order rows carry no fee fields.

## Path parameters

- `address` string, required

## Query parameters

- `open` boolean
- `limit` integer
- `venue` 'polymarket' | 'predictfun' | 'hyperliquid': Venue id. `predict.fun` is accepted as an input alias of `predictfun`.

## Headers

- `X-Kairos-Wallet-Api` '2', required

## Response `200`

Orders, newest first.

- WalletOrdersResponse
  - `orders` WalletOrder[], required
    - `orderId` string, uuid, required: Kairos order id — use it to cancel.
    - `venue` 'polymarket' | 'predictfun' | 'hyperliquid', required: Venue id. `predict.fun` is accepted as an input alias of `predictfun`.
    - `market` string, required: `venue:market_id`.
    - `marketId` string, required
    - `outcome` string, nullable, required
    - `tokenId` string, nullable, required
    - `side` 'buy' | 'sell', required: Order/intent side. Lower-case on the wire.
    - `type` 'market' | 'limit', required: Order type. `market` orders still require a `price` (the limit you'll cross to); `limit` orders rest at `price` until filled or cancelled.
    - `price` string, nullable, required
    - `size` string, nullable, required
    - `filledSize` string, nullable, required
    - `avgFillPrice` string, nullable, required
    - `timeInForce` 'GTC' | 'GTD' | 'FOK' | 'FAK' | 'IOC', required: Time-in-force, always UPPER-CASE on the wire. `GTC`/`GTD` are resting (limit-style); `FOK`/`FAK`/`IOC` are immediate taker executions.
    - `postOnly` boolean, nullable, required
    - `expiresAt` string, date-time, nullable, required
    - `status` 'pending' | 'queued' | 'locked' | 'executing' | 'live' | 'partial' | 'filled' | 'cancelled' | 'expired' | 'failed' | 'orphaned', required: Lifecycle status. `partial` is the wire spelling of a partially-filled order (NOT `partially_filled`). The internal states `queued`, `locked` and `orphaned` are **persisted as `pending`**, so an order read back from `GET /orders` or `GET /orders/{order_id}` reports `pending` for all three — they are listed here because they are part of the type and can appear on in-process/streamed values. `executing` is the exception: once a worker claims the order for submission it is persisted as `executing`, and read-back endpoints report `executing` until the venue acknowledges (then `live`) or the attempt fails. The one place a caller sees `queued` directly is the `status` field of a fresh `POST /orders` response, which is the literal string `"queued"`.
    - `venueOrderId` string, nullable, required
    - `clientOrderId` string, nullable, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `venueDetail` WalletVenueReadError: Per-venue read failures, keyed by venue. Present only when some venue could not be read.

## Other responses

- `400`: `unknown venue "x"`; `wallet must be a 0x address`. Plain text for a malformed query (e.g. `open=1`).
- `401`: Tenant failures (`send X-Kairos-Partner-Id or your API key (X-Client-Id, X-Api-Key, X-Api-Secret)`, `invalid API key`), or the wallet proof failed: - `malformed sign-in token` — not `SIWE <token>` as issued, over 4096 bytes, or an invalid lifetime - `sign-in token was issued for another partner or node` — issued for another partner or environment - `sign-in token has expired; run a login action` - `sign-in token signature is not from its wallet` - `Missing authorization` — no `Authorization` header and no API key to prove the wallet; `Invalid API credentials`, `API credential has been revoked` or `Invalid token` when the proving credential is not `SIWE` and fails
- `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`: `wallet not found` — the sign-in token was signed by a different wallet, the API key's account does not own the wallet, or the wallet has never been set up.
- `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)