GetFills - Get Fill Data
Retrieve fills at a specific position from Hyperliquid L1 Gateway via gRPC. Get order execution data for analysis and reconciliation.
Hyperliquid RPC endpoint: endpoint URLs, plans and pricing.
Retrieve fills at a specific position from the Hyperliquid L1 Gateway.
Full Code Examples
Clone our gRPC Code Examples Repository for complete, runnable implementations in Go, Python, and Node.js.
When to Use This Method
GetFills is essential for:
- Trade Reconciliation - Verify fills at a specific point in time
- Historical Analysis - Retrieve fill data for backtesting or reporting
- Auditing - Verify trade executions at specific blocks
- Liquidation Detection - Identify forced position closures at specific blocks
- Debugging - Investigate specific fills during development
Method signature
rpc GetFills(GetRequest) returns (Record) {}V3 accepts an inclusive position.block_number or Unix-millisecond position.timestamp; explicit zero is invalid. A positioned call returns the selected envelope. An empty GetRequest waits for the next fills record written after the call begins, so set a deadline.
position: {
block_number: 1058646974
}
filter: {
fields: {
field: "coins"
op: FILTER_OP_IN
values: "BTC"
}
}Fills accept users, coins and dexes filters. User matching is case-insensitive, coin matching is case-sensitive and dex matching is exact on the HIP-3 dex prefix; values within a field use OR semantics and separate fields use AND semantics. A zero-match unary request returns the selected Record with data containing events: []. The record also exposes optional block_number and timestamp cursors. A pruned position returns NOT_FOUND; malformed filters return INVALID_ARGUMENT.
grpcurl \
-import-path content/docs/hyperliquid/grpc \
-proto v3.proto \
-H "x-api-key: ${DWELLIR_API_KEY}" \
-d '{"position":{"block_number":"1058646974"},"filter":{"fields":[{"field":"coins","op":"FILTER_OP_IN","values":["BTC"]}]}}' \
"${HYPERLIQUID_GRPC_ENDPOINT}" \
hyperliquid_l1_gateway.v3.HyperliquidL1Gateway/GetFillsCommon Use Cases
For V3, select each block with GetRequest.position.block_number, decode Record.data, and process its events array. The decoded payload supports the same PnL, volume, fill-verification, and liquidation workflows described in the StreamFills field reference.
Fill Field Reference
GetFills returns the same fill format as StreamFills. See the StreamFills documentation for the complete field reference, including liquidation data and maker vs taker details.
Best Practices
- Position Selection: Use the exact sequential block cursor for precise queries; timestamp lookups may return different fills across requests
- Data Validation: Always validate JSON structure and handle optional fields
- Within one block, group a match by
(coin, tid). Across blocks, includeblock_numberorblock_time. Retain account and order identity when deduplicating individual fills. - Error Recovery: Implement retry logic with exponential backoff
- Resource Management: Close gRPC connections properly to avoid resource leaks
Current Limitations
- Replay History: Available replay history varies by feed and endpoint. A cursor outside retained history returns
NOT_FOUND - Rate Limits: Be mindful of request frequency to avoid overwhelming the service
Resources
- GitHub: gRPC Code Examples - Complete working examples
- StreamFills Documentation - Full fill specification and streaming examples
- Copy Trading Bot - Production-ready example using fill data
Need help? Contact our support team or check the Hyperliquid gRPC documentation.
GetBlock - Get Block Data
Retrieve a single block from Hyperliquid L1 Gateway via gRPC. Get blockchain data at a specific position.
GetMempoolTxs - Get a Pre-Consensus Client Block
Retrieve one pre-consensus Hyperliquid client block by receive time over V3 gRPC, with nanosecond cursors for exact addressing.