Skip to main content
The Trader Data API is about traders: wallets, PnL, positions, history, and leaderboards derived from on-chain settlement. For realtime market data, live trades and order books, see Market Data. Requests here use the base path /trader-analytics and are sometimes referred to as the “Data API” in older material.
Bravado’s Trader 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: 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):
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 Trader Data 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.

​
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

Cashflow-based net profit after fees, computed over the full position lifecycle including trades, splits, merges, redemptions, and market resolutions. 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. 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.
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:
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.
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:
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.

​
Trader profile

The trader endpoints return comprehensive performance data for a single wallet across all markets.
The response includes: Additional per-wallet endpoints:

​
Tax statements

Bravado generates formal accounting documents for tax reporting and financial reconciliation. Each statement type covers a specific aspect of wallet activity.
Lists every closed position as a disposition row with acquisition date, disposal date, proceeds, cost basis, gain/loss, and holding-period term (SHORT for positions held ≤ 365 days, LONG for positions held > 365 days). Formatted to mirror IRS Form 8949 for US taxpayers.
Itemizes non-trade income received by the wallet: liquidity rewards, maker rebates, and referral bonuses. Each line includes the on-chain transaction hash and USDC amount.
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.
A chronological log of deposits into and withdrawals from the wallet. Distinguishes between USDC.e and pUSD flows.
Quantitative performance summary:
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.