Fees (preview)

Post the wallet's signature or transaction hash for a settlement

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.

Answers a settlement in awaiting_signature: a signature on Polymarket, a transactionHash on Predict.fun — never both. On success the settlement is submitted; poll GET /v3/fees/settlements/{id} until it is confirmed.

A Polymarket signature must be a plain 65-byte ECDSA signature from wallet (low-s); smart-account signatures are refused. It is accepted until 30 s before expiresAt. wallet must be the wallet that opened the settlement (walletRequest.request.params[0] on Polymarket).

POST

fees

settlements

{id}

answer

curl --request POST \
  --url https://execution.kairos.trade/v3/fees/settlements/{id}/answer \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Kairos-Partner-Id: <api-key>' \
  --data '
{
  "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
  "signature": "0x4f8b2c1d9e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c3d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e1b"
}
'

{
  "id": "4e1d2c3b-5a6f-4b7c-8d9e-0f1a2b3c4d5e",
  "venue": "polymarket",
  "status": "awaiting_signature",
  "holdingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
  "assetKey": "evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb",
  "chainId": "137",
  "token": "0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb",
  "treasury": "0x3333333333333333333333333333333333333333",
  "decimals": 6,
  "amountRaw": "12500000",
  "transactionHash": null,
  "expiresAt": "2026-10-28T12:30:00Z",
  "failure": null,
  "walletRequest": {
    "kind": "signature",
    "chainId": "0x89",
    "request": {
      "method": "eth_signTypedData_v4",
      "params": [
        "0x8ba1f109551bd432803012645ac136ddd64dba72",
        "{\"types\":{\"EIP712Domain\":[…],\"Batch\":[{\"name\":\"wallet\",\"type\":\"address\"},{\"name\":\"nonce\",\"type\":\"uint256\"},{\"name\":\"deadline\",\"type\":\"uint256\"},{\"name\":\"calls\",\"type\":\"Call[]\"}],\"Call\":[…]},\"domain\":{\"name\":\"DepositWallet\",\"version\":\"1\",\"chainId\":\"137\",\"verifyingContract\":\"0x2f9c…4c3b\"},\"primaryType\":\"Batch\",\"message\":{…}}"
      ]
    }
  }
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

{
  "error": "API key missing trade:read scope"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

{
  "error": "rate limit exceeded for this endpoint; retry later"
}

{
  "error": "internal error"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

Authorizations

X-Kairos-Partner-Id

string

header

required

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.

Authorization

string

header

required

Wallet sign-in token: SIWE <token>, where <token> is result.token from a login action (exactly one space after SIWE). Proves the wallet on reads of its orders and positions, and on trade plans, fee settlements and on-chain intents. The token is bound to the partner and the environment that issued it and lasts 24 hours; run a new login action to renew it.

Path Parameters

string<uuid>

required

Settlement id.

Body

application/json

Send signature (Polymarket) or transactionHash (Predict.fun) — exactly one.

wallet

string

required

EVM address, 0x + 40 hex.

Pattern: ^0x[0-9a-fA-F]{40}$

Example:

"0x8ba1f109551bd432803012645ac136ddd64dba72"

signature

string

Polymarket — 65-byte ECDSA signature of walletRequest, 0x-prefixed hex (v of 0, 1, 27 or 28; low-s).

Pattern: ^0x[0-9a-fA-F]{130}$

transactionHash

string

Predict.fun — 0x + 64 hex hash of the payment transaction (not all zeros).

Pattern: ^0x[0-9a-fA-F]{64}$

Response

The settlement, refreshed after the answer — usually submitted. If the payment transaction is already known and in a finalized block (a Predict.fun hash, or a batch the relayer reports mined), it may come back confirmed or failed.

A payment of a wallet's unpaid fees on one venue. The amount is frozen when the settlement opens.

string<uuid>

required

venue

enum<string>

required

Available options:

polymarket,

predictfun

status

enum<string>

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

Available options:

awaiting_signature,

submitted,

confirmed,

failed,

expired

holdingWallet

string

required

Address the fee is paid from — Polymarket's trading wallet, or the wallet itself on Predict.fun.

assetKey

string

required

Example:

"evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb"

chainId

string

required

Chain id as a decimal string (walletRequest.chainId is hex).

Example:

"137"

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

required

The payment transaction, once known.

expiresAt

string<date-time> | null

required

Polymarket — sign before this (30 minutes after opening). null on Predict.fun.

failure

string | null

required

Why the settlement failed or expired. Kept when a late Predict.fun payment later confirms an expired settlement.

walletRequest

object | null

required

Present only while awaiting_signature.

Show child attributes

Example:

{
  "kind": "transaction",
  "chainId": "0x38",
  "request": {
    "method": "eth_sendTransaction",
    "params": [
      {
        "from": "0x8ba1f109551bd432803012645ac136ddd64dba72",
        "to": "0x55d398326f99059ff775485246999027b3197955",
        "value": "0x0",
        "data": "0xa9059cbb0000000000000000000000003333333333333333333333333333333333333333000000000000000000000000000000000000000000000000ad78ebc5ac620000",
        "chainId": "0x38"
      }
    ]
  }
}

curl --request POST \
  --url https://execution.kairos.trade/v3/fees/settlements/{id}/answer \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Kairos-Partner-Id: <api-key>' \
  --data '
{
  "wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
  "signature": "0x4f8b2c1d9e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c3d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e1b"
}
'

{
  "id": "4e1d2c3b-5a6f-4b7c-8d9e-0f1a2b3c4d5e",
  "venue": "polymarket",
  "status": "awaiting_signature",
  "holdingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
  "assetKey": "evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb",
  "chainId": "137",
  "token": "0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb",
  "treasury": "0x3333333333333333333333333333333333333333",
  "decimals": 6,
  "amountRaw": "12500000",
  "transactionHash": null,
  "expiresAt": "2026-10-28T12:30:00Z",
  "failure": null,
  "walletRequest": {
    "kind": "signature",
    "chainId": "0x89",
    "request": {
      "method": "eth_signTypedData_v4",
      "params": [
        "0x8ba1f109551bd432803012645ac136ddd64dba72",
        "{\"types\":{\"EIP712Domain\":[…],\"Batch\":[{\"name\":\"wallet\",\"type\":\"address\"},{\"name\":\"nonce\",\"type\":\"uint256\"},{\"name\":\"deadline\",\"type\":\"uint256\"},{\"name\":\"calls\",\"type\":\"Call[]\"}],\"Call\":[…]},\"domain\":{\"name\":\"DepositWallet\",\"version\":\"1\",\"chainId\":\"137\",\"verifyingContract\":\"0x2f9c…4c3b\"},\"primaryType\":\"Batch\",\"message\":{…}}"
      ]
    }
  }
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

{
  "error": "API key missing trade:read scope"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

Failed to deserialize the JSON body into the target type: action.price: invalid type: floating point `0.52`, expected a string

{
  "error": "rate limit exceeded for this endpoint; retry later"
}

{
  "error": "internal error"
}

{
  "error": "unknown or expired action"
}

{
  "error": "unknown or expired action"
}

Get started

Onboard users

Trade

Route and fund

Partner fees

Build

Endpoints

Post the wallet's signature or transaction hash for a settlement

Authorizations

Path Parameters

Body

Response