--- title: "Get a combined platform + exchange fee quote for a prospective trade" method: GET path: "/orders/fee-quote" tags: ["Orders"] --- # Get a combined platform + exchange fee quote for a prospective trade `GET /orders/fee-quote` ## Request - Base URL: `https://execution.kairos.trade` - URL: `https://execution.kairos.trade/orders/fee-quote` - Auth: API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret` Prices a trade you are considering WITHOUT submitting it: for a market order (`order_type=market`, `price` omitted) the live orderbook is walked for `quantity` to compute a size-weighted executable price; for a limit order (`order_type=limit`) `price` is required and used as the resting quote. Shares the exact computation used by the WebSocket RFQ stream (`subscribe_fee_quote`), so the two surfaces can never price a trade differently. Quotes are display-only, degrade-open estimates (`is_estimate: true`) — the authoritative fee is computed at fill time. If no fresh orderbook is available, every numeric field is a `"0"` placeholder and `pricing_unavailable: true`; callers MUST check that flag rather than rendering the zeros as a real quote. Supported `exchange_id` values: `polymarket`, `kalshi`, `predictfun`. **Auth & scope.** Requires `trade:read`. ## Query parameters - `exchange_id` 'polymarket' | 'kalshi' | 'predictfun', required - `market_id` string - `token_id` string - `quantity` string, required - `side` 'buy' | 'sell', required - `price` string - `order_type` 'market' | 'limit', required ## Response `200` Combined platform + exchange fee quote. - OrderFeeQuoteResponse: Response for `GET /orders/fee-quote`. All numeric fields are decimal strings in USDC. The WebSocket `subscribe_fee_quote` stream emits a near-identical frame, but it omits `venue_reserve_fee_usdc` — do not treat the two as interchangeable. See `execution-ws.asyncapi.yaml`. - `avg_price_usdc` string, required: Size-weighted executable price (VWAP for a market order), or the limit price for a limit order. - `filled_size` string, required: Size the book can actually fill; equals `requested_size` when liquidity suffices. - `requested_size` string, required: The size the caller asked to quote (echoes `quantity`). - `sufficient_liquidity` boolean, required: False when the book cannot fill the full `requested_size`. - `notional_usdc` string, required: `filled_size × avg_price_usdc`. - `platform_fee_usdc` string, required: Kairos platform fee, based on the caller's fee tier. `"0"` if the tier lookup failed (fails open, never a phantom rate). - `exchange_fee_usdc` string, required: Venue-specific fee the caller is expected to pay. `"0"` on venues that only charge takers when this quote is a resting maker order. - `venue_reserve_fee_usdc` string, required: Fee the VENUE actually reserves to accept the order — distinct from `exchange_fee_usdc`. Some venues (Polymarket CLOB) can't know a resting limit will stay maker, so they reserve the taker estimate at placement regardless; buy-affordability checks must size off this field, not `exchange_fee_usdc`. - `total_fee_usdc` string, required: `platform_fee_usdc + exchange_fee_usdc`. - `exchange_fee_note` string, nullable: Human-readable note on the exchange fee, e.g. "1.8% taker fee". - `total_cost_usdc` string, required: All-in cost — for a buy, `notional + fees`; for a sell, `proceeds = notional − fees`. - `pricing_unavailable` boolean, required: `true` when no executable price was available (no client price and no fresh orderbook) — every other numeric field is a placeholder `"0"` and MUST NOT be rendered as a real quote. - `is_estimate` boolean, required: Always `true` — this is a display estimate; the authoritative fee is computed at fill time. - `funding_tier` 't0_local' | 't1_prepositioned' | 't2_bridge' | 'reject', required: Which rails run to fund this order. `t0_local` means no collateral moves; only `t2_bridge` carries a bridge fee. It names the movement, not whether the balance suffices. - `bridge_fee_usdc` string, nullable, required: Bridge fee in USDC. `"0"` below `t2_bridge`, and `null` exactly when `bridge_quote_unavailable` is `true` — an unknown fee is never rendered as `$0.00`. This fee is already included in `total_cost_usdc`, and buy-affordability checks must include it too. - `bridge_eta_p50_ms` integer, nullable, required: Median bridge fill time from Kairos's own completed intents, never a provider estimate. Present only once the route has ≥1,000 samples and its p90 ETA error is within ±10s. - `bridge_eta_p95_ms` integer, nullable, required: 95th-percentile bridge fill time from Kairos's own completed intents. Present under the same gate as `bridge_eta_p50_ms`. - `bridge_route_label` string, nullable, required: The route in the user's words, naming the token the rail DELIVERS, e.g. "BNB USDT → Polymarket pUSD via Relay". Absent when nothing bridges. - `bridge_min_txs` integer, nullable, required: On-chain transactions the bridge route needs, so a client can price the signing path. Absent when nothing bridges. - `bridge_eta_state` 'measured' | 'not_yet_measured', nullable, required: Whether the ETA above is a measurement or an admission that the route has not earned one. Absent when nothing bridges. - `bridge_quote_unavailable` boolean, required: `true` when a bridge is needed and no quote landed. Consumers MUST render a "routing…" state and disable submit rather than showing any fee; `bridge_fee_usdc` is `null` in this state. - `bridge_beta` boolean, required: `true` while tier-2 bridge funding is behind a flag, so the bridge row can be labelled beta. ## Other responses - `400`: Unsupported `exchange_id`, invalid `order_type`/`side`, non-positive `quantity`, `price` out of `(0, 1]`, a limit order missing `price`, or a Polymarket quote missing both `token_id` and `market_id`. Empty body (status code only) — the specific validation failure is logged server-side but never returned. - `401`: No valid credential presented — missing/invalid API-key headers or an invalid/expired session token. - `403`: Missing `trade:read` scope, or API-key access to this provider is disabled. Empty body (status code only). - `503`: API-key access to this provider could not be checked (fails closed). Empty body (status code only). --- [API](https://skmtc.dev/kairos/apis/kairos-order-execution-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-order-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-order-execution-api/revisions/9ba7d463d505?raw)