Reporting API

The builder dashboard (Settings → Builders → Builder Dashboard in the app) and these endpoints report your builder's attributed activity.

Authentication

Reporting endpoints use the fee account's API key. The builder is derived from the key, so don't pass builder_id.

Use a read-only API key for dashboards and accounting jobs. Read-only keys can call every reporting endpoint, including the CSV export, but can't trade, withdraw, transfer or change your builder.

Time windows

Pick one of:

• period: 24h, 7d, 30d or 90d. Not available on /builder/fills.

• start_time and end_time: Unix nanoseconds. A custom range can be up to 180 days.

All daily series are in UTC.

Units

• volume, notional and fees are USDC strings.

• For options, volume and notional are contracts × index price, the same basis as the fee.

• Timestamps are Unix nanoseconds, as strings.

Pagination

/builder/users, /builder/fills and /builder/markets return count: the total number of rows in the window, as a string. Page with limit and offset:

• limit: default 50, maximum 200.

• offset: rows to skip.

• Total pages = ceil(count / limit).

/builder/users and /builder/fills also support cursor pagination: pass the previous response's next_cursor as cursor. Use either cursor or offset, not both (BUILDER_CURSOR_WITH_OFFSET). Offset pages don't return next_cursor.

/builder/markets returns every market when neither limit nor offset is sent.

GET /builder/stats

Totals for the window, the previous window of the same length (for comparisons), a per-market summary and a daily series.

curl -sS "https://api-testnet.aevo.xyz/builder/stats?period=30d" \
  -H "AEVO-KEY: $FEE_ACCOUNT_KEY" -H "AEVO-SECRET: $FEE_ACCOUNT_SECRET"

Fields: builder_id, name, fee_account, status, period, start_time, end_time, volume, fees, fills, unique_traders, active_traders, new_traders, returning_traders, maker_volume, taker_volume, previous (volume, fees, unique_traders, fills), markets[], series[] (timestamp, volume, fees).

• New traders made their first-ever fill with your builder in this window.

• Returning traders had filled with your builder before this window.

GET /builder/markets

Per-instrument totals, sorted by volume.

curl -sS "https://api-testnet.aevo.xyz/builder/markets?period=30d&limit=25&offset=0" \
  -H "AEVO-KEY: $FEE_ACCOUNT_KEY" -H "AEVO-SECRET: $FEE_ACCOUNT_SECRET"

{
  "markets": [
    {"instrument": "ETH-PERP", "volume": "2715.83", "fees": "0.81", "fills": 3, "maker_volume": "0", "taker_volume": "2715.83"}
  ],
  "count": "1"
}

GET /builder/users

Traders who filled with your builder, sorted by volume.

curl -sS "https://api-testnet.aevo.xyz/builder/users?period=7d&limit=25&offset=0" \
  -H "AEVO-KEY: $FEE_ACCOUNT_KEY" -H "AEVO-SECRET: $FEE_ACCOUNT_SECRET"

Each user has account, volume, fees, fills, first_fill_timestamp and last_fill_timestamp.

GET /builder/fills

Individual attributed fills, newest first. Optional instrument filter (for example ETH-PERP).

curl -sS "https://api-testnet.aevo.xyz/builder/fills?start_time=1790000000000000000&end_time=1790600000000000000&limit=50&offset=0" \
  -H "AEVO-KEY: $FEE_ACCOUNT_KEY" -H "AEVO-SECRET: $FEE_ACCOUNT_SECRET"

Each fill has trade_id, order_id, account, instrument, side, price, amount, notional, builder_fee_rate, builder_fee, is_maker and timestamp.

CSV export

Add format=csv to /builder/fills. It takes the same start_time, end_time and instrument filters.

curl -sS "https://api-testnet.aevo.xyz/builder/fills?format=csv&start_time=1790000000000000000&end_time=1790600000000000000" \
  -H "AEVO-KEY: $FEE_ACCOUNT_KEY" -H "AEVO-SECRET: $FEE_ACCOUNT_SECRET" \
  -o fills.csv

Columns:

timestamp,trade_id,order_id,account,instrument,side,price,quantity,notional,builder_fee_rate,builder_fee_amount,is_maker

One export is capped at 50,000 rows. A larger range returns CSV_RANGE_TOO_LARGE; split it into shorter windows.

GET /builder-config

The current protocol limits. Public, no authentication.

curl -sS "https://api-testnet.aevo.xyz/builder-config"

{"max_fee_rate_perps": "0.0005", "min_create_balance": "100", "max_fee_rate_options": "0.0003", "option_premium_cap": "0.05"}

Field	Meaning
max_fee_rate_perps	Protocol cap on perpetual builder fees and on approval max_fee_rate: 0.0005 (5 bps).
max_fee_rate_options	Protocol cap on option builder fee rates: 0.0003 (3 bps of index notional).
option_premium_cap	Option builder fee cap, as a fraction of premium: 0.05 (5%).
min_create_balance	Minimum USDC balance to register a builder.

A null value means that feature is turned off. Builder orders or registration that depend on it are rejected.

Errors

Code	Meaning
BUILDER_NOT_FOUND	The API key's account is not a builder fee account.
BUILDER_INVALID_ID	builder_id was passed. Reporting derives the builder from the key.
BUILDER_CURSOR_WITH_OFFSET	Both cursor and offset were sent.
CSV_RANGE_TOO_LARGE	The export window has more than 50,000 fills.