> ## Documentation Index > Fetch the complete documentation index at: https://docs.kairos.trade/llms.txt > Use this file to discover all available pages before exploring further. # List a wallet's orders across venues > Returns the wallet's orders on every venue, newest first. Requires proof of the wallet: send `Authorization: SIWE ` 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..error` says why. Order rows carry no fee fields. ## OpenAPI ````yaml /openapi/wallet-api.json get /v3/wallets/{address}/orders openapi: 3.1.0 info: title: Kairos Partner API version: 1.0.0 description: >- Self-custody trading for wallets and apps: Kairos builds each step, the user's wallet signs it. Every operation is under `/v3`. Guides: https://docs.kairos.trade/wallets/overview servers: - url: https://execution.kairos.trade description: Production - url: https://staging-execution.kairos.trade description: Staging security: [] tags: - name: Actions description: >- Start `setup`, `order`, `cancel` and `login` actions and answer their steps. Live. Send `X-Kairos-Wallet-Api: 2`. - name: Reads description: >- Wallet readiness and balances per venue (partner id or API key, no wallet proof), and the wallet's orders and positions (also needs `Authorization: SIWE ` from a `login` action). Live. - name: Trade plans (preview) description: >- One buy order authorized up front in one signature batch, with a fee ceiling and deadlines, optionally funded by bridging the exact shortfall from Polygon or Arbitrum USDC. Preview: staging only; production returns `503` until release. - name: Fees (preview) description: >- Trading fees from trade plans accrue as a debt per wallet and are paid in one settlement — a gasless signature on Polymarket, a USDT transfer on Predict.fun. Preview: staging only. - name: On-chain intents (preview) description: >- Split, merge or redeem conditional tokens on a Polymarket deposit wallet with two signatures and no gas; Kairos confirms from the finalized receipt. Preview: staging only; production returns `503` until release. paths: /v3/wallets/{address}/orders: get: tags: - Reads summary: List a wallet's orders across venues description: >- Returns the wallet's orders on every venue, newest first. Requires proof of the wallet: send `Authorization: SIWE ` 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..error` says why. Order rows carry no fee fields. operationId: listWalletOrders parameters: - $ref: '#/components/parameters/WalletAddressPath' - $ref: '#/components/parameters/WalletApiVersion' - name: open in: query required: false description: >- `true` returns only working orders; `false` (default) returns every status. Only the literal `true` / `false` are accepted. schema: type: boolean default: false - name: limit in: query required: false description: Maximum rows to return. Values outside 1–500 are clamped. schema: type: integer minimum: 1 maximum: 500 default: 50 - $ref: '#/components/parameters/WalletVenueQuery' responses: '200': description: Orders, newest first. content: application/json: schema: $ref: '#/components/schemas/WalletOrdersResponse' '400': description: >- `unknown venue "x"`; `wallet must be a 0x address`. Plain text for a malformed query (e.g. `open=1`). content: application/json: schema: $ref: '#/components/schemas/WalletApiError' text/plain: schema: $ref: '#/components/schemas/WalletPlainTextError' '401': $ref: '#/components/responses/WalletSignInUnauthorized' '403': $ref: '#/components/responses/WalletTenantForbidden' '404': $ref: '#/components/responses/WalletNotFound' '429': $ref: '#/components/responses/WalletRateLimited' '500': $ref: '#/components/responses/WalletInternalError' '502': $ref: '#/components/responses/WalletVenueUnavailable' '503': $ref: '#/components/responses/WalletServiceUnavailable' '504': $ref: '#/components/responses/WalletGatewayTimeout' security: - walletPartnerId: [] walletSignIn: [] - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] walletSignIn: [] - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] - walletPartnerId: [] apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] - walletPartnerId: [] bearerAuth: [] components: parameters: WalletAddressPath: name: address in: path required: true description: The wallet's EVM address (`0x` + 40 hex; checksum not required). schema: type: string pattern: ^0x[0-9a-fA-F]{40}$ example: '0x8ba1f109551bd432803012645ac136ddd64dba72' WalletApiVersion: name: X-Kairos-Wallet-Api in: header required: true description: >- Wallet API contract version. Send `2` — the multi-venue contract this reference documents. Without the header (or with any other value) `/v3/actions` and `/v3/wallets/*` serve the original Polymarket-only contract, which ignores venue prefixes, `expiresAt` and `setup.venues`, omits `chainId`, `venue` and `fallbackRequests` from steps, refuses orders on a wallet that is not set up (`409`), and returns snake_case order and position rows. schema: type: string enum: - '2' example: '2' WalletVenueQuery: name: venue in: query required: false description: >- Read one venue only. Case-insensitive; `predict.fun` is accepted for `predictfun`. An unknown name is `400 unknown venue ""`; a venue not offered on this deployment returns an empty list. schema: $ref: '#/components/schemas/WalletVenue' schemas: WalletOrdersResponse: type: object required: - orders properties: orders: type: array items: $ref: '#/components/schemas/WalletOrder' venueDetail: $ref: '#/components/schemas/WalletVenueReadError' example: orders: - orderId: 3f2b8c1e-5d4a-4e6f-9b7c-1a2d3e4f5a6b venue: predictfun market: predictfun:1027194 marketId: '1027194' outcome: 'Yes' tokenId: '81517620335745318418347838710345678901234567890' side: buy type: limit price: '0.52' size: '10' filledSize: '0' avgFillPrice: null timeInForce: GTD postOnly: false expiresAt: '2026-10-29T00:00:00Z' status: live venueOrderId: 512334:0x3c9a… clientOrderId: acme-7f3a91 createdAt: '2026-10-28T12:00:00Z' updatedAt: '2026-10-28T12:00:01Z' WalletApiError: type: object description: >- Wallet API error body. `error` is a human-readable message; `code` is set on a few structured refusals (e.g. `CLIENT_ORDER_ID_CONFLICT`, `POLYMARKET_V2_TRADING_DISABLED`, `SIGNATURE_EXPIRED`); `errorCode` mirrors `code` where the same refusal can also surface on a failed step. Most `/v3` errors carry only `error`. Framework rejections (malformed JSON, wrong shape, missing content type) are plain text, not this body. required: - error properties: error: type: string description: Human-readable message. code: type: string description: Stable code, present on structured refusals only. errorCode: type: string description: >- Same as `code`; present where the refusal can also appear as a failed step's `errorCode`. example: error: unknown or expired action WalletPlainTextError: type: string description: >- A plain-text (non-JSON) rejection from request parsing — malformed JSON, a body of the wrong shape, a missing `Content-Type`, a malformed path id or query. Do not JSON-parse it. example: >- Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string WalletVenue: type: string description: Venue id. `predict.fun` is accepted as an input alias of `predictfun`. enum: - polymarket - predictfun - hyperliquid WalletOrder: type: object description: >- One order, in the shape every venue shares. Prices are 0–1 and sizes are shares, as decimal strings. No fee fields. required: - orderId - venue - market - marketId - outcome - tokenId - side - type - price - size - filledSize - avgFillPrice - timeInForce - postOnly - expiresAt - status - venueOrderId - clientOrderId - createdAt - updatedAt properties: orderId: type: string format: uuid description: Kairos order id — use it to cancel. venue: $ref: '#/components/schemas/WalletVenue' market: type: string description: '`venue:market_id`.' marketId: type: string outcome: type: - string - 'null' tokenId: type: - string - 'null' side: $ref: '#/components/schemas/OrderSide' type: $ref: '#/components/schemas/OrderKind' price: type: - string - 'null' size: type: - string - 'null' filledSize: type: - string - 'null' avgFillPrice: type: - string - 'null' timeInForce: $ref: '#/components/schemas/OrderTimeInForce' postOnly: type: - boolean - 'null' expiresAt: type: - string - 'null' format: date-time status: $ref: '#/components/schemas/OrderStatus' venueOrderId: type: - string - 'null' clientOrderId: type: - string - 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time WalletVenueReadError: type: object description: >- Per-venue read failures, keyed by venue. Present only when some venue could not be read. additionalProperties: type: object properties: error: type: string OrderSide: type: string description: Order/intent side. Lower-case on the wire. enum: - buy - sell example: buy OrderKind: type: string description: >- Order type. `market` orders still require a `price` (the limit you'll cross to); `limit` orders rest at `price` until filled or cancelled. enum: - market - limit example: limit OrderTimeInForce: type: string description: >- Time-in-force, always UPPER-CASE on the wire. `GTC`/`GTD` are resting (limit-style); `FOK`/`FAK`/`IOC` are immediate taker executions. enum: - GTC - GTD - FOK - FAK - IOC example: GTC OrderStatus: type: string description: >- 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"`. enum: - pending - queued - locked - executing - live - partial - filled - cancelled - expired - failed - orphaned example: live responses: WalletSignInUnauthorized: description: >- 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 ` 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 content: application/json: schema: $ref: '#/components/schemas/WalletApiError' example: error: sign-in token has expired; run a login action WalletTenantForbidden: description: >- `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`. content: application/json: schema: $ref: '#/components/schemas/WalletApiError' example: error: unknown partner id WalletNotFound: description: >- `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. content: application/json: schema: $ref: '#/components/schemas/WalletApiError' example: error: wallet not found WalletRateLimited: description: >- `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. content: application/json: schema: $ref: '#/components/schemas/WalletApiError' example: error: rate limit exceeded for this endpoint; retry later WalletInternalError: description: '`internal error`.' content: application/json: schema: $ref: '#/components/schemas/WalletApiError' example: error: internal error WalletVenueUnavailable: description: >- A venue did not answer cleanly, e.g. `Hyperliquid is unavailable; retry shortly`, `Predict.fun is unavailable; retry shortly`. Retry. content: application/json: schema: $ref: '#/components/schemas/WalletApiError' WalletServiceUnavailable: description: >- `partner registry unavailable; retry shortly`; `rate limiter unavailable` (the rate limiter fails closed); `wallet sign-in is not configured on this node`; ` is not available right now`. Retry later. content: application/json: schema: $ref: '#/components/schemas/WalletApiError' WalletGatewayTimeout: description: >- `… did not answer in time; GET /v3/actions/{id} before retrying`. The request may have taken effect: read the state before repeating it. content: application/json: schema: $ref: '#/components/schemas/WalletApiError' securitySchemes: walletPartnerId: type: apiKey in: header name: X-Kairos-Partner-Id description: >- Wallet API partner id, issued by Kairos together with the partner's base URL. Identifies the partner (tenant) on every `/v3` call; sent instead of an API key. Letters, digits and `._:-`, at most 64 characters, case-insensitive. A partner id issued for an individual account cannot be sent this way — that account sends its API key triple instead. walletSignIn: type: apiKey in: header name: Authorization description: >- Wallet sign-in token: `SIWE `, where `` is `result.token` from a `login` action (exactly one space after `SIWE`). Proves the wallet on reads of its orders and positions, and on trade plans, fee settlements and on-chain intents. The token is bound to the partner and the environment that issued it and lasts 24 hours; run a new `login` action to renew it. apiKeyClientId: type: apiKey in: header name: X-Client-Id description: >- Credential client id (`kairos_ck_...`). Must be sent together with X-Api-Key and X-Api-Secret. apiKeyKey: type: apiKey in: header name: X-Api-Key description: 64-char hex API key. apiKeySecret: type: apiKey in: header name: X-Api-Secret description: 64-char hex API secret. bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- First-party Kairos session JWT (web app sessions). Not issued to API consumers. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.