Data API: Trader Analytics and Combos Data

The Data API is about traders and settlements: wallets, PnL, positions, history and leaderboards derived from on-chain settlement (/trader-analytics/*), and market-wide Polymarket Combos data (/v2/data/combos/*). One credential with analytics.read covers both. For realtime market data, live trades and order books, see Market Data. Older material calls this product the “Trader Data API” or “Analytics API”; it is the same endpoint.

Bravado’s Data API combines on-chain settlement history, FIFO cost-basis accounting and current market prices to serve wallet performance. You can query performance data for your own wallet or any public address, useful for leaderboard analysis, due diligence on traders you want to copy, and year-end tax reporting. The base URL for all analytics endpoints is https://partner-api.bravadotrade.com/trader-analytics.

Authentication

Sign Data API requests with your partner API key, using the same HMAC scheme as the Trade API. Send these headers on every call:

Header	Value
`X-BRAVADO-API-KEY`	Your public key
`X-BRAVADO-TIMESTAMP`	Unix milliseconds, within ±30s of server time
`X-BRAVADO-SIGNATURE`	Lowercase-hex HMAC-SHA256 of `timestamp\nMETHOD\ncanonical_path\nsha256_hex(body)`, keyed by your secret. The Data API is GET-only, so the body hash is always the empty-body constant `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`.

Your key needs the analytics.read scope (select the Data API product when creating the key in the Console), and your partner account needs the request’s venue enabled — see Venues below. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a 429 includes Retry-After.

No credentials needed for GET /healthz and the free tax-report surface: /traders/{address}/tax-report, /traders/{address}/tax-report/8949, and /traders/{address}/event-graph are public.

Deprecated: Authorization: Bearer <token> with a Bravado-issued static token still works during the key-migration window and will be removed once all partners are migrated. New integrations must sign with partner keys.

Venues

Every Data API request belongs to exactly one venue, and your partner account must have that venue enabled (403 VENUE_NOT_ENABLED otherwise):

Venue	Paths	Notes
Polymarket (default)	everything under `/trader-analytics/`	Full surface, including tax statements. See Data API on Polymarket.
Predict.fun	`/trader-analytics/predict/*`	Core analytics (leaderboards, profiles, PnL, positions, trades, categories); realized PnL is already net of fees on this venue. See Data API on Predict.fun.

All numeric fields in Data API responses, including PnL, volume, and prices, are returned as JSON strings. Always parse them as BigDecimal (or your language’s equivalent arbitrary-precision type). Parsing as a float risks silent rounding errors on large values.

Accounting coverage

Bravado reconstructs wallet cost basis and realized PnL using a share-level FIFO engine. Open positions are marked to market. You can read public wallet analytics without a funded trading account. On Polymarket, processed wallets can also return PMWAS statements, R1 dispositions, performance metrics and R8 reconciliation certificates. A certificate reports internal accounting checks; it is not an independent audit opinion. Full statements depend on wallet processing and can return 503 with available: false while unavailable. Tax reports disclose whether they use PMWAS statements or a serving-engine FIFO fallback. The fallback does not provide the same lot lineage and cash-flow coverage as a full statement. Entity rollups aggregate mapped member wallets; they do not infer arbitrary wallet clusters. Predict.fun supports core wallet analytics. PMWAS statements, tax reports, reconciliation and entity rollups are Polymarket-only today.

Data-only access and onboarding

You can use the Data API with an analytics.read key and no trading permissions. Bravado can arrange evaluation access, venue enablement and the appropriate request allowance directly. Confirm commercial use and redistribution terms during onboarding. Create an account in the Bravado Console, then open Endpoints to configure your product and API keys to manage credentials. Contact the team if your organisation needs additional venue or product access. See API credits for published request costs; exact quotas and historical coverage depend on the product and dataset.

Kalshi market data

With analytics.read and an explicit Kalshi data grant, a Data credential can read native Kalshi market data: current order books, catalogue metadata, public trades and native candles. It can also query captured Kalshi order-book history under /market-data/v1, with an explicit Kalshi read-only data grant. This is a separate, limited captured dataset, not Kalshi trader analytics or a live WebSocket. Discover the available generations and capture intervals before integrating.

Trader intelligence

Beyond leaderboards, use wallet profiles, open and closed positions, trade history and category performance. Polymarket top holders are available through GET /clob-proxy/holders?market={conditionId}; this proxies venue holder data and is not a smart-money score. For similar-wallet discovery, clusters, per-market intelligence or additional style labels, contact us to scope the analysis. These are custom development requests rather than existing general-purpose endpoints.

Key metrics

Realized PnL

FIFO-realized net profit over the full position lifecycle including trades, splits, merges and market resolutions. Fees are already inside proceeds and cost basis (the figure is never reduced by fees a second time). A gain is realized when the market resolves or the position is sold; a later redemption only collects the cash. Splits and merges are correctly excluded from volume inflation.

Unrealized PnL

Open position shares marked to the latest CLOB midpoint prices. Updates in real time as market prices move.

Volume

USDC notional traded, filtered to exclude CTF split, merge, and redeem transactions. This gives you true trading volume, not inflated on-chain throughput.

Win rate

Closed-position stats at the outcome level, a position is a “win” if it closed with positive realized PnL. Calculated independently of position size.

The `window` parameter

Analytics endpoints that document window accept a ?window= query parameter that controls the rolling lookback period for returned metrics.

Value	Description
`1h`	Last 1 hour
`4h`	Last 4 hours
`24h`	Last 24 hours (default for leaderboard endpoints)
`7d`	Last 7 days
`30d`	Last 30 days
`90d`	Last 90 days
`365d`	Last 365 days
`all`	All-time

What the window affects: PnL, volume, and trade counts use daily or hourly rollups that respect the window boundary. Windowed queries are fast because they aggregate pre-computed buckets. What the window does not affect: Fee totals, streak metadata, and drawdown statistics are always computed all-time regardless of the window value. This is by design, these metrics are meaningless when truncated to a short window.

GET https://partner-api.bravadotrade.com/trader-analytics/traders/0x3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b?window=30d

Wallet addresses are matched case-insensitively, and the 0x prefix is optional — a bare 40-hex address, as returned in leaderboard rows, is accepted and treated identically.

Leaderboards

Bravado maintains two live leaderboards ranked by the window you specify:

PnL leaderboard
Volume leaderboard

Returns traders ranked over the selected window. The ranking runs in the database over the complete candidate set on the served column, with a deterministic tie-break, so pages never overlap. Default ranking is total_pnl for window=all and realized_pnl (what was realized inside the window) for windowed boards.

GET https://partner-api.bravadotrade.com/trader-analytics/leaderboard?window=24h

Parameter	Description
`sort`	Ranking column: `total_pnl`, `realized_pnl`, `unrealized_pnl`, `volume_usdc`, `trades`, `active_positions`, `open_position_value`; `window=all` only: `win_rate`, `wins`, `losses`, `total_positions`.
`order`	`desc` (default) or `asc` — `sort=realized_pnl&order=asc` lists the worst performers first.
`is_mm_bot`	`true` keeps only wallets flagged `is_mm_bot`, `false` drops them (same gate as the row flag).
`limit` / `offset`	Page size (max 500) and offset.

The response carries total (size of the candidate set after min_trades and the bot filter; null only if it could not be counted), has_more (offset + rows < total), and echoes the resolved sort and order.It also carries a totals object — a board-wide aggregate over that same candidate set, for a stat-strip header rather than for paging:

"totals": {
  "traders": 2559852,
  "volume_usdc": "18234567890.123000",
  "trades": 9812340,
  "realized_pnl": "1234567.890000",
  "unrealized_pnl": "-45678.120000",
  "total_pnl": "1188889.770000",
  "profitable_traders": 13102,
  "unprofitable_traders": 11343
}

traders always equals total. profitable_traders/unprofitable_traders classify by the sign of total_pnl (realized + current open mark-to-market) — the one figure defined the same way on every window. totals is null only if it could not be computed; it never adds latency, since it’s computed alongside the ranked page rather than after it.

Returns traders ranked by USDC trading volume over the selected window. CTF infrastructure transactions are excluded. Ranked in the database over the complete candidate set, with the same deterministic wallet tie-break as the PnL leaderboard.

GET https://partner-api.bravadotrade.com/trader-analytics/leaderboard/volume?window=7d

Parameter	Description
`sort`	Ranking column: `volume_usdc` (default), `trades`, `volume_shares`. This board carries no PnL fields, so PnL sort keys are rejected here.
`order`	`desc` (default) or `asc` — pass `order=asc` to read the bottom of the board directly (e.g. the least-active traders), without walking pages backward from an unknown end.
`min_trades`	Minimum trade count (default `0`).
`limit` / `offset`	Page size (max 500) and offset.

The response carries total (size of the candidate set after min_trades; null only if it could not be counted), has_more, and echoes the resolved sort and order — same paging contract as the PnL leaderboard. It also carries a totals object scoped to the same candidate set:

"totals": {
  "traders": 3194081,
  "volume_usdc": "90018699131.670208",
  "volume_shares": "216739307194.687436",
  "trades": 2172472283
}

This board’s default min_trades is 0 (any wallet with at least one real fill), while the PnL leaderboard’s default is 5 — that is the entire reason the volume board’s candidate set is larger. Pass a matching min_trades to both endpoints to compare the same population; they are not different populations of traders.

Trader profile

The trader endpoints return comprehensive performance data for a single wallet across all markets.

GET https://partner-api.bravadotrade.com/trader-analytics/traders/{address}?window=30d

The response includes:

Field	Description
`realized_pnl`	Net closed-position profit; fees are inside the figure (basis `net`), not subtracted again
`unrealized_pnl`	Mark-to-market open position value minus cost
`volume`	USDC notional traded in the window
`trade_count`	Number of individual fills
`win_rate`	Fraction of closed positions that were profitable
`open_positions`	Count of currently active positions
`current_streak`	Consecutive winning (positive) or losing (negative) closed positions
`max_drawdown`	Largest peak-to-trough equity decline, all-time
`biggest_win`	Highest single-position realized PnL, all-time
`biggest_loss`	Largest single-position realized loss, all-time

Additional per-wallet endpoints:

Endpoint	Description
`GET /traders/{address}/pnl`	PnL breakdown over the selected window
`GET /traders/{address}/positions`	All positions (open and closed) for the wallet
`GET /traders/{address}/trades`	Individual trade history
`GET /traders/{address}/categories`	Performance grouped by market category
`GET /traders/{address}/metrics`	Aggregate performance metrics
`GET /traders/{address}/statements`	Full accounting statement for the wallet
`GET /traders/{address}/reconciliation`	On-chain data reconciliation report
`GET /traders/{address}/tax-report`	Downloadable tax report for the wallet

Combos data

The same Data API credential also serves market-wide data on Polymarket Combos (multi-leg parlays): every combo settlement on the venue, each combo’s legs mapped to its underlying markets, aggregate stats and a combo trader leaderboard, plus a live settlement stream. These routes live under /v2/data/combos on the same host and cost 1 credit per request like the rest of the product.

Endpoint	Description
`GET /v2/data/combos`	Combos with at least one settlement, with legs and activity
`GET /v2/data/combos/trades`	Every combo fill, newest first
`GET /v2/data/combos/{combo_id}`	One combo, its underlying markets and recent settlements
`GET /v2/data/combos/stats`	Volume, trades, traders, resolutions and top leg markets over a window
`GET /v2/data/combos/leaderboard`	Wallets ranked by combo volume, PnL, trade count or win rate
`WSS /stream/polymarket/partner/combos`	Live combo settlements (Market Data key)

See the Combos Data API reference. To quote and buy combos, use the Combos API instead.

Perps data

The same Data API credential also serves read-only market data for Polymarket Perps (perpetual futures): funding history and cross-venue funding comparison, open-interest and mark-versus-index basis rollups, long/short account skew and detected liquidations. These routes live under /perps on the same host and cost 1 credit per successful response like the rest of the product. This is market data, not execution — to trade perps, use the Polymarket Perps Trade API instead.

Endpoint	Description
`GET /perps/funding/history`	Per-interval funding observations for one instrument, with hourly-normalised and annualised forms
`GET /perps/funding/compare`	One symbol on the Polymarket perp against Binance, Bybit and Hyperliquid, interval-normalised
`GET /perps/oi/history`	OHLC of open interest in contracts, plus closing USD notional per bucket
`GET /perps/basis`	OHLC of mark, index and basis (bps) per bucket
`GET /perps/skew`	Long/short account counts, contract sums and concentration over the observed account universe
`GET /perps/liquidations`	Detected liquidations, each with its evidence class

See the Perps Data overview.

UMA resolution

The same Data API credential also serves UMA resolution data — how Polymarket markets settle through UMA’s Optimistic Oracle (proposals, disputes and final settlement outcomes). These routes live under /uma on the same host and cost 1 credit per successful response like the rest of the product. They come in two surfaces:

Endpoint	Description
`GET /uma/question`, `/uma/market`, `/uma/recent`	The live window — lowest-latency reads of what is resolving right now (about 7 days settled, 14 days open)
`GET /uma/history/question`, `/uma/history/market`, `/uma/history/recent`	All history from `pm_uma_oracle_events`, with `from` / `to`, cursor paging and `resolution_source` provenance

The live push stream (/uma/ws) is a separate Market Data surface on the stream.read credential. See the UMA overview.

Tax statements

Bravado generates formal accounting documents for tax reporting and financial reconciliation. Each statement type covers a specific aspect of wallet activity.

Dispositions (Form 8949-style)

Lists every disposition as a row with disposal date, proceeds, cost basis and gain/loss, formatted to mirror IRS Form 8949 for US taxpayers. For wallets in the PMWAS batch each row also carries the acquisition date and the holding-period term (SHORT for positions held ≤ 365 days, LONG for positions held > 365 days). For every other wallet the trading engine records no acquisition date per lot, so date_acquired and term are UNKNOWN (never guessed) and the response says so under disclosure; a combo row whose acquisition date is not recorded is UNKNOWN too. A redemption of a position that already resolved is a cash event, not a disposition: it is reported per year as redemption_cash. The row count is total_rows (X-Total-Rows on the CSV); pages never stand for the whole period.

Income

Itemizes non-trade income received by the wallet: liquidity rewards, maker rebates and other program rewards, with count and fair-market value per kind. For wallets in the PMWAS batch this is attributed to tax years; for every other wallet only the all-time total (income_all_time) is available, per-year income is null (listed in not_computed) and is not included in net_taxable_uusdc.

Open positions

A point-in-time snapshot of all open positions, share balances, cost bases, mark prices, and unrealized PnL. Useful for year-end Schedule D footnotes.

Capital flows

A chronological log of deposits into and withdrawals from the wallet. Distinguishes between USDC.e and pUSD flows.

Performance metrics

Quantitative performance summary:

Metric	Description
TWR	Time-weighted return, eliminates the effect of capital inflows/outflows
MWR	Money-weighted return (IRR), accounts for the timing and size of capital flows
NAV	Net asset value at the statement date
ROI	Simple return on invested capital
Win rate	Closed-position win percentage

Reconciliation certificate

A machine-readable report of internal reconciliation checks for the processed statement. Read the individual check results and coverage disclosures; the certificate is not a guarantee of complete source history or an independent audit.

GET https://partner-api.bravadotrade.com/trader-analytics/traders/{address}/tax-report?year=2025

Data API

Kalshi market data

Trader analytics

Polymarket analytics

Combos Data

Perps data

UMA resolution

By venue

Guides

Data API: Trader Analytics and Combos Data

Authentication

Venues

Accounting coverage

Data-only access and onboarding

Kalshi market data

Trader intelligence

Key metrics

Realized PnL

Unrealized PnL

Volume

Win rate

The `window` parameter

Leaderboards

Trader profile

Combos data

Perps data

UMA resolution

Tax statements

​Authentication

​Venues

​Accounting coverage

​Data-only access and onboarding

​Kalshi market data

​Trader intelligence

​Key metrics

Realized PnL

Unrealized PnL

Volume

Win rate

​The window parameter

​Leaderboards

​Trader profile

​Combos data

​Perps data

​UMA resolution

​Tax statements

Authentication

Venues

Accounting coverage

Data-only access and onboarding

Kalshi market data

Trader intelligence

Key metrics

The `window` parameter

Leaderboards

Trader profile

Combos data

Perps data

UMA resolution

Tax statements