> 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/builderapprovedfundingbytime.md).

# builderApprovedFundingByTime

Hourly funding payments made by users who had an active builder-fee approval for your builder address.

The funding counterpart of [builderApprovedFillsByTime](/readme/rest-api/historical-data/builderapprovedfillsbytime.md): every hourly funding payment made by a user while they had approved your builder, across all of those users at once. Each row is exactly a [userFunding](/readme/rest-api/historical-data/userfunding.md) row with the paying `user` added.

{% hint style="info" %}
**Attribution is by approval, not by routing.** A funding payment has no builder code and no order behind it — it is charged by the protocol once an hour on every open position — so it can only be attributed by asking who the user had approved at that block. A user who approved your builder and then opened a position through another frontend still appears here.
{% endhint %}

### Why you need this

Funding is often the largest recurring cost or income for a perp position, and it is invisible to every routing-based endpoint. If you report net PnL for the users who approved you, fills alone overstate it; this endpoint supplies the missing leg without you having to poll `userFunding` per user.

## 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>"builderApprovedFundingByTime"</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}_{user}_{coin}"</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, user, coin)`.

{% 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": "builderApprovedFundingByTime",
    "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": "builderApprovedFundingByTime",
        "builder": "0x1924b8561eef20e70ede628a296175d358be80e5",
        "startTime": 1786000000000,
        "limit": 100,
    },
)
funding = 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: "builderApprovedFundingByTime",
    builder: "0x1924b8561eef20e70ede628a296175d358be80e5",
    startTime: 1786000000000,
    limit: 100,
  }),
});
const funding = await resp.json();
```

{% endtab %}
{% endtabs %}

***

## Pagination

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

Funding is charged once an hour, and every payment of that hour carries the same `time`, so a page boundary usually falls **inside** an hour. That is why the cursor carries `user` and `coin` rather than a transaction index: it resumes exactly after the last row you saw without repeating or skipping the rest of the hour.

## Semantics

* **Hourly rows.** One row per `(user, coin)` position per funding hour, with the block timestamp of the funding event as `time`. There are no rows between funding hours.
* **Attributed at the block.** An approval applies from the block it lands in, and a revocation likewise. A payment that happened while an approval was active stays attributed permanently — revoking does not remove past rows from this endpoint.
* **Same row as `userFunding`.** `time`, `hash` and `delta` are byte-for-byte what [userFunding](/readme/rest-api/historical-data/userfunding.md) returns for that user; only `user` is added. `hash` is always the zero hash, as it is there, because funding is a protocol event with no transaction.

## Response Fields

| Field               | Type   | Description                                                                               |
| ------------------- | ------ | ----------------------------------------------------------------------------------------- |
| `user`              | string | The user who paid or received the funding, and who had approved your builder at the time. |
| `time`              | int    | Funding block timestamp (ms).                                                             |
| `hash`              | string | Always the zero hash.                                                                     |
| `delta`             | object | Funding payment details, identical to `userFunding`.                                      |
| `delta.type`        | string | Always `"funding"`.                                                                       |
| `delta.coin`        | string | Asset symbol.                                                                             |
| `delta.usdc`        | string | USDC amount of the funding payment (negative when paid).                                  |
| `delta.szi`         | string | Position size at the time of funding.                                                     |
| `delta.fundingRate` | string | Funding rate applied.                                                                     |

<details>

<summary>Response</summary>

```json
[
  {
    "user": "0x0000000000000000000000000000000000000001",
    "time": 1786000000066,
    "hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "delta": {
      "type": "funding",
      "coin": "BTC",
      "usdc": "0.014419",
      "szi": "-0.01",
      "fundingRate": "0.0000125"
    }
  }
]
```

</details>