> ## Documentation Index > Fetch the complete documentation index at: https://docs.dexpaprika.com/llms.txt > Use this file to discover all available pages before exploring further. # Stream real-time pool reserves for a single asset > Establishes an SSE stream of block-by-block, USD-denominated reserve changes for a single pool or a single token, using query string parameters. The reserves feed was restructured to emit a **distinct event name per subscription method** instead of a single shared event: - `pool_reserves`: emitted when `method=pool_reserves`. One event per block in which the subscribed **pool** changed. The payload carries the full pool snapshot, including a `tokens` array with per-token reserve and delta figures. Schema matches `PoolReservesEvent`. - `token_reserves`: emitted when `method=token_reserves`. One event per block per pool in which the subscribed **token** changed. The payload is flattened to that single token's reserve and delta in the affected pool. Schema matches `TokenReservesEvent`. - `ping`: Infrastructure keep-alive payload (`PingEvent`). - `warning`: System warning notifications (`WarningEvent`). - `error`: Stream-level operational exceptions (`ErrorEvent`), always a single `{"message": "..."}` object. ## OpenAPI ````yaml /streaming/api-streaming.yml get /sse/reserves openapi: 3.1.0 info: title: DexPaprika Streaming API version: 1.0.1 license: name: UNLICENSED identifier: UNLICENSED description: > The DexPaprika Streaming API delivers real-time updates for token prices utilizing the Server-Sent Events (SSE) protocol. ### Connection Quotas and Limits To ensure high availability and infrastructure stability, the following constraints are strictly enforced: - **Concurrent Streams:** A maximum of **10 active SSE streams** are permitted per IP address. Exceeding this threshold results in a `429 Too Many Requests` response containing the message `ip stream limit exceeded`. - **Subscription Capacity:** Batch subscription endpoints (POST) are limited to a maximum of **25 requests per stream**. - **Keep-Alive Protocol:** The server dispatches a `ping` event every 15 seconds to maintain active TCP connections. ### Deprecation Notice The `/stream` endpoint architecture has been refactored. - Legacy path `/stream` is **deprecated** and scheduled for decommissioning. - Active implementations must migrate to `/sse/prices`. ### Server-Sent Events (SSE) Protocol Messages conform to the standard W3C SSE specification with an additional `request_id` field for tracking multiplexed requests: ``` event: [event_name] request_id: [your_request_id] data: [json_payload] ``` #### Request correlation (`request_id`) Every streaming endpoint accepts an optional `request_id` query parameter. When supplied, the server echoes it back on every message of the stream as an SSE `request_id:` field, so you can correlate emitted events with the subscription that produced them. This is most useful on multiplexed POST streams where several subscriptions share one connection. The `request_id` is included on all non-legacy, non-system events — it is omitted from `ping`, `warning`, and `error` events. - **Format:** the value must be a non-negative integer. Any non-numeric value is rejected with `{"message": "invalid query parameters: request_id (must be a number)"}`. - **Default:** when omitted, the server emits `request_id: 0` on every message. #### Core System Events - `ping`: Sent every 15 seconds for connection keep-alive. ``` event: ping data: {"time": 1715162400} ``` - `warning`: Non-breaking operational alerts (e.g., deprecation warnings). ``` event: warning data: {"message": "Deprecation notice description"} ``` - `error`: Sent prior to abnormal stream termination. The payload is always a single `{"message": "..."}` object. ``` event: error data: {"message": "Error description"} ``` servers: - url: https://streaming.dexpaprika.com description: Production Streaming Gateway security: [] paths: /sse/reserves: get: summary: Stream real-time pool reserves for a single asset description: > Establishes an SSE stream of block-by-block, USD-denominated reserve changes for a single pool or a single token, using query string parameters. The reserves feed was restructured to emit a **distinct event name per subscription method** instead of a single shared event: - `pool_reserves`: emitted when `method=pool_reserves`. One event per block in which the subscribed **pool** changed. The payload carries the full pool snapshot, including a `tokens` array with per-token reserve and delta figures. Schema matches `PoolReservesEvent`. - `token_reserves`: emitted when `method=token_reserves`. One event per block per pool in which the subscribed **token** changed. The payload is flattened to that single token's reserve and delta in the affected pool. Schema matches `TokenReservesEvent`. - `ping`: Infrastructure keep-alive payload (`PingEvent`). - `warning`: System warning notifications (`WarningEvent`). - `error`: Stream-level operational exceptions (`ErrorEvent`), always a single `{"message": "..."}` object. parameters: - name: method in: query required: true schema: type: string enum: - pool_reserves - token_reserves description: >- Subscription method. `pool_reserves` watches one pool by its address; `token_reserves` watches every pool that contains the given token. - name: address in: query required: true schema: type: string description: >- Target pool address (for `pool_reserves`) or token contract address (for `token_reserves`). - name: chain in: query required: true schema: type: string description: Target blockchain network identifier (e.g., `ethereum`, `solana`). - name: limit in: query required: false schema: type: integer minimum: 1 description: >- Maximum event count processing threshold before server-initiated connection teardown. - $ref: '#/components/parameters/requestIdParam' responses: '200': description: SSE stream successfully established. content: text/event-stream: schema: oneOf: - $ref: '#/components/schemas/PoolReservesEvent' - $ref: '#/components/schemas/TokenReservesEvent' - $ref: '#/components/schemas/PingEvent' - $ref: '#/components/schemas/WarningEvent' - $ref: '#/components/schemas/ErrorEvent' components: parameters: requestIdParam: name: request_id in: query required: false schema: type: integer minimum: 0 description: >- Optional correlation ID echoed back on every message of the stream as an SSE `request_id:` field. Must be a non-negative integer; non-numeric values are rejected with `{"message": "invalid query parameters: request_id (must be a number)"}`. Defaults to `0` when omitted. schemas: PoolReservesEvent: type: object description: >- Payload for the `pool_reserves` event channel. Emitted once per block in which the subscribed pool changed, carrying the full pool snapshot. properties: chain: type: string description: The blockchain network the pool resides on. example: ethereum pool_id: type: string description: Address of the pool the change happened in. example: '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640' block: type: string description: Block number the change was observed in (string-encoded). example: '25236164' tokens: type: array description: Per-token reserve state for every token in the pool. items: $ref: '#/components/schemas/ReserveTokenEntry' total_reserve_usd: type: number description: Total reserve value of the pool in USD. example: 92394235.39327304 total_delta_usd: type: number description: >- Net USD reserve change across all tokens this block. Positive means net inflow, negative means net outflow. example: 28.042117388933548 timestamp: type: integer description: Unix timestamp (seconds) when the event was emitted by the stream. example: 1780481297 block_timestamp: type: integer description: >- Unix timestamp (seconds) of the block in which the change was observed. example: 1780481291 TokenReservesEvent: type: object description: >- Payload for the `token_reserves` event channel. Emitted once per block per pool in which the subscribed token changed, flattened to that single token's reserve state in the affected pool. properties: chain: type: string description: The blockchain network the change happened on. example: ethereum token_id: type: string description: Contract address of the subscribed token. example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' reserve: type: string description: >- Current reserve of this token in the affected pool (string-encoded raw integer). example: '1594137888891996' delta: type: string description: >- Change in this token's reserve since the previous block (string-encoded raw integer). May be negative. example: '185546629534' block: type: string description: Block number the change was observed in (string-encoded). example: '25236162' price_usd: type: number description: Current USD price of the token at observation time. example: 1.0004497513149309 reserve_usd: type: number description: Current reserve value of this token in USD. example: 1594854854.5037065 delta_usd: type: number description: USD value of this block's reserve change. May be negative. example: 185630.0793746139 updated_at: type: integer description: >- Unix timestamp (seconds) when the underlying reserve state was last updated. example: 1780481267 timestamp: type: integer description: Unix timestamp (seconds) when the event was emitted by the stream. example: 1780481271 PingEvent: type: object description: Connection structural lifecycle verify payload. properties: time: type: integer description: Standard Unix system epoch format validation anchor. example: 1715162400 WarningEvent: type: object description: Informational pipeline lifecycle event indicators. properties: message: type: string description: Internal compliance metrics alert description. example: stream is deprecated, move to /sse/prices instead ErrorEvent: type: object description: Runtime system stream rejection payload exception details. properties: message: type: string description: Machine-readable reason for connection fault or stream termination. example: 'invalid search query parameters: address (not found)' ReserveTokenEntry: type: object description: >- Reserve state for one token inside a pool snapshot. Large on-chain integers (`reserve`, `delta`) are encoded as strings because they routinely exceed `Number.MAX_SAFE_INTEGER`. properties: token_id: type: string description: Token contract address. example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' reserve: type: string description: >- Current reserve of this token, as a raw on-chain integer (string-encoded). example: '27549935173644' delta: type: string description: >- Change in this token's reserve since the previous block, as a raw on-chain integer (string-encoded). May be negative. example: '69057090960' price_usd: type: number description: Current USD price of the token at observation time. example: 1.000240563722932 reserve_usd: type: number description: Current reserve value of this token in USD. example: 27556562.688615907 delta_usd: type: number description: >- USD value of this block's reserve change for this token. May be negative. example: 69073.70359089618 ````