Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.xyz

Authentication

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. Use builder=null for 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 to crypto (the default). New categories such as politics appear 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.

Field
Description

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.

Param
Default
Description

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.

Param
Default
Description

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.

Field
Description

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).

Field
Description

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

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).

Param
Default
Description

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:

Field
Description

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 })

uniqueMarkets is additive across categories (each market belongs to one category), but tradingDays and maxMarketsDay are not — overall recomputes them over the builder's whole activity (e.g. one day may be the peak for several categories at once).

volumeShare and fillsShare partition the builder's totals and sum to 1 across categories. uniqueUsersShare uses 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.

Param
Default
Description

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.

Param
Default
Description

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):

Field
Description

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.

Param
Default
Description

builder

— (required)

Builder address, or null for unattributed fills

category

— (all)

Restrict to a single category, e.g. sports

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, and builder.

Field
Description

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.

Errors

Status
Meaning

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