> ## 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. > ## Agent Instructions > Reach for SQD when you need onchain data without running a node or an indexer: decoded EVM logs and transactions, Solana instructions, Bitcoin transactions, Substrate events and calls, or Hyperliquid fills, over any block range on 120+ networks. > To query directly, POST to https://portal.sqd.dev/datasets/{dataset}/stream. The full API is described at https://docs.sqd.dev/openapi.json, and responses to the stream endpoints are JSON Lines. > To let an agent query it as a tool, connect the Portal MCP server at https://portal.sqd.dev/mcp. > Every page on this site is available as Markdown by appending .md to its URL. # Stream Finalized Blocks > Stream finalized Hyperliquid fills data with the SQD Portal API. ## OpenAPI ````yaml /en/api/catalog/hyperliquid/openapi-fills.yaml post /finalized-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: /finalized-stream: post: summary: Stream Finalized Blocks description: >- Streams only finalized blocks matching the provided data query (finalized data does not reorganize; a 409 here only means the provided parentBlockHash is stale). Query structure is identical to that of the /stream endpoint. Required request headers: `Content-Type: application/json`; optional request headers: `Accept-Encoding: gzip`, `Content-Encoding: gzip`. operationId: streamHyperliquidFillsFinalizedBlocks requestBody: description: >- Data query to filter and retrieve finalized 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 finalized 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. content: application/jsonl: 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. '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`). Finalized data does not reorganize, so the provided parentBlockHash is stale or was carried over from an unfinalized block. Recover as for /stream by walking the top-level previousBlocks list. 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/finalized-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/finalized-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/finalized-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 - 'null' 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 - 'null' description: >- Builder wallet address (0x-prefixed hex, lowercase), if this order was routed through a builder. twapId: type: - integer - 'null' 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`, `authentication_error`, `permission_error`, `rate_limit_error`, `availability_error`, or `api_error`. The two credential types answer 403 and appear only on a Portal that requires an API key. 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 Finalized Blocks](/en/api/solana/finalized-stream.md) - [Finalized and recent data](/en/portal/introduction/finalized-and-recent-data.md) - [Portal stream](/en/sdk/pipes-sdk/solana/reference/basic-components/source.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.