# userFills

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

{% hint style="info" %}
**All data fully available from 28-07-2025. We have performed a full backfill of all fills the HL native API offered, meaning that we have full historical data for most traders except for 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>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>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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hydromancer.xyz/readme/rest-api/historical-data/userfills.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.