KAkairos
PnL

Live per-market PnL for a (wallet, market) pair

Live "hover" PnL for a single wallet on a single market, sourced from a fast real-time pipeline — quick regardless of how far back the wallet's earliest trade goes. Returns one row per token held on the contract (e.g. YES + NO for a binary market) plus aggregate totals across those tokens. Only providers on this pipeline are supported: polymarket, opinion, predictfun; kalshi and hyperliquid are rejected with 400 and must use /pnl/{user_id}. When the underlying pipeline is disabled (e.g. while a backfill is ramping), the endpoint returns a well-formed zero/empty payload (tokens: [], all totals 0.0) instead of erroring, matching the "no data" state the frontend already renders gracefully. For API-key callers, the requested provider must additionally have its API access enabled.

get/pnl/hover/{provider_id}/{wallet}/{contract_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

provider_id'polymarket' | 'opinion' | 'predictfun' required

MV-pipeline provider id. kalshi, hyperliquid, and any other registered-but-non-MV provider are rejected with 400.

walletstring required

Wallet address (opaque string; trimmed, length-checked — not format-validated at this layer).

contract_idstring required

Market/condition (contract) id.

Response

Per-token PnL rows and aggregate totals for the wallet on this market. Returns an empty/zeroed payload (not a 404) when the underlying PnL pipeline is disabled.

provider_id'polymarket' | 'opinion' | 'predictfun' required
wallet_addressstring required
contract_idstring required
total_unrealized_pnl_usdnumber double required
total_realized_pnl_usdnumber double required
total_position_value_usdnumber double required

Example response

{
  "provider_id": "polymarket",
  "wallet_address": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "contract_id": "0xabc123condition",
  "tokens": [
    {
      "token_id": "10723948572...4",
      "outcome": "YES",
      "balance": 150,
      "avg_entry_price": 0.42,
      "cost_basis_usd": 63,
      "mark_price": 0.55,
      "position_value_usd": 82.5,
      "unrealized_pnl_usd": 19.5
    }
  ],
  "total_unrealized_pnl_usd": 19.5,
  "total_position_value_usd": 82.5
}

Changes

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