Outcome Builder Analytics
Outcome Builder Analytics API
API reference for the outcome builder analytics endpoints. These expose trading volume, fees, and activity for builders operating on outcome (prediction) markets — both builder-level totals/time-series and a per-category breakdown (crypto, sports, economics, politics, …).
Base URL
https://api.hydromancer.xyzAuthentication
Send your API key as a Bearer token on every request:
Authorization: Bearer <your-api-key>Your key must be authorized for these endpoints — contact us to enable access.
Conventions
builder— a builder address. Usebuilder=nullfor fills not attributed to any builder.category— the market category. Categories are resolved at read time from the market's registration / settlement metadata, so newly tagged markets (and any re-tagging) are reflected automatically. Markets with no category tag resolve tocrypto(the default). New categories such aspoliticsappear automatically once their markets are tagged upstream — no API change.Volume counts matched trades only (
Buy/Sell). Settlement and other position-lifecycle actions are not counted as volume, fees, or users.Decimal values (prices, sizes, volumes, fees) are returned as strings to preserve precision, e.g.
"1234.56". Trade times are Unix milliseconds; hours and dates are UTC.Per-category series are sparse: a
(period, category)row appears only if it had activity. A category with no fills in a period is simply absent.
Builder-level analytics
1. All-time builder stats
All-time outcome trading totals for one builder.
builderFee
Total builder fees collected
volume
All-time traded volume (notional)
volumeShare
Share of total outcome market volume (0–1)
fills
Number of trades
uniqueUsers
Distinct users who traded
2. Daily volume
Daily volume time-series. With no builder, returns the top builders by volume; with a builder, returns just that builder.
startDate
30 days ago
Inclusive start, YYYY-MM-DD
endDate
today (UTC)
Inclusive end, YYYY-MM-DD
builder
—
Restrict to a single builder (or null)
limitBuilders
20
Number of top builders (max 100)
format
packed
rows for one row per builder/day, packed for chart-ready arrays
Date range cannot exceed 365 days.
Packed (default — aligned arrays for charting):
In series, each metric is indexed [builder][day], aligned to builders[] and dates[].
Rows (format=rows):
3. Hourly stats
Hourly time-series for one builder.
builder
— (required)
Builder address, or null
hours
72
Lookback window in hours (max 168)
format
packed
rows or packed
Each array in series is aligned to hours[]. Hours are UTC, formatted YYYY-MM-DD HH:00:00.
activeUsers
Users who traded in the hour
newUsers
Users trading with this builder for the first time
biggestNotionalFill
Largest single trade (notional) in the hour
Rows (format=rows):
4. Recent fills
The 100 most recent trades for one builder, newest first. Requires a builder address (the unattributed null bucket is not available for this endpoint).
builder
— (required)
Builder address
venue
— (all)
Only trades on outcome markets deployed by this permissionless venue, e.g. out. 2–4 ASCII letters, case-insensitive; an unknown venue returns no fills
coin
Outcome market symbol
px / sz
Trade price / size
side
B (buy) or A (sell)
dir
Buy or Sell
time
Trade time (Unix ms)
fee / builderFee
Total fee / builder portion
user
Trader address
venue
HIP-4 venue of the outcome market (e.g. "out"); omitted for validator-deployed outcomes
Per-category analytics
These endpoints break a builder's activity down by market category — crypto, sports, economics, politics, … — for volume, fees, fills, and unique traders. 1 outcome = 1 market.
5. All-time category breakdown
All-time per-category totals for one builder, ordered by volume (descending).
builder
— (required)
Builder address, or null
overall is the builder's totals across all categories (omitted if the builder has no activity). Each categories[] entry carries the same metrics scoped to that category:
category
Market category (crypto for untagged markets)
builderFee
Builder fees collected in this category
volume
Traded volume (notional) in this category
volumeShare
Category volume ÷ the builder's total volume (0–1)
fills
Number of trades in this category
fillsShare
Category fills ÷ the builder's total fills (0–1)
uniqueUsers
Distinct traders in this category
uniqueUsersShare
Category distinct traders ÷ the builder's total distinct traders
tradingDays
Distinct UTC dates on which the builder traded (in this category)
uniqueMarkets
Distinct markets traded (1 outcome = 1 market)
maxMarketsDay
The date with the most distinct markets traded, and that count ({ date, markets })
uniqueMarketsis additive across categories (each market belongs to one category), buttradingDaysandmaxMarketsDayare not —overallrecomputes them over the builder's whole activity (e.g. one day may be the peak for several categories at once).
volumeShareandfillsSharepartition the builder's totals and sum to 1 across categories.uniqueUsersShareuses the builder's actual distinct trader count as the denominator (not a sum of per-category counts), so it is the fraction of the builder's traders who traded each category — these can sum to more than 1, because a trader active in two categories is counted in both.
6. Daily category series
Daily per-category time-series for one builder.
builder
— (required)
Builder address, or null
startDate
30 days ago
Inclusive start, YYYY-MM-DD
endDate
today (UTC)
Inclusive end, YYYY-MM-DD
Date range cannot exceed 365 days.
Rows are ordered by date ascending, then category.
7. Hourly category series
Hourly per-category time-series for one builder over a rolling window.
builder
— (required)
Builder address, or null
hours
72
Lookback window in hours (max 168)
Rows are ordered by hour ascending, then category. Hours are UTC, formatted YYYY-MM-DD HH:00:00.
Daily / hourly category row fields
The daily and hourly category rows carry the same metric set (only the period key differs — date vs hour):
volume
Traded volume (notional) in the period × category
fills
Number of trades
uniqueUsers
Distinct traders
builderFee
Builder fees collected ("0.00" for the null builder bucket)
biggestNotionalFill
Largest single trade (notional) in the period × category
8. Recent fills by category
The 100 most recent trades for one builder, newest first, each labeled with its category. Pass category to return only that category's fills (including category=crypto for untagged markets); omit it to return all categories.
builder
— (required)
Builder address, or null for unattributed fills
category
— (all)
Restrict to a single category, e.g. sports
venue
— (all)
Only trades on outcome markets deployed by this permissionless venue, e.g. out. 2–4 ASCII letters, case-insensitive; an unknown venue returns no fills
Each fill is the standard fill object (same shape as the other fills endpoints) with an added category. The example below shows the commonly used fields; the full object also includes startPosition, closedPnl, hash, oid, crossed, tid, cloid, deployerFee, priorityGas, twapId, txIndex, liquidation, builder, and venue (the HIP-4 venue, omitted for validator-deployed outcomes).
coin
Outcome market symbol (#<assetId>)
px / sz
Trade price / size
side
B (buy) or A (sell)
dir
Buy or Sell
time
Trade time (Unix ms)
fee / builderFee
Total fee / builder portion
user
Trader address
category
Resolved category for the fill's market (crypto if untagged)
When category is omitted, the top-level category field is null and each fill is labeled with its own category.
9. Profitability
Realised profit and loss over completed outcome trades — a position opened and closed. The outcome counterpart of /dashboard/builder-profitability, and the two are separate lineages: a trade appears in exactly one of them, so read them side by side rather than adding them together. Every response carries scope: "outcome" so which one you are holding is never ambiguous.
Parameters
builder
yes
Builder address, or null for unattributed activity — the largest single bucket on outcome markets
window
no
today, 1d, 7d, 30d, 90d, all. Default 7d. The complete-day presets end yesterday
venue
no
Scope to one outcome venue. Omit for every venue. none selects outcomes with no venue — those registered before permissionless deployment, which are the majority rather than an edge case
Notes
fundingPnl is always "0.00". Outcome exposure is a token holding — always long, unlevered, and accruing no funding — so the field exists only to keep the shape identical to the perp endpoint.
winRate and profitableTraderShare answer different questions. winRate is winning trades over all trades, so your most active accounts dominate it. profitableTraderShare is the share of traders whose summed PnL over the window is positive. Both are ratios, not percentages: multiply by 100 to display. A trade that breaks exactly even counts as a loss.
grossPnl is before fees; netPnl is after. holdTime reports how long positions stayed open, as a mean plus p10/p50/p95 in seconds — the median is typically far below the mean, because a few long-held positions pull the average up. It is null when the window contains no completed trades.
An empty window and an unknown builder are different answers. A builder that has routed outcome fills at some point, but closed no trades inside the window, is a 200 with every count and amount at zero and holdTime null. A builder that has never routed an outcome fill at all is a 404. Section 1 (/dashboard/outcome-builder-stats) splits the same way; the series and fills routes in this family return an empty 200 in both cases.
Errors
400
Missing or invalid parameter
401
Missing or invalid API key
403
Key not authorized for this endpoint
404
No data for the requested builder
429
Rate limit exceeded — slow down and retry
Errors are returned as JSON:
Last updated