> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/historical-data/builderapprovedfillsbytime.md).

# builderApprovedFillsByTime

{% hint style="info" %}
This is **not** the same as [builderFillsByTime](/readme/rest-api/historical-data/builderfillsbytime.md).

`builderFillsByTime` returns fills that were *routed through* your builder — the order carried your builder address. `builderApprovedFillsByTime` returns **every** fill a user made while they had approved your builder, including trades placed elsewhere and trades with no builder attached at all.

A user who approves your builder and then trades on another frontend appears here, and not in `builderFillsByTime`.
{% endhint %}

### Why you need this

Some fills can never carry a builder code, so they are invisible to `builderFillsByTime` no matter how the user trades:

* **Liquidations** — the fill is generated by the protocol, not by an order the user signed, so there is no builder to attach.
* **TWAP sub-fills** — the individual slices carry no builder code.

Attributing by *approval* rather than by *routing* captures both, so activity from your users stops disappearing from your numbers the moment it takes one of these paths.

{% hint style="warning" %}
The flip side: approval-based attribution reflects what a user **could** route through you, not what they did. A user who holds their own private key can trade directly or through another builder while your approval is still active, and those fills appear here. Treat this endpoint as "activity by users who approved me", not as "revenue routed through me" — for the latter, use [builderFillsByTime](/readme/rest-api/historical-data/builderfillsbytime.md).
{% endhint %}

## POST Request

<table><thead><tr><th width="180">Field</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Required. <code>"builderApprovedFillsByTime"</code></td></tr><tr><td><code>builder</code></td><td>string</td><td>Required. Builder address, 42-char hex.</td></tr><tr><td><code>startTime</code></td><td>number</td><td>Required unless <code>cursor</code> is given. Inclusive, milliseconds.</td></tr><tr><td><code>endTime</code></td><td>number</td><td>Optional. Inclusive, milliseconds.</td></tr><tr><td><code>cursor</code></td><td>string</td><td>Optional. Continue from a previous page. Format <code>"{time}_{txIndex}"</code>.</td></tr><tr><td><code>limit</code></td><td>number</td><td>Optional. Default and maximum 2000.</td></tr></tbody></table>

Results are returned oldest-first, ordered by `(time, txIndex)`.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.hydromancer.xyz/info \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "builderApprovedFillsByTime",
    "builder": "0x1924b8561eef20e70ede628a296175d358be80e5",
    "startTime": 1786000000000,
    "limit": 100
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

resp = requests.post(
    "https://api.hydromancer.xyz/info",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "builderApprovedFillsByTime",
        "builder": "0x1924b8561eef20e70ede628a296175d358be80e5",
        "startTime": 1786000000000,
        "limit": 100,
    },
)
fills = resp.json()
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const resp = await fetch("https://api.hydromancer.xyz/info", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": "YOUR_API_KEY" },
  body: JSON.stringify({
    type: "builderApprovedFillsByTime",
    builder: "0x1924b8561eef20e70ede628a296175d358be80e5",
    startTime: 1786000000000,
    limit: 100,
  }),
});
const fills = await resp.json();
```

{% endtab %}
{% endtabs %}

***

## Pagination

Take the last returned fill and build `cursor` as `"{time}_{txIndex}"`, then repeat the request with that `cursor` instead of `startTime`. A page shorter than `limit` means you have reached the end of the range.

## Semantics

An approval applies from the block it lands in, and a revocation likewise. A fill that happened while an approval was active stays attributed permanently — revoking does not remove past fills from this endpoint.

## Response Fields

An array of fill objects, each including the `user` that made the fill — the same shape as [builderFillsByTime](/readme/rest-api/historical-data/builderfillsbytime.md), plus a `builder` field.

The `builder` field is the builder the fill was **routed through**, which is a separate question from why the fill is in this response. It is usually `null`: liquidations and TWAP sub-fills carry no builder code, and a user who approved you can trade through anyone. `builderFillsByTime` does not return this field, because there every fill is routed through the builder you asked for.

<details>

<summary>Response</summary>

```json
[
  {
    "coin": "BTC",
    "px": "50000.0",
    "sz": "1.5",
    "side": "B",
    "time": 1786000001000,
    "startPosition": "0.0",
    "dir": "Open Long",
    "closedPnl": "0.0",
    "hash": "0x...",
    "oid": 12345,
    "crossed": false,
    "fee": "0.5",
    "tid": 20001,
    "feeToken": "USDC",
    "builder": null,
    "user": "0x0000000000000000000000000000000000000001",
    "txIndex": 0
  }
]
```

</details>