Fees (preview)

Read (and advance) a fee 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.

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.

GET

fees

settlements

{id}

Read (and advance) a fee settlement

curl --request GET \
  --url https://execution.kairos.trade/v3/fees/settlements/{id} \
  --header 'Authorization: <api-key>' \
  --header 'X-Kairos-Partner-Id: <api-key>'

import requests

url = "https://execution.kairos.trade/v3/fees/settlements/{id}"

headers = {
    "X-Kairos-Partner-Id": "<api-key>",
    "Authorization": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-Kairos-Partner-Id': '<api-key>', Authorization: '<api-key>'}
};

fetch('https://execution.kairos.trade/v3/fees/settlements/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://execution.kairos.trade/v3/fees/settlements/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "X-Kairos-Partner-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://execution.kairos.trade/v3/fees/settlements/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Kairos-Partner-Id", "<api-key>")
	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://execution.kairos.trade/v3/fees/settlements/{id}")
  .header("X-Kairos-Partner-Id", "<api-key>")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://execution.kairos.trade/v3/fees/settlements/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Kairos-Partner-Id"] = '<api-key>'
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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": "sign-in token has expired; run a login action"
}

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

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

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

{
  "error": "internal error"
}

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

Query Parameters

wallet

string

required

The wallet's EVM address. No other query parameter is accepted.

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

Response

The refreshed settlement.

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

Read (and advance) a fee settlement

curl --request GET \
  --url https://execution.kairos.trade/v3/fees/settlements/{id} \
  --header 'Authorization: <api-key>' \
  --header 'X-Kairos-Partner-Id: <api-key>'

import requests

url = "https://execution.kairos.trade/v3/fees/settlements/{id}"

headers = {
    "X-Kairos-Partner-Id": "<api-key>",
    "Authorization": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-Kairos-Partner-Id': '<api-key>', Authorization: '<api-key>'}
};

fetch('https://execution.kairos.trade/v3/fees/settlements/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://execution.kairos.trade/v3/fees/settlements/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "X-Kairos-Partner-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://execution.kairos.trade/v3/fees/settlements/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Kairos-Partner-Id", "<api-key>")
	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://execution.kairos.trade/v3/fees/settlements/{id}")
  .header("X-Kairos-Partner-Id", "<api-key>")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://execution.kairos.trade/v3/fees/settlements/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Kairos-Partner-Id"] = '<api-key>'
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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": "sign-in token has expired; run a login action"
}

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

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

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

{
  "error": "internal error"
}

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

Get started

Onboard users

Trade

Route and fund

Partner fees

Build

Endpoints

Read (and advance) a fee settlement

Authorizations

Path Parameters

Query Parameters

Response