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

# fillsByTime

Market-wide fills of the last 24 hours, by time, optionally filtered by coin.

This endpoint is for market-specific fills. For user-specific fills, use [userFillsByTime](/readme/rest-api/historical-data/userfillsbytime.md).

## 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>"fillsByTime"</code></td></tr><tr><td><code>startTime</code></td><td>number</td><td>Required unless <code>cursor</code> is given. Inclusive, milliseconds. A value older than 24 hours is moved forward to 24 hours ago.</td></tr><tr><td><code>endTime</code></td><td>number</td><td>Optional. Inclusive, milliseconds. Default: now.</td></tr><tr><td><code>cursor</code></td><td>string</td><td>Optional. Continue from a previous page. Format <code>"{time}_{txIndex}"</code>. A cursor older than 24 hours resumes at 24 hours ago.</td></tr><tr><td><code>coin</code></td><td>string</td><td>Optional. Only fills on this coin, e.g. <code>"BTC"</code>, <code>"xyz:GOLD"</code>, <code>"@107"</code>, <code>"#40080"</code>.</td></tr><tr><td><code>dex</code></td><td>string</td><td>Optional. <code>"main_dex"</code> or a HIP-3 dex such as <code>"xyz"</code>.</td></tr><tr><td><code>venue</code></td><td>string</td><td>Only fills on outcome markets deployed by this permissionless venue, e.g. <code>"skew"</code>. 2–4 ASCII letters, case-insensitive; an unknown venue returns an empty list (optional)</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)`. A range that lies entirely before the last 24 hours returns an empty list.

{% 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": "fillsByTime",
    "coin": "BTC",
    "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": "fillsByTime",
        "coin": "BTC",
        "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: "fillsByTime",
    coin: "BTC",
    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.

At the busiest hours the market produces about 300 fills a second, so a 2000-fill page covers only a few seconds. Filter by `coin` when you can.

## Response Fields

An array of fill objects, each including the `user` that made the fill. The `builder` field is the builder the fill was routed through, `null` when there was none.

<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": true,
    "fee": "0.5",
    "tid": 20001,
    "feeToken": "USDC",
    "builder": null,
    "user": "0x0000000000000000000000000000000000000001",
    "txIndex": 0
  }
]
```

</details>