> ## 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. # Read a wallet's readiness and balances per venue > 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. ## OpenAPI ````yaml /openapi/wallet-api.json get /v3/wallets/{address} 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}: get: tags: - Reads summary: Read a wallet's readiness and balances per venue description: >- 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. operationId: getWalletStatus parameters: - $ref: '#/components/parameters/WalletAddressPath' - $ref: '#/components/parameters/WalletApiVersion' responses: '200': description: Readiness and balances per venue. content: application/json: schema: $ref: '#/components/schemas/WalletStatus' '400': description: '`wallet must be a 0x address`, or a malformed partner id.' content: application/json: schema: $ref: '#/components/schemas/WalletApiError' '401': $ref: '#/components/responses/WalletTenantUnauthorized' '403': $ref: '#/components/responses/WalletTenantForbidden' '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: [] - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] 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' schemas: WalletStatus: type: object description: Response of `GET /v3/wallets/{address}`. required: - wallet - ready - next - venues properties: wallet: $ref: '#/components/schemas/WalletAddress' ready: type: boolean description: >- Every venue that could be read is ready, and at least one could be read. next: type: - string - 'null' enum: - setup - wait - fund - blocked - null description: The most urgent next step across venues. venues: type: object description: Readiness per venue offered on this deployment. additionalProperties: $ref: '#/components/schemas/WalletVenueStatus' tradingWallet: type: - string - 'null' description: Polymarket's trading wallet, when Polymarket is offered. balance: type: - string - 'null' description: Polymarket's balance, when Polymarket is offered. example: wallet: '0x8ba1f109551bd432803012645ac136ddd64dba72' ready: false next: fund venues: polymarket: ready: true next: null tradingWallet: '0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b' balance: '25' currency: pUSD venueDetail: chainId: '0x89' asOf: '2026-10-28T12:00:00.125Z' predictfun: ready: false next: fund tradingWallet: '0x8ba1f109551bd432803012645ac136ddd64dba72' balance: '0' currency: USDT venueDetail: chainId: '0x38' gasBalance: '0' missingApprovals: 3 sessionExpiresAt: null asOf: '2026-10-28T12:00:00.140Z' hyperliquid: ready: true next: fund tradingWallet: '0x8ba1f109551bd432803012645ac136ddd64dba72' balance: '0' currency: USDC venueDetail: chainId: '0xa4b1' network: Mainnet transferFromPerps: available: '12.5' note: >- your next order asks you to move what it needs from perps to spot asOf: '2026-10-28T12:00:00.180Z' tradingWallet: '0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b' balance: '25' 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 WalletAddress: type: string description: EVM address, `0x` + 40 hex. pattern: ^0x[0-9a-fA-F]{40}$ example: '0x8ba1f109551bd432803012645ac136ddd64dba72' WalletVenueStatus: type: object description: >- One venue's readiness. A venue whose read failed is `{ready: false, available: false, error}`. required: - ready properties: ready: type: boolean next: type: - string - 'null' enum: - setup - wait - fund - blocked - null description: What to do on this venue. tradingWallet: type: - string - 'null' description: >- Where this venue's collateral sits — Polymarket's trading wallet, or the wallet itself on Predict.fun and Hyperliquid. balance: type: - string - 'null' description: >- Collateral available to trade, whole units (decimal string); `null` when unknown. example: '25' currency: type: string description: >- `pUSD` (Polymarket), `USDT` (Predict.fun), `USDC` (Hyperliquid spot). venueDetail: $ref: '#/components/schemas/WalletVenueDetail' asOf: type: string format: date-time description: When the venue was read. available: type: boolean const: false description: Present (and `false`) only when the venue could not be read. error: type: string description: Why the venue could not be read. WalletVenueDetail: type: object description: Venue-specific detail. Keys appear only where they apply. properties: chainId: type: string description: Chain the venue settles on (hex). example: '0x89' gasBalance: type: - string - 'null' description: Predict.fun — BNB balance for gas, whole units. missingApprovals: type: integer description: Predict.fun — approvals still to send. sessionExpiresAt: type: - string - 'null' format: date-time description: Predict.fun — when the venue session ends. network: type: string description: Hyperliquid — `Mainnet` or `Testnet`. transferFromPerps: type: object description: >- Hyperliquid — USDC in perps the next order can move to spot (with an extra prompt). properties: available: type: string example: '12.5' note: type: string code: type: string description: >- Hyperliquid — `HYPERLIQUID_AGENT_MISSING` when the trading approval must be renewed by `setup`. reason: type: string description: Why the venue is not ready (fund, blocked, or approval renewal). blocked: type: boolean description: Hyperliquid — this account cannot be enrolled. accountMode: type: string description: Hyperliquid — the account mode that blocks enrollment. approvals: type: integer description: Setup result, Predict.fun — approvals the wallet needs gas for. gasWei: type: string description: Setup result, Predict.fun — estimated BNB gas needed, in wei. additionalProperties: true responses: WalletTenantUnauthorized: description: >- `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`. content: application/json: schema: $ref: '#/components/schemas/WalletApiError' example: error: >- send X-Kairos-Partner-Id or your API key (X-Client-Id, X-Api-Key, X-Api-Secret) 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 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. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.