---
title: "Read (and advance) a fee settlement"
method: GET
path: "/v3/fees/settlements/{id}"
tags: ["Fees (preview)"]
---

# Read (and advance) a fee settlement

`GET /v3/fees/settlements/{id}`

## Request

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

Returns the settlement after refreshing it from chain evidence. **This read is what advances a settlement** — poll it until `status` is terminal (`confirmed`, `failed`, `expired`). `confirmed` requires the payment to be in a **finalized** block, so it can trail the transaction by minutes.

Statuses: `awaiting_signature` → (answer) → `submitted` → `confirmed`. A Polymarket settlement left unsigned past `expiresAt` becomes `expired`; a Predict.fun hash that never appears on chain within an hour becomes `expired`. If that transaction lands within 7 days of expiring, `GET /v3/fees` or `POST /v3/fees/settlements` (not this read) credits it and moves the settlement to `confirmed`. A Polymarket batch the relayer fails, or never executes by 5 minutes after `expiresAt`, becomes `failed`. `failed` carries a reason in `failure`, for example `the transaction reverted`, `transfer differs from the settlement`, `receipt contains no settlement transfer`, `receipt pays the settlement more than once`, `transaction predates the settlement`.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `wallet` string, required

## Response `200`

The refreshed settlement.

- WalletFeeSettlement: 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 non-UUID `{id}` or a bad query. 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`: `fee settlement not found`; `wallet not found`.
- `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)