GetFills - Get Fill Data
Retrieve fills at a specific position from Hyperliquid L1 Gateway via gRPC. Get order execution data for analysis and reconciliation.
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 and coins filters. User matching is case-insensitive and coin matching is case-sensitive; 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.
Common 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
- Grouping and Deduplication: Group a match by at least
(coin, tid)becausetidis not globally unique. Preserve one taker/liquidated-side fill plus one or more maker/counterparty fills; extend the key with user or order identity when deduplicating individual records. - 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.
GetMiscEvents - Get Miscellaneous Event Data
Retrieve miscellaneous events at a specific position from Hyperliquid L1 Gateway via gRPC. Get non-fill balance-affecting events for analysis and reconciliation.