Partner fees and settlement

Preview. Partner fees and fee settlement come with trade plans, which aren’t available in production yet and are still being validated on staging. Orders placed with /v3/actions carry no partner fee. Ask Kairos before you build on this.

A fill on a trade plan can carry three charges:

Charge	Who sets it	How it’s paid
Venue fee	The venue	By the venue, in the trade itself. See Fees
Kairos fee	Kairos, from the wallet’s fee tier	Accrues as a balance the wallet owes, paid in a fee settlement
Your partner fee	You, through the schedule Kairos configures for you	Added to the Kairos fee and paid in the same settlement. Kairos pays your share out to you

The wallet signs the ceiling of every charge before anything trades. Kairos can charge less than the signed ceiling, never more.

Your fee schedule

Kairos sets up your schedule with you. There is no self-serve API: tell your Kairos contact what you want. A schedule is a list of bands. Each band gives a maker rate and a taker rate:

{
  "minNotionalUsd": "0",
  "minVolume30dUsd": "0",
  "maker": { "model": "flat", "bps": 0 },
  "taker": { "model": "flat", "bps": 25 }
}

Rate shapes

A rate is in whole basis points, from 0 to 1000 (10%). Pick a shape per side:

Flat
Curve
Parabolic

The same rate at every price.

{ "model": "flat", "bps": 25 }

A rate that changes with the fill price. Give 2–32 points with prices from 0 to 1 in increasing order. Rates are linear between points and flat beyond the first and last.

{ "model": "curve", "points": [
  { "price": "0",   "feeBps": 10 },
  { "price": "0.5", "feeBps": 60 },
  { "price": "1",   "feeBps": 10 }
] }

A smooth rate that peaks (or dips) at a price of 0.5: edge + 4 × (center − edge) × p × (1 − p).

{ "model": "parabolic", "edgeBps": 5, "centerBps": 40 }

At p = 0.5 the rate is centerBps. At p = 0 or 1 it is edgeBps.

Price-shaped fees suit prediction markets: a share at 0.97 has little room left, so a flat percentage of notional takes a large bite of the possible profit.

Bands

A schedule has 1–16 bands. The first starts at 0 / 0. Each later band raises minNotionalUsd, minVolume30dUsd, or both, and never lowers either. For each trade, the highest band whose two thresholds the trade meets applies:

minNotionalUsd is compared with the trade’s notional (its collateral amount, in USD).
minVolume30dUsd is compared with the user’s rolling 30-day trading volume on Kairos.

[
  { "minNotionalUsd": "0",    "minVolume30dUsd": "0",      "maker": { "model": "flat", "bps": 0 }, "taker": { "model": "flat", "bps": 30 } },
  { "minNotionalUsd": "1000", "minVolume30dUsd": "0",      "maker": { "model": "flat", "bps": 0 }, "taker": { "model": "flat", "bps": 20 } },
  { "minNotionalUsd": "1000", "minVolume30dUsd": "250000", "maker": { "model": "flat", "bps": 0 }, "taker": { "model": "flat", "bps": 10 } }
]

Scope

You can have one schedule for every venue, plus one per venue (Polymarket, Predict.fun). Kairos can also give a single user their own schedule, optionally with an end date. The most specific active schedule wins: a user’s own over yours, and a venue’s over the all-venue one.

Limits

Combined ceiling: 10%. Kairos’s highest possible rate plus your highest possible rate must be 1000 bps or less. A plan over it is refused with 422 the combined Kairos and partner fee exceeds the 10% platform ceiling.
No per-order flat fees, minimum or maximum charges, or rebates.
Hyperliquid trades never carry a partner fee.
Changing your schedule affects new plans only. A prepared plan keeps the terms the wallet signed.

What the wallet signs

When you prepare a trade plan, the plan’s tradeBudget pins the fee terms. The planHash the wallet signs covers them. Illustrative values for a $52 Polymarket buy:

"tradeBudget": {
  "collateral": { "kind": "evm", "chainId": "137", "token": "0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb" },
  "decimals": 6,
  "notionalRaw": "52000000",
  "maxPlatformFeeBps": 75,
  "maxCollateralFeeRaw": "1690000",
  "maxDebitRaw": "53690000",
  "existingSpendableRaw": "60000000",
  "partnerFee": {
    "scheduleId": "4b1d…",
    "maxBps": 25,
    "maker": { "model": "flat", "bps": 0 },
    "taker": { "model": "flat", "bps": 25 }
  }
}

Field	Means
`maxPlatformFeeBps`	Kairos’s highest rate for this wallet plus your `partnerFee.maxBps`. The most the combined fee can be
`partnerFee`	Your band for this trade. Absent when you charge nothing or the venue is Hyperliquid
`maxCollateralFeeRaw`	The most the fees can total, in collateral base units: the platform fee ceiling plus the venue fee bound, rounded up
`maxDebitRaw`	`notionalRaw + maxCollateralFeeRaw`. The most the trade can cost the wallet

Show these to the user before the wallet signs. Amounts ending in Raw are integers in the token’s base units (decimals: 6 for pUSD and USDC, 18 for BNB Chain USDT).

How a fill is charged

For each fill:

kairos rate  = min(the wallet's Kairos rate now, maxPlatformFeeBps − partnerFee.maxBps)
partner rate = your shape for this side (maker or taker), at the fill price
fee          = fill size × fill price × (kairos rate + partner rate) / 10,000

Fees are on notional (what the shares cost), not on the number of shares.
If the wallet’s Kairos tier improves after signing, it pays less. If it gets worse, Kairos still charges no more than it signed for.
Each fill’s fee is rounded to $0.000001.
If a fill would go past the plan’s signed budget, the charge is clipped. Your share is cut first.

Example. A plan signed with maxPlatformFeeBps: 75, your flat taker rate of 25 bps, and Kairos’s current rate of 50 bps. A taker fill of 100 shares at 0.52 has a notional of $52. Kairos charges 50 bps ($0.26) and you charge 25 bps ($0.13), for $0.39 in total.

How fees are collected

Kairos never takes a fee out of an order, and holds no allowance on the wallet. Fees add up as a balance the wallet owes, per venue. When the balance reaches your settlement threshold (default $10, up to $10,000; ask Kairos to change it), the wallet must pay it before its next trade plan:

// 409 from POST /v3/trade-plans
{
  "error": "unpaid trading fees must be settled before the next trade",
  "code": "FEE_SETTLEMENT_REQUIRED",
  "assetKey": "evm:137:0xc011a7e12a19f7b1f670d46f03b03f3342e82dfb",
  "owedRaw": "10420000",
  "thresholdRaw": "10000000"
}

Resting orders and plans already prepared keep working. Only new plans wait. The balance is per wallet and venue, across every partner the wallet trades through. The threshold that applies is yours, as the partner preparing the plan.

Venue	Paid in	What the wallet does	Gas
Polymarket	pUSD from the trading wallet	Signs one `Batch` (EIP-712) that makes one pUSD transfer. Kairos submits it	None
Predict.fun	USDT from the wallet, on BNB Chain	Sends one USDT `transfer` transaction itself, then reports its hash	The user pays BNB gas
Hyperliquid	—	Nothing. There is no partner fee and nothing to settle	—

With the SDK

const { venues } = await kairos.wallet.fees.summary(wallet)
// [{ venue: 'polymarket', owedRaw: '10420000', thresholdRaw: '10000000', decimals: 6, settlement: null, … }]

const settlement = await kairos.wallet.fees.settle(wallet, 'polymarket')
// signs (or sends) what's asked, then waits until it's final: check status
// { id: '…', status: 'confirmed', amountRaw: '10420000', transactionHash: '0x…', … }

Over HTTP

Read what the wallet owes

curl "$BASE/v3/fees?wallet=$WALLET" -H "X-Kairos-Partner-Id: $PARTNER" -H "X-Kairos-Wallet-Api: 2" -H "Authorization: SIWE $TOKEN"

{ "venues": [
  { "venue": "polymarket", "holdingWallet": "0x…", "assetKey": "evm:137:0xc011…2dfb",
    "decimals": 6, "owedRaw": "10420000", "thresholdRaw": "10000000", "settlement": null }
] }

owedRaw can be negative: the wallet overpaid, and the credit counts against later fees.

Open a settlement

curl -X POST "$BASE/v3/fees/settlements" \
  -H "X-Kairos-Partner-Id: $PARTNER" -H "X-Kairos-Wallet-Api: 2" -H "Authorization: SIWE $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "wallet": "0x…", "venue": "polymarket" }'

venue is polymarket or predictfun. The other calls below take the same headers.It freezes the whole current balance into amountRaw, and answers with what the wallet must do in walletRequest. If a settlement is already open for this wallet, you get that one back. 409 this wallet has no unpaid fees means there’s nothing to pay.

{ "id": "8f2c…", "venue": "polymarket", "status": "awaiting_signature",
  "holdingWallet": "0x…", "assetKey": "evm:137:0xc011…2dfb", "chainId": "137",
  "token": "0xc011…2dfb", "treasury": "0x…", "decimals": 6, "amountRaw": "10420000",
  "transactionHash": null, "expiresAt": "2026-10-28T12:30:00Z", "failure": null,
  "walletRequest": { "kind": "signature", "chainId": "0x89",
    "request": { "method": "eth_signTypedData_v4", "params": ["0xOwner", "{…Batch…}"] } } }

Sign or send

Polymarket (kind: "signature"): pass walletRequest.request to the wallet. The Batch holds one call: pUSD.transfer(treasury, amountRaw) from the trading wallet. Sign within 30 minutes (expiresAt).
Predict.fun (kind: "transaction"): the request is an eth_sendTransaction of USDT.transfer(treasury, amountRaw) on BNB Chain. Send it exactly as given, as its own transaction. There’s no deadline: expiresAt is null.

Answer

# Polymarket
curl -X POST "$BASE/v3/fees/settlements/$ID/answer" … -d '{ "wallet": "0x…", "signature": "0x…" }'
# Predict.fun
curl -X POST "$BASE/v3/fees/settlements/$ID/answer" … -d '{ "wallet": "0x…", "transactionHash": "0x…" }'

The settlement moves to submitted.

Poll until it's final

curl "$BASE/v3/fees/settlements/$ID?wallet=$WALLET" …

Reading the settlement is what checks the chain. Poll every few seconds until status is confirmed, failed or expired. Kairos credits a payment only once its block is final, which can take a few minutes. Until a read sees it confirmed, new trade plans still answer FEE_SETTLEMENT_REQUIRED.

Settlement states

`status`	Means	Next
`awaiting_signature`	Waiting for the wallet. `walletRequest` says what to do	Sign or send, then answer
`submitted`	Payment sent; waiting for a final block	Keep polling
`confirmed`	Paid and credited	Read `/v3/fees` again: fills after the settlement opened are still owed
`failed`	The payment didn’t match or reverted, or the Polymarket relayer refused or never ran the batch. `failure` says why	Open a new settlement
`expired`	Polymarket: not signed within 30 minutes. Predict.fun: the reported hash never appeared on chain within an hour	Open a new settlement

A Predict.fun payment whose hash was reported but only lands after its settlement expired is still credited, if it lands within 7 days.

Pay exactly amountRaw, in one transfer, in its own transaction. A Predict.fun transaction that pays a different amount, pays twice, or moves other USDT out of the wallet fails the settlement. That money isn’t credited automatically, so contact Kairos if it happens.

Settlement errors

Status	`error`
`400`	`answer with a signature on Polymarket or a transactionHash on Predict.fun`, `invalid transactionHash`
`401`	`signature does not authorize this fee settlement`
`404`	`fee settlement not found`, `wallet not found`
`409`	`this wallet has no unpaid fees`, `this fee settlement no longer accepts an answer`, `that transaction already paid another settlement`
`410`	`this fee settlement expired; create a new one`: a Polymarket answer less than 30 seconds before `expiresAt`
`422`	Unknown or missing JSON fields, or a `venue` other than `polymarket` or `predictfun`
`502`	`the Polymarket relayer refused the settlement` (the settlement is `failed`; open a new one)
`503`	Payment rail or chain data briefly unavailable. Retry

Reads (GET /v3/fees, GET …/settlements/{id}) need trade:read when you use an API key. Writes need trade:execute. With a partner id, send the wallet’s sign-in token.

Hyperliquid

Hyperliquid trades carry no partner fee and owe nothing through settlement. Where a Hyperliquid builder fee is configured, setup asks the wallet to approve it alongside the trading agent (ApproveBuilderFee, with the maximum rate shown as a percentage). The builder fee is at most 1%.

Reporting

GET /v3/fees shows a wallet’s balance and open settlement. For your partner earnings across wallets, ask Kairos for a statement: there is no partner reporting endpoint yet.

Get started

Onboard users

Trade

Route and fund

Partner fees

Build

Endpoints

Partner fees and settlement

Your fee schedule

Rate shapes

Bands

Scope

Limits

What the wallet signs

How a fill is charged

How fees are collected

With the SDK

Over HTTP

Settlement states

Settlement errors

Hyperliquid

Reporting

​Your fee schedule

​Rate shapes

​Bands

​Scope

​Limits

​What the wallet signs

​How a fill is charged

​How fees are collected

​With the SDK

​Over HTTP

​Settlement states

​Settlement errors

​Hyperliquid

​Reporting

Your fee schedule

Rate shapes

Bands

Scope

Limits

What the wallet signs

How a fill is charged

How fees are collected

With the SDK

Over HTTP

Settlement states

Settlement errors

Hyperliquid

Reporting