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

# userFills

Get the 2000 latest fills of a certain user. Includes twap fills.

{% hint style="info" %}
**All data is fully available from 28-07-2025. Hydromancer performed a full backfill of fills offered by the native Hyperliquid API. The result includes full historical data for most traders, except some very high-volume addresses. TWAP fills are included from 02-08-2025.**
{% endhint %}

## POST Request

<table><thead><tr><th width="161.9998779296875">Field</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"userFills"</code></td></tr><tr><td><code>user</code></td><td>string</td><td>Ethereum address (0x-prefixed, 42 characters)</td></tr><tr><td><code>builder</code></td><td>string</td><td>Filter to fills routed through this builder address (0x-prefixed, 42 characters). Omit (or send <code>null</code>) for no filtering. A malformed, empty or non-string value is a <code>400</code> rather than a silently unfiltered result (optional)</td></tr><tr><td><code>aggregateByTime</code></td><td>boolean</td><td><code>true</code> or <code>false</code> false by default (optional)</td></tr><tr><td><code>dex</code></td><td>string</td><td>i.e. "xyz" or "main_dex" or dont pass for no filtering (optional)</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>integer</td><td>Max results to return, default 2000 (optional)</td></tr></tbody></table>

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

```bash
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "userFills",
    "user": "0x0000000000000000000000000000000000000000"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'userFills',
        'user': '0x0000000000000000000000000000000000000000'
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
import axios from 'axios';

try {
    const response = await axios.post('https://api.hydromancer.xyz/info', {
        type: 'userFills',
        user: '0x0000000000000000000000000000000000000000'
    }, {
        headers: {
            'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    console.log(response.data);
} catch (error) {
    console.error('Error:', error.message);
}
```

{% endtab %}
{% endtabs %}

***

## Response Fields

| Field           | Type    | Description                                     |
| --------------- | ------- | ----------------------------------------------- |
| `coin`          | string  | Asset symbol                                    |
| `px`            | string  | Fill price                                      |
| `sz`            | string  | Fill size                                       |
| `side`          | string  | `"A"` (sell) or `"B"` (buy)                     |
| `time`          | int     | Fill timestamp (ms)                             |
| `startPosition` | string  | Position size before the fill                   |
| `dir`           | string  | Direction (e.g. `"Open Long"`, `"Close Short"`) |
| `closedPnl`     | string  | Closed PnL from this fill                       |
| `hash`          | string  | Transaction hash                                |
| `oid`           | int     | Order ID                                        |
| `crossed`       | boolean | Whether the order crossed the spread            |
| `fee`           | string  | Fee amount                                      |
| `tid`           | int     | Trade ID                                        |
| `cloid`         | string? | Client order ID (optional)                      |
| `builderFee`    | string? | Builder fee (optional)                          |
| `deployerFee`   | string? | Deployer fee (optional, HIP-3 fills only)       |
| `priorityGas`   | string? | Priority gas fee in HYPE (optional)             |
| `feeToken`      | string  | Fee token (e.g. `"USDC"`)                       |
| `builder`       | string? | Builder address (optional)                      |
| `twapId`        | int?    | TWAP order ID (null if not a TWAP fill)         |
| `txIndex`       | int     | Transaction index                               |

<details>

<summary>Response</summary>

```json
[
  {
    "coin": "BTC",
    "px": "45000.00",
    "sz": "0.5",
    "side": "B",
    "time": 1234567890123,
    "startPosition": "1.0",
    "dir": "Open Long",
    "closedPnl": "0.00",
    "hash": "0x1234567890abcdef",
    "oid": 123456,
    "crossed": false,
    "fee": "22.50",
    "tid": 789012,
    "cloid": "client-123",
    "builderFee": "0.10",
    "deployerFee": "0.05",
    "priorityGas": null,
    "feeToken": "USDC",
    "builder": "0x...",
    "twapId": 123456,
    "txIndex": 12
  }
]
```

</details>