---
title: "Read a wallet's unpaid trading fees per venue"
method: GET
path: "/v3/fees"
tags: ["Fees (preview)"]
---

# Read a wallet's unpaid trading fees per venue

`GET /v3/fees`

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/v3/fees`
- 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

Preview: available on staging (`https://staging-execution.kairos.trade`); not yet released in production, where trade plans — the only source of this fee debt — return `503`.

Trades placed through **trade plans** on Polymarket and Predict.fun accrue the Kairos fee and the partner fee as a debt per wallet and collateral asset; nothing is deducted inside the order. This read returns the debt per venue, the threshold at which `POST /v3/trade-plans` refuses new trades with `FEE_SETTLEMENT_REQUIRED`, and any open settlement.

`owedRaw` is a signed integer string in token base units: it is **negative** when confirmed payments exceed the fees booked so far (a credit carried against later fees). The threshold is set by Kairos per partner. A venue whose settlement rail is not offered is omitted.

Reading also advances settlements: it refreshes the open settlement from chain evidence and credits late payments. Hyperliquid has no fee debt on this API.

## Query parameters

- `wallet` string, required

## Response `200`

Debt per venue.

- WalletFeeSummary: Response of `GET /v3/fees`.
  - `venues` WalletFeeVenue[], required
    - `venue` 'polymarket' | 'predictfun', required
    - `holdingWallet` string, required
    - `assetKey` string, required
    - `decimals` integer, required
    - `owedRaw` string, required: Unpaid Kairos and partner fees, minus confirmed payments. **May be negative** (a credit against later fees).
    - `thresholdRaw` string, required: At or above this, new trade plans are refused with `FEE_SETTLEMENT_REQUIRED`.
    - `settlement` WalletFeeSettlement, required: A payment of a wallet's unpaid fees on one venue. The amount is frozen when the settlement opens.
      - `id` string, uuid, required
      - `venue` 'polymarket' | 'predictfun', required
      - `status` 'awaiting_signature' | 'submitted' | 'confirmed' | 'failed' | 'expired', required: `awaiting_signature` → `submitted` → `confirmed`. Terminal: `confirmed` and `failed`. `expired` is final unless it is a Predict.fun settlement whose reported transaction lands within 7 days of expiring: `GET /v3/fees` or `POST /v3/fees/settlements` then credits it and it becomes `confirmed` (`GET /v3/fees/settlements/{id}` does not re-check an expired settlement).
      - `holdingWallet` string, required: Address the fee is paid from — Polymarket's trading wallet, or the wallet itself on Predict.fun.
      - `assetKey` string, required
      - `chainId` string, required: Chain id as a **decimal** string (`walletRequest.chainId` is hex).
      - `token` string, required: Fee token (pUSD on Polygon, USDT on BNB Chain).
      - `treasury` string, required: The payee address.
      - `decimals` integer, required: Token decimals (6 for pUSD, 18 for BNB Chain USDT).
      - `amountRaw` string, required: Amount to pay, integer string in token base units.
      - `transactionHash` string, nullable, required: The payment transaction, once known.
      - `expiresAt` string, date-time, nullable, required: Polymarket — sign before this (30 minutes after opening). `null` on Predict.fun.
      - `failure` string, nullable, required: Why the settlement failed or expired. Kept when a late Predict.fun payment later confirms an `expired` settlement.
      - `walletRequest` WalletFeeWalletRequest, required: What the wallet runs to pay a settlement. `kind: signature` (Polymarket) — sign it and answer with `signature`; `kind: transaction` (Predict.fun) — send it unchanged and answer with `transactionHash`.
        - `kind` 'signature' | 'transaction', required
        - `chainId` string, required: Chain to switch to, **hex** (`0x89` or `0x38`).
        - `request` WalletEip1193Request, required: An EIP-1193 request to run through the wallet's provider exactly as given (`provider.request({method, params})`). - `eth_signTypedData_v4`: `params` = `[address, typedData]` — `typedData` is a **JSON string**; pass it unchanged. - `personal_sign`: `params` = `[hexMessage, address]`. - `wallet_sendCalls` (EIP-5792): `params` = `[{version, chainId, from, atomicRequired, calls}]`; the wallet pays gas. - `eth_sendTransaction`: `params` = `[{from, to, data, value, chainId?}]`; the wallet pays gas.
          - `method` 'eth_signTypedData_v4' | 'personal_sign' | 'wallet_sendCalls' | 'eth_sendTransaction', required
          - `params` unknown[], required
            - unknown

## Other responses

- `400`: `wallet must be a 0x address`. Plain text for a missing `wallet` or any other query parameter. With API-key wallet proof a malformed `wallet` is `404 wallet not found` instead.
- `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`: `API key missing trade:read scope` (reads) or `API key missing trade:execute scope` (writes) when an API key is the caller — `trade:execute` does not imply `trade:read`; or a tenant refusal: `unknown partner id`, `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`, `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`.
- `503`: `fee settlement storage is unavailable`; `the BNB Chain treasury is unavailable`; another settlement dependency is unavailable; `the chain RPC is unavailable`; `partner registry unavailable; retry shortly`; `rate limiter unavailable`. Retry later.

---

[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)