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

# List a wallet's positions across venues

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

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/v3/wallets/{address}/positions`
- 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 open, resolved and closed positions across venues. Requires `Authorization: SIWE <token>` from a `login` action (or an API key whose Kairos account owns the wallet).

**The body is nested:** the rows are at `positions.positions`, with `positions.resolved`, `positions.closed` and `positions.asOf` beside them. When a venue cannot be read, `venueDetail.<venue>.error` says why.

## Path parameters

- `address` string, required

## Query parameters

- `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`

Positions across venues.

- WalletPositionsResponse: Response of `GET /v3/wallets/{address}/positions`. **Nested:** the rows are at `positions.positions`.
  - `positions` object, required
    - `positions` WalletPosition[], required: Open positions.
      - `venue` 'polymarket' | 'predictfun' | 'hyperliquid', required: Venue id. `predict.fun` is accepted as an input alias of `predictfun`.
      - `market` string, required
      - `marketId` string, required
      - `outcome` string, nullable, required
      - `tokenId` string, nullable, required
      - `size` string, nullable, required: Shares held.
      - `availableToSell` string, nullable, required: Shares not reserved by open sell orders.
      - `avgPrice` string, nullable, required: Average entry price, 0–1.
      - `realizedPnl` string, nullable, required
      - `holdingWallet` string, nullable, required: The address that holds the shares.
      - `lastTradeAt` string, date-time, nullable, required
    - `resolved` WalletResolvedPosition[], required: Positions in resolved markets.
      - `venue` 'polymarket' | 'predictfun' | 'hyperliquid', required: Venue id. `predict.fun` is accepted as an input alias of `predictfun`.
      - `market` string, required
      - `marketId` string, required
      - `outcome` string, nullable, required
      - `tokenId` string, nullable, required
      - `size` string, nullable, required
      - `redeemable` boolean, nullable, required: The shares can be redeemed for collateral.
      - `holdingWallet` string, nullable, required
    - `closed` object[], required: Positions closed out.
      - `venue` 'polymarket' | 'predictfun' | 'hyperliquid', required: Venue id. `predict.fun` is accepted as an input alias of `predictfun`.
      - `tokenId` string, nullable, required
    - `asOf` 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`.
- `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)