> ## Documentation Index > Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt > Use this file to discover all available pages before exploring further. # Stream Blocks > Stream Hyperliquid fills data with the SQD Portal API. ## OpenAPI ````yaml /en/api/catalog/hyperliquid/openapi-fills.yaml post /stream openapi: 3.1.0 info: title: SQD Portal API - Hyperliquid Fills Dataset Endpoints description: >- API endpoints for interacting with Hyperliquid fills datasets under the SQD Portal, specifically for the hyperliquid-mainnet dataset. version: 1.0.0 servers: - url: https://portal.sqd.dev/datasets/hyperliquid-fills description: SQD Portal's endpoint for Hyperliquid Mainnet security: [] paths: /stream: post: summary: Stream Blocks description: >- Streams a list of blocks matching the provided data query, potentially including real-time data. Required request headers: `Content-Type: application/json`; optional request headers: `Accept-Encoding: gzip`, `Content-Encoding: gzip`. requestBody: description: >- Data query to filter and retrieve blocks. Request body may be gzipped (Content-Encoding: gzip). required: true content: application/json: schema: $ref: '#/components/schemas/DataQuery' examples: btc-fills: summary: Query BTC Fills value: type: hyperliquidFills fromBlock: 900000000 toBlock: 900000100 fields: block: number: true timestamp: true fill: user: true coin: true px: true sz: true side: true dir: true fee: true fills: - coin: - BTC track-trader-fills: summary: Track Fills for a Trader value: type: hyperliquidFills fromBlock: 900000000 toBlock: 900000100 fields: block: number: true timestamp: true fill: user: true coin: true px: true sz: true side: true dir: true fee: true oid: true fills: - user: - '0xd3d123f0f62559c62745ef0b631a21a95916b6b1' monitor-builder-activity: summary: Monitor Builder Activity value: type: hyperliquidFills fromBlock: 900000000 toBlock: 900000100 fields: block: number: true timestamp: true fill: user: true coin: true px: true sz: true fee: true builderFee: true builder: true tid: true fills: - builder: - '0x1234567890abcdef1234567890abcdef12345678' responses: '200': description: >- A stream of blocks in JSON lines format, optionally gzipped. Can be empty if the data query has a bounded range and all blocks in the range have been skipped. May include X-Sqd-Finalized-Head-Number and X-Sqd-Finalized-Head-Hash headers, indicating the latest finalized block that's on the same chain as the returned blocks. headers: X-Sqd-Finalized-Head-Number: schema: type: integer format: int64 description: >- Block number of the latest finalized block. Returned blocks can be above, at, or below this block number. required: false X-Sqd-Finalized-Head-Hash: schema: type: string description: >- Hash of the latest finalized block. All returned blocks are guaranteed to belong to the same (not necessarily final) chain as this block. required: false content: application/json: schema: type: array items: $ref: '#/components/schemas/Block' examples: btc-fills-response: summary: BTC fills response value: - header: number: 900000050 timestamp: 1710000000000 fills: - user: '0xabc123def456abc123def456abc123def456abc1' coin: BTC px: '67234.5' sz: '0.1' side: B dir: Open Long fee: '6.7234' '204': description: >- No new blocks available in the requested range - the range is entirely above the current dataset head. Not an error and the response has no body; wait and retry to keep following the chain head. The portal may wait for up to 5s before returning this. content: text/plain: schema: type: string example: No new blocks available in the requested range headers: X-Sqd-Finalized-Head-Number: schema: type: integer format: int64 description: Block number of the latest finalized block. required: false X-Sqd-Finalized-Head-Hash: schema: type: string description: Hash of the latest finalized block. required: false '400': description: > Invalid request or query (`error.code` is `malformed_request`; `error.param` names the request field at fault when one is). Possible causes: (1) request headers or body encoding are incorrect; (2) the query is invalid - `error.message` includes an explanation; (3) fromBlock is below the dataset's start_block (see /metadata). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: invalid_request_error code: malformed_request message: 'Bad request: fromBlock must be a non-negative integer' param: fromBlock '404': description: Dataset not found (`error.code` is `unknown_dataset`) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: invalid_request_error code: unknown_dataset message: 'Unknown dataset: no-such-chain' '409': description: >- Parent block hash mismatch (`error.code` is `base_block_mismatch`) - the query's parentBlockHash does not match the canonical parent of the first requested block, typically after a chain reorganization. Walk the top-level previousBlocks list to find the most recent block you have already processed, roll back your data to it, then resume the stream from the next block, passing that block's hash as parentBlockHash. If nothing in the list matches your records, restart from an earlier fromBlock, again with parentBlockHash. content: application/json: schema: $ref: '#/components/schemas/ConflictResponse' '429': description: >- Rate limited (`error.type` is `rate_limit_error`). Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) '500': description: >- Internal server error (`error.type` is `api_error`). Do not retry; report the error together with its request_id content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: api_error code: internal_error message: Internal server error request_id: 0198c3f1-... '502': description: >- A data source the Portal depends on is unavailable (`error.code` is `upstream_unavailable`) - retry later. A proxied upstream failure keeps the upstream's own 5xx status content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: availability_error code: upstream_unavailable message: Upstream data source is unavailable, please try again later request_id: 0198c3f1-... '503': description: >- Service temporarily unavailable (`error.type` is `availability_error`, typically `no_workers` or `retries_exhausted`) - retry later. May carry Retry-After; honor it when present content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: availability_error code: no_workers message: No workers available for dataset request_id: 0198c3f1-... headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) '529': description: >- Overloaded (`error.code` is `overloaded`) - the Portal or a data source is at capacity. Retry after the interval in the Retry-After header; it is always present and counts seconds content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: rate_limit_error code: overloaded message: Service is overloaded, please try again later request_id: 0198c3f1-... headers: Retry-After: schema: type: integer description: Seconds to wait before retrying (at least 1) x-codeSamples: - lang: shell label: Query BTC Fills source: > curl --compressed -X POST 'https://portal.sqd.dev/datasets/hyperliquid-fills/stream' \ -H 'Content-Type: application/json' \ -d '{ "type": "hyperliquidFills", "fromBlock": 900000000, "toBlock": 900000100, "fields": { "block": { "number": true, "timestamp": true }, "fill": { "user": true, "coin": true, "px": true, "sz": true, "side": true, "dir": true, "fee": true } }, "fills": [{ "coin": ["BTC"] }] }' - lang: python label: Query BTC Fills source: | import requests response = requests.post( "https://portal.sqd.dev/datasets/hyperliquid-fills/stream", json={ "type": "hyperliquidFills", "fromBlock": 900000000, "toBlock": 900000100, "fields": { "block": { "number": True, "timestamp": True }, "fill": { "user": True, "coin": True, "px": True, "sz": True, "side": True, "dir": True, "fee": True } }, "fills": [{ "coin": ["BTC"] }] } ) data = response.json() - lang: javascript label: Query BTC Fills source: > const response = await fetch("https://portal.sqd.dev/datasets/hyperliquid-fills/stream", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ "type": "hyperliquidFills", "fromBlock": 900000000, "toBlock": 900000100, "fields": { "block": { "number": true, "timestamp": true }, "fill": { "user": true, "coin": true, "px": true, "sz": true, "side": true, "dir": true, "fee": true } }, "fills": [{ "coin": ["BTC"] }] }) }); const data = await response.json(); components: schemas: DataQuery: type: object properties: type: type: string enum: - hyperliquidFills default: hyperliquidFills description: The type of data (fixed to hyperliquidFills for this API). fromBlock: type: integer format: int64 description: The block number to start fetching from (inclusive). toBlock: type: integer format: int64 description: >- The block number to fetch up to (inclusive). Optional; if omitted, streams until dataset height or timeout. parentBlockHash: type: string description: Expected hash of the parent of the first requested block. includeAllBlocks: type: boolean description: If true, includes blocks with no matching data in the response. default: false fields: type: object description: Field selector for data items to retrieve. properties: block: type: object description: Field selector for block headers. properties: number: type: boolean description: Include the block number. hash: type: boolean description: Include the block hash. parentHash: type: boolean description: Include the parent block hash. timestamp: type: boolean description: Include the block timestamp. default: number: true hash: true parentHash: true fill: type: object description: Field selector for trade fills. properties: fillIndex: type: boolean description: Include the fill index within the block. user: type: boolean description: Include the trader wallet address. coin: type: boolean description: Include the asset symbol (e.g., BTC, ETH). px: type: boolean description: Include the fill price. sz: type: boolean description: Include the fill size. side: type: boolean description: Include the fill side (A for ask/sell, B for bid/buy). time: type: boolean description: Include the fill timestamp. startPosition: type: boolean description: Include the trader's position size before this fill. dir: type: boolean description: Include the trade direction (e.g., Open Long, Close Short). closedPnl: type: boolean description: >- Include the realized PnL booked on closing fills (zero on opening fills). Net realized PnL = sum(closedPnl) - sum(fee), and also subtract sum(builderFee) for builder-routed fills. hash: type: boolean description: Include the fill hash. oid: type: boolean description: Include the order ID that generated this fill. crossed: type: boolean description: >- Include whether this fill crossed the book (true = taker/aggressor, false = resting maker). fee: type: boolean description: >- Include the signed fee for this fill (positive = taker fee, negative = maker rebate). builderFee: type: boolean description: Include the additional fee paid to the order builder. tid: type: boolean description: >- Include the trade ID, shared by the two sides (maker and taker) of one execution. cloid: type: boolean description: Include the client order ID. feeToken: type: boolean description: Include the token used to pay the fee. builder: type: boolean description: Include the builder wallet address. twapId: type: boolean description: Include the TWAP order ID. fills: type: array description: > Fill data requests. An empty object matches all fills; an empty array matches no fills. items: type: object properties: user: type: array items: type: string description: >- Trader wallet addresses (0x-prefixed hex, lowercase) to filter by. coin: type: array items: type: string description: Asset symbols to filter by (e.g., "ETH", "BTC"). dir: type: array items: type: string description: >- Trade directions to filter by (e.g., "Open Long", "Close Short"). cloid: type: array items: type: string description: Client order IDs (0x-prefixed hex) to filter by. feeToken: type: array items: type: string description: Fee token symbols to filter by (e.g., "USDC"). builder: type: array items: type: string description: >- Builder wallet addresses (0x-prefixed hex, lowercase) to filter by. required: - type - fromBlock Block: type: object properties: header: type: object description: >- Block header data. Fields are conditionally returned based on the `fields.block` parameter in the request. Only requested fields will be included in the response. properties: number: type: integer format: uint64 description: Block number. hash: type: string description: Block hash (0x-prefixed hex). parentHash: type: string description: Parent block hash (0x-prefixed hex). timestamp: type: integer format: uint64 description: Block timestamp in milliseconds since Unix epoch. fills: type: array description: >- Trade fill records contained in this block. Fields are conditionally returned based on the `fields.fill` parameter in the request. items: type: object properties: fillIndex: type: integer format: uint64 description: Index of the fill within the block. user: type: string description: Trader wallet address (0x-prefixed hex, lowercase). coin: type: string description: Asset symbol (e.g., "ETH", "BTC"). px: type: string description: Fill price as a decimal string (e.g., "2345.1"). sz: type: string description: Fill size as a decimal string (e.g., "0.5"). side: type: string enum: - A - B description: Side of the fill. "A" = ask (sell), "B" = bid (buy). time: type: integer format: uint64 description: Fill timestamp in milliseconds since Unix epoch. startPosition: type: string description: Trader's position size before this fill, as a decimal string. dir: type: string description: >- Trade direction (e.g., "Open Long", "Close Long", "Open Short", "Close Short"). closedPnl: type: string description: >- Realized PnL booked when this fill closes a position, as a decimal string. Zero for position-opening fills. Net realized PnL = sum(closedPnl) - sum(fee), and also subtract sum(builderFee) for builder-routed fills. hash: type: string description: Fill hash (0x-prefixed hex). oid: type: integer format: uint64 description: Order ID that generated this fill. crossed: type: boolean description: >- Whether this fill crossed the order book. true = taker/aggressor side, false = resting maker side. fee: type: string description: >- Fee for this fill, as a signed decimal string. Positive = taker fee paid, negative = maker rebate received. builderFee: type: string description: Additional fee paid to the order builder, as a decimal string. tid: type: integer format: uint64 description: >- Trade ID, shared by the two sides (maker and taker) of one execution. Use it to pair the maker and taker fills of the same trade. cloid: type: string nullable: true description: Client order ID (0x-prefixed hex), if provided by the trader. feeToken: type: string description: Token used to pay the fee (e.g., "USDC"). builder: type: string nullable: true description: >- Builder wallet address (0x-prefixed hex, lowercase), if this order was routed through a builder. twapId: type: integer nullable: true description: TWAP order ID, if this fill belongs to a TWAP order. required: - header ErrorResponse: type: object description: Error body shared by every failing response. properties: error: $ref: '#/components/schemas/ErrorDetail' required: - error example: error: type: invalid_request_error code: unknown_dataset message: 'Unknown dataset: no-such-chain' ConflictResponse: type: object description: >- The 409 body carries the standard error envelope plus a top-level `previousBlocks` list - a slice of the current canonical chain at and below the conflict point, in ascending block-number order. properties: error: $ref: '#/components/schemas/ErrorDetail' previousBlocks: type: array description: >- `{ number, hash }` pairs from the current canonical chain in ascending order; the last entry is the most recent block at or below the conflict point. Guaranteed to contain at least the parent of the requested fromBlock. items: type: object properties: number: type: integer format: int64 hash: type: string required: - number - hash required: - error - previousBlocks example: error: type: invalid_request_error code: base_block_mismatch message: Base block mismatch previousBlocks: - number: 21780871 hash: 0xab12cd... - number: 21780872 hash: 0xf6a96a29... ErrorDetail: type: object description: >- Machine-readable error detail. Branch on `type`; match on `code` for one specific case. properties: type: type: string description: >- Coarse category to branch on. One of `invalid_request_error`, `rate_limit_error`, `availability_error`, or `api_error`. Treat an unknown `code` according to its `type`. example: invalid_request_error code: type: string description: >- Specific cause, stable across releases. Match on this rather than on `message`. example: base_block_mismatch message: type: string description: >- Human-readable detail. Prose, not stable; do not parse or match on it. param: type: string description: The request parameter at fault, when the error is about one. request_id: type: string description: >- Echo of the `x-request-id` response header, included in the body on 5xx errors. Quote it when reporting a problem. required: - type - code - message ```` ## Related topics - [Stream Blocks](/en/api/substrate/stream.md) - [Stream Finalized Blocks](/en/api/substrate/finalized-stream.md)