# allFills

{% hint style="info" %}
💧New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.
{% endhint %}

{% hint style="warning" %}

### ⚠️ This is an add-on endpoint - access has to be purchased separately.

{% endhint %}

### Subscribe

```
{
    "type": "subscribe",
    "subscription": {
        "type": "allFills",
        "dex": "dex_name",            // optional, filter by DEX (default: all)
        "coin": "BTC",                // optional, filter by exact coin name
        "outcomeMarkets": "exclude",  // optional, "exclude" or "only"
        "aggregateByTime": true        // optional
    }
}
```

### Filters

| Parameter         | Type    | Description                                                                                                                                                               |
| ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dex`             | string  | Filter by DEX. Use `"main"` for Hyperliquid perps, or the dex name (e.g. `"vntls"`) for dex-specific fills. Omit to receive fills from all DEXes.                         |
| `coin`            | string  | Filter by exact coin name (case-sensitive). Use the full coin string including dex prefix, e.g. `"BTC"`, `"ETH"`, `"vntls:vBTC"`, `"#90"`.                                |
| `outcomeMarkets`  | string  | Filter outcome/prediction market fills (coins starting with `#`). Set to `"exclude"` to drop them, or `"only"` to receive only outcome market fills. Omit to include all. |
| `aggregateByTime` | boolean | When `true`, fills with the same timestamp are aggregated into a single fill.                                                                                             |

{% hint style="warning" %}
Outcome markets are currently only available on testnet. The `outcomeMarkets` filter will have no effect on mainnet until outcome markets launch there.
{% endhint %}

All filters are optional and can be combined. For example, to stream only main-dex fills excluding outcome markets:

```json
{
    "type": "subscribe",
    "subscription": {
        "type": "allFills",
        "dex": "main",
        "outcomeMarkets": "exclude"
    }
}
```

### Unsubscribe

```
{
    "type": "unsubscribe",
    "subscription": {
        "type": "allFills"
    }
}
```

### Fill data format

Each fill contains an address and fill details. Fills are batched per block.

{% hint style="info" %}
**Reconnection Note:** When reconnecting with a session, replay and live events may overlap. Deduplicate using `(time, txIndex)` - skip fills where this tuple is at or before your last processed fill. See [Session Management](/readme/websocket/session-management-and-reconnection.md#deduplication) for details.
{% endhint %}

```json
{
  "type": "allFills",
  "seq": 1,
  "cursor": "500:1704067200000:3",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.50",              // price
        "sz": "1.5",                  // size
        "side": "B",                  // B=buy, A=sell
        "time": 1704067200000,        // timestamp (ms)
        "startPosition": "1.5",       // position before fill
        "dir": "Open Long",           // direction
        "closedPnl": "125.50",        // realized PnL
        "hash": "0xabc...def",        // fill hash
        "oid": 12345678,              // order ID
        "crossed": false,             // was crossed
        "fee": "2.50",                // fee amount
        "tid": 87654321,              // trade ID
        "cloid": "client-123",        // client order ID (optional)
        "builderFee": "0.10",         // builder fee (optional)
        "deployerFee": "0.05",        // deployer fee (optional, HIP-3 only)
        "priorityGas": null,          // priority gas fee in HYPE (optional)
        "feeToken": "USDC",           // fee token
        "builder": "0x..",            // builder
        "twapId": 913412,             // null if not a twap
        "txIndex": 3                  // transaction index within block
      }
    ]
  ]
}
```

### Examples

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

```javascript
const WebSocket = require('ws');

const ws = new WebSocket(`wss://api.hydromancer.xyz/ws?token=${process.env.HYDROMANCER_API_KEY}`);

ws.on('message', (data) => {
    const msg = JSON.parse(data);

    if (msg.type === 'connected') {
        // Subscribe to fills
        ws.send(JSON.stringify({
            type: 'subscribe',
            subscription: {
                type: 'allFills'
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'allFills') {
        console.log(`Received ${msg.fills.length} fills`);
    }
});
```

{% endtab %}

{% tab title="Python" %}

```python
import websocket
import json
import os

def on_message(ws, message):
    msg = json.loads(message)

    if msg['type'] == 'connected':
        ws.send(json.dumps({
            "type": "subscribe",
            "subscription": {
                "type": "allFills"
            }
        }))
    elif msg['type'] == 'ping':
        print("Received ping, sending pong")
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'allFills':
        print(f"Received {len(msg['fills'])} fills")
    elif msg['type'] == 'subscriptionUpdate':
        print(f"Subscription update: {msg}")
    elif msg['type'] == 'error':
        print(f"Error: {msg}")
    else:
        print(f"Unknown message type: {msg}")

ws = websocket.WebSocketApp(
    f"wss://api.hydromancer.xyz/ws?token={os.environ.get('HYDROMANCER_API_KEY')}",
    on_message=on_message
)
ws.run_forever()
```

{% endtab %}
{% endtabs %}

#### Error messages:

```
{
    "type": "error",
    "message": "Invalid API key"
}
```

#### Common errors

1. ```
   Connection timeout - Respond to ping messages
   ```
2. ```
   Rate limit exceeded - allFills requires add-on permission
   ```
3. ```
   Invalid API key
   ```


---

# 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/websocket/allfills.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.