---
title: "Builder attributed fills"
method: GET
path: "/api/public/v1/builders/{builder}/fills"
tags: ["Builder Analytics"]
---

# Builder attributed fills

`GET /api/public/v1/builders/{builder}/fills`

Individual fills attributed to the builder within a lookback window (clamped to 90d), with optional exact-coin and wallet filters. Each fill carries price, size, USD volume, realized PnL, the builder fee paid, and the order id it attributes to. Trigger-order fills (stop/TP) are not yet attributed, so this feed slightly undercounts versus ledger revenue; see the response's dataNotes.

## Path parameters

- `builder` string, required — Builder address (0x-hex)

## Query parameters

- `since` string — Lookback window like 30m, 6h, 7d (clamped to 90d)
- `coin` string — Optional exact coin filter (BTC, xyz:GOLD, @123, #10010)
- `address` string — Optional wallet filter (0x-hex)
- `limit` integer
- `offset` integer

## Response `200`

OK

- BuilderFillsBody
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `builder` string, required
  - `builderName` string — Known display name for the builder; omitted if unknown
  - `dataNotes` string, required
  - `fills` BuilderFillRow[], nullable, required
    - `builderFeeUsd` number, double, required
    - `coin` string, required
    - `marketType` 'perp' | 'spot' | 'hip4', required — '@N' coins = spot, '#N' = HIP-4 outcome, else perp (native or builder-dex)
    - `oid` integer, nullable, required — Order id the fill attributes to; null if untracked
    - `pnl` number, double, required
    - `price` number, double, required
    - `side` 'BUY' | 'SELL', required
    - `size` number, double, required
    - `tid` integer, required
    - `time` string, required — Fill time (RFC3339)
    - `volumeUsd` number, double, required
    - `wallet` string, required
  - `verified` BuilderStamp
    - `coverage` BuilderCoverage, required
      - `attributed_fees_usd` number, double, required — Join-attributed fees in the rollup window
      - `computed_at` string, required — When the rollup was computed (RFC3339)
      - `ledger_fees_usd` number, double, required — Exact ledger revenue in the rollup window
      - `ratio` number, double, required — attributed_fees / ledger_fees — the share of revenue the fill-level metrics account for
      - `window_end` string, required — End of that window (RFC3339)
      - `window_start` string, required — Start of the window the coverage rollup was computed over (RFC3339)
    - `ledger_block` integer, required — Latest block in HL's builder-fee ledger this data was verified against
    - `ledger_chain_time` string, required — Chain timestamp of that ledger entry (RFC3339)
  - `window` string, required — Echo of the requested since parameter; lookbacks beyond 90d still echo as requested while the data is clamped to 90d

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error
- `504` — Gateway Timeout

---

[API](https://skmtc.dev/coinversa/apis/coinversa-api.md) · [All operations](https://skmtc.dev/coinversa/apis/coinversa-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/coinversa/coinversa-api/revisions/77c03c427063/schema)