---
title: "Read a wallet's readiness and balances per venue"
method: GET
path: "/v3/wallets/{address}"
tags: ["Reads"]
---

# Read a wallet's readiness and balances per venue

`GET /v3/wallets/{address}`

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/v3/wallets/{address}`
- 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 whether the wallet is ready to trade on each venue, what to do next, and the venue balance. Needs only the partner id or API key — no wallet sign-in — because it reports on-chain state and readiness, not orders.

**`next`** tells the app what to do: `setup` (run a `setup` action), `wait` (approvals are confirming), `fund` (deposit collateral, or gas on Predict.fun), `blocked` (Hyperliquid cannot enroll this account; see `venueDetail.reason`), or `null`. The top-level `next` picks the most urgent across not-ready venues (`setup` > `wait` > `fund` > `blocked`); when every venue is ready it is `fund` if no ready venue reports a non-zero balance — including when a balance is unknown (`null`).

Venues not offered on the deployment are omitted. A venue whose read failed appears as `{"ready": false, "available": false, "error": …}` and is left out of the top-level `ready` and `next`. Readings may be up to 30 s old (`asOf`); a setup action refreshes them.

## Path parameters

- `address` string, required

## Headers

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

## Response `200`

Readiness and balances per venue.

- WalletStatus: Response of `GET /v3/wallets/{address}`.
  - `wallet` string, required: EVM address, `0x` + 40 hex.
  - `ready` boolean, required: Every venue that could be read is ready, and at least one could be read.
  - `next` 'setup' | 'wait' | 'fund' | 'blocked' | 'null', nullable, required: The most urgent next step across venues.
  - `venues` object, required: Readiness per venue offered on this deployment.
  - `tradingWallet` string, nullable: Polymarket's trading wallet, when Polymarket is offered.
  - `balance` string, nullable: Polymarket's balance, when Polymarket is offered.

## Other responses

- `400`: `wallet must be a 0x address`, or a malformed partner id.
- `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`.
- `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)