Reads

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.

get/v3/wallets/{address}

Request

Base URL
https://execution.kairos.trade
Auth
- API key in header X-Kairos-Partner-Id
- or API key in header X-Client-Id and API key in header X-Api-Key and API key in header X-Api-Secret

Path parameters

addressstring required

The wallet's EVM address (0x + 40 hex; checksum not required).

Headers

X-Kairos-Wallet-Api'2' required

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.

Response

Readiness and balances per venue.

walletstring required

EVM address, 0x + 40 hex.

readyboolean 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.

venuesobject required

Readiness per venue offered on this deployment.

tradingWalletstring nullable

Polymarket's trading wallet, when Polymarket is offered.

balancestring nullable

Polymarket's balance, when Polymarket is offered.

Example response

{
  "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"
}

Changes

No recorded changes to this operation across all 1 revision of this API.