KAkairos
PnL

Get merged PnL data for a user across one or more wallets/providers

Fetches and merges PnL records/summary across the wallets supplied for this user via the general-purpose PnL path — not the real-time pipeline used by /pnl/hover and /pnl/wallet-totals. At least one of polymarket_wallet, kalshi_wallet, or hyperliquid_wallet is required — the request is rejected with 400 if none are supplied. polymarket_wallet and hyperliquid_wallet must be valid Ethereum addresses (normalized/lower-cased); kalshi_wallet is treated as an opaque user-id string (Kalshi is a CEX with internal, non-address identifiers). provider (repeatable query param, up to 16 items) filters the merged result down to specific provider(s); when omitted, all providers implied by the supplied wallets are used. Kalshi and Hyperliquid PnL are served only through this aggregate endpoint; neither is available from /pnl/hover or /pnl/wallet-totals. Hyperliquid open-position and unrealized PnL use HIP-4 balances and mark prices, while realized PnL and fee fields are currently zero. The caller-supplied {user_id} MUST match the authenticated principal's own id (JWT sub, or user_id for API-key auth) — mismatches are rejected with 403; this endpoint can only ever return the caller's own PnL. limit/offset paginate the merged record list; internally up to min(limit + offset, 1000) records per provider are fetched, so total/has_more in the response describe the page relative to that ceiling, not an authoritative full-history count. For API-key callers, each requested provider must additionally have its API access enabled; JWT/admin callers are exempt.

get/pnl/{user_id}

Request

  • Base URL
    https://data.kairos.trade
  • Auth
    API key in header X-Client-Id and API key in header X-Api-Key and API key in header X-Api-Secret

Path parameters

user_idstring required

Kairos internal user id. Must match the authenticated caller's own id.

Query parameters

polymarket_walletstring

Polymarket (Ethereum) wallet address.

kalshi_walletstring

Kalshi user ID (opaque internal identifier, not a wallet address).

hyperliquid_walletstring

Hyperliquid EVM address (HIP-4 positions key off this same deposit/trade address).

providerstring[]

Filter merged PnL to these provider(s). Repeatable query param.

limitinteger

Records per page.

offsetinteger

Records to skip.

Response

Merged PnL summary and records for the user.

user_idstring required
filters_appliedobject required

Echoes the effective filters used to build this response (wallets, providers, etc.).

totalinteger

Count of merged records the aggregator returned before pagination slicing, bounded by the per-provider fetch ceiling (min(limit+offset, 1000)) — not an authoritative full-history count.

has_moreboolean

True only when the aggregator definitively saw more records than this page returned.

Example response

{
  "user_id": "usr_9f3c2a1b",
  "summary": {
    "user_id": "usr_9f3c2a1b",
    "total_realized_pnl": 1875.1,
    "total_fees": 18.2,
    "total_cost_basis": 12400,
    "total_winning_positions": 25,
    "total_losing_positions": 11
  },
  "records": [
    {
      "provider": "polymarket",
      "market_id": "0xabc123condition",
      "timestamp": "2026-07-20T09:14:02+00:00",
      "realized_pnl": 24.15,
      "fees": 0.35
    }
  ],
  "total": 143
}

Changes

No recorded changes to this operation across all 1 revision of this API.