> For the complete documentation index, see [llms.txt](https://www.aevo.xyz/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.aevo.xyz/docs/api-reference/builder-codes/reporting-api.md).

# 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`.

{% hint style="info" %}
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.
{% endhint %}

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

```bash
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.

```bash
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"
```

```json
{
  "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.

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

```bash
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.

```bash
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.

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

```json
{"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.                        |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.aevo.xyz/docs/api-reference/builder-codes/reporting-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.