> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Spot OHLC

> Subscribe to real-time OHLC candlestick bars from on-chain AMM swap aggregates (`0404`).

## Overview

* **Dataset ID:** [`0404 - Token-to-Token OHLC`](/data-catalog/evm/prices/token-to-token-prices-ohlc)
* **Description:** Time-bucketed OHLC bars (1m..1d) per pool and token pair direction.
* **Sample:** [Hugging Face Sample](https://huggingface.co/datasets/BlockDB/Token-To-Token-Prices-OHLC)

## Subscription Parameters

<ParamField body="chain_id" type="number" required>
  Target EVM chain. *See the [Chain](/api-reference/enumerations/chain) enumeration for supported values.*
</ParamField>

<ParamField body="base_token_address" type="string" required>
  ERC-20 contract address for the base asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField body="quote_token_address" type="string" required>
  ERC-20 contract address for the quote asset (hex string, 20 bytes, no `0x` prefix).
</ParamField>

<ParamField body="aggregation_interval" type="string" default="1m">
  Candle width, expressed as an ISO-8601 duration shorthand (`1m`, `5m`, `1h`, `1d`). Default is `1m`.
</ParamField>

## Message Fields (`data`)

Top-level fields: `chain_id`, `dataset_id`, `is_reorg`, `data` (object). The `data` object mirrors **`b0404_token_to_token_prices_ohlc_v1`**:

<ResponseField name="data.pool_uid" type="string">
  `BYTEA` — Pool id (hex).
</ResponseField>

<ResponseField name="data.exchange_id" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.type_id" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.bucket_start" type="string">
  `TIMESTAMPTZ` — Inclusive UTC bucket start.
</ResponseField>

<ResponseField name="data.bucket_end" type="string">
  `TIMESTAMPTZ` — Exclusive UTC bucket end (`bucket_start + bucket_seconds`).
</ResponseField>

<ResponseField name="data.bucket_seconds" type="number">
  `INTEGER`
</ResponseField>

<ResponseField name="data.token_in" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data.token_out" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data.open" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.high" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.low" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.close" type="string">
  `NUMERIC(78,18)`
</ResponseField>

<ResponseField name="data.volume_in_raw" type="string">
  `NUMERIC(78,0)` — Sum of raw UInt256 `amountIn` values.
</ResponseField>

<ResponseField name="data.volume_in" type="string | null">
  `NUMERIC(78,18)` — Decimal-adjusted `token_in` volume; `null` if decimals unknown.
</ResponseField>

<ResponseField name="data.volume_out_raw" type="string">
  `NUMERIC(78,0)` — Sum of raw UInt256 `amountOut` values.
</ResponseField>

<ResponseField name="data.volume_out" type="string | null">
  `NUMERIC(78,18)` — Decimal-adjusted `token_out` volume; `null` if decimals unknown.
</ResponseField>

<ResponseField name="data.trades_count" type="number">
  `BIGINT`
</ResponseField>

<ResponseField name="data._tracing_id" type="string">
  `BYTEA`
</ResponseField>

<ResponseField name="data._parent_tracing_ids" type="string[] | null">
  `BYTEA[]` — Optional parent lineage references.
</ResponseField>

<ResponseField name="data._created_at" type="string">
  `TIMESTAMPTZ`
</ResponseField>

<ResponseField name="data._updated_at" type="string">
  `TIMESTAMPTZ`
</ResponseField>

## Subscription Example

<CodeGroup>
  ```bash bash theme={null}
  # Use wscat to connect and subscribe
  wscat -c wss://api.blockdb.io/v1/evm/ \
    -H "Authorization: Bearer $BLOCKDB_API_KEY" \
    -x '{"action": "subscribe", "dataset_id": "0404", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "aggregation_interval": "1m"}}'
  ```

  ```c C theme={null}
  #include <libwebsockets.h>
  #include <string.h>
  #include <stdio.h>

  static int callback_blockdb(struct lws *wsi, enum lws_callback_reasons reason,
                              void *user, void *in, size_t len) {
      switch (reason) {
          case LWS_CALLBACK_CLIENT_ESTABLISHED:
              lws_callback_on_writable(wsi);
              break;
          case LWS_CALLBACK_CLIENT_RECEIVE:
              printf("Received: %s\n", (char *)in);
              break;
          case LWS_CALLBACK_CLIENT_WRITEABLE: {
              unsigned char buf[LWS_PRE + 1024];
              unsigned char *p = &buf[LWS_PRE];
              size_t n = sprintf((char *)p, "{\"action\": \"subscribe\", \"dataset_id\": \"0404\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_token_address\": \"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\", \"aggregation_interval\": \"1m\"}}");
              lws_write(wsi, p, n, LWS_WRITE_TEXT);
              break;
          }
      }
      return 0;
  }
  ```

  ```csharp .NET theme={null}
  using System;
  using System.Net.WebSockets;
  using System.Text;
  using System.Threading;
  using System.Threading.Tasks;

  class Program {
      static async Task Main() {
          using var ws = new ClientWebSocket();
          ws.Options.SetRequestHeader("Authorization", $"Bearer {Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")}");
          await ws.ConnectAsync(new Uri("wss://api.blockdb.io/v1/evm/"), CancellationToken.None);

          var subMsg = "{\"action\": \"subscribe\", \"dataset_id\": \"0404\", \"chain_id\": 1, \"params\": {\"base_token_address\": \"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\", \"quote_token_address\": \"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\", \"aggregation_interval\": \"1m\"}}";
          await ws.SendAsync(new ArraySegment<byte>(Encoding.UTF8.GetBytes(subMsg)), WebSocketMessageType.Text, true, CancellationToken.None);

          var buffer = new byte[1024 * 4];
          while (ws.State == WebSocketState.Open) {
              var result = await ws.ReceiveAsync(new ArraySegment<byte>(buffer), CancellationToken.None);
              Console.WriteLine(Encoding.UTF8.GetString(buffer, 0, result.Count));
          }
      }
  }
  ```

  ```python Python theme={null}
  import websocket
  import json
  import os

  def on_message(ws, message):
      print(f"Received: {message}")

  def on_open(ws):
      msg = {
          "action": "subscribe",
          "dataset_id": "0404",
          "chain_id": 1,
          "params": {
              "base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
              "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
              "aggregation_interval": "1m"
          }
      }
      ws.send(json.dumps(msg))

  ws = websocket.WebSocketApp(
      "wss://api.blockdb.io/v1/evm/",
      header={"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}"},
      on_message=on_message,
      on_open=on_open
  )
  ws.run_forever()
  ```

  ```javascript Node.js theme={null}
  const WebSocket = require('ws');

  const ws = new WebSocket('wss://api.blockdb.io/v1/evm/', {
    headers: { 'Authorization': `Bearer ${process.env.BLOCKDB_API_KEY}` }
  });

  ws.on('open', () => {
    ws.send(JSON.stringify({
      action: 'subscribe',
      dataset_id: '0404',
      chain_id: 1,
      params: {
        base_token_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        quote_token_address: "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        aggregation_interval: "1m"
      }
    }));
  });

  ws.on('message', (data) => {
    console.log('Received:', JSON.parse(data));
  });
  ```

  ```go Go theme={null}
  package main

  import (
  	"fmt"
  	"log"
  	"net/http"
  	"os"
  	"github.com/gorilla/websocket"
  )

  func main() {
  	header := http.Header{"Authorization": []string{"Bearer " + os.Getenv("BLOCKDB_API_KEY")}}
  	c, _, err := websocket.DefaultDialer.Dial("wss://api.blockdb.io/v1/evm/", header)
  	if err != nil {
  		log.Fatal("dial:", err)
  	}
  	defer c.Close()

  	sub := `{"action": "subscribe", "dataset_id": "0404", "chain_id": 1, "params": {"base_token_address": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "quote_token_address": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "aggregation_interval": "1m"}}`
  	err = c.WriteMessage(websocket.TextMessage, []byte(sub))
  	if err != nil {
  		log.Fatal("write:", err)
  	}

  	for {
  		_, message, err := c.ReadMessage()
  		if err != nil {
  			log.Fatal("read:", err)
  		}
  		fmt.Printf("Received: %s\n", message)
  	}
  }
  ```
</CodeGroup>

## Response Example

<CodeGroup>
  ```json Response theme={null}
  {
    "chain_id": 1,
    "dataset_id": "0404",
    "is_reorg": false,
    "data": {
      "pool_uid": "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000",
      "exchange_id": 1,
      "type_id": 201,
      "bucket_start": "2025-11-11T00:00:00.000Z",
      "bucket_end": "2025-11-11T00:01:00.000Z",
      "bucket_seconds": 60,
      "token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "open": "3010.112233445566778899",
      "high": "3033.998877665544332211",
      "low": "3008.001122334455667788",
      "close": "3025.219821481234567890",
      "volume_in_raw": "420000000000000000000",
      "volume_in": "420.000000000000000000",
      "volume_out_raw": "1269000000000",
      "volume_out": "1269000.000000000000000000",
      "trades_count": 128,
      "_tracing_id": "0404000000000000000000000000000000000001",
      "_parent_tracing_ids": null,
      "_created_at": "2025-11-11T00:01:05.000Z",
      "_updated_at": "2025-11-11T00:01:05.000Z"
    }
  }
  ```
</CodeGroup>


## AsyncAPI

````yaml specs/wss/evm/prices/crypto/prices-spot-ohlc.yaml spot-ohlc
id: spot-ohlc
title: Spot-ohlc
description: ''
servers:
  - id: production
    protocol: wss
    host: api.blockdb.io/v1/evm/
    bindings: []
    variables: []
address: /
parameters: []
bindings: []
operations:
  - &ref_2
    id: onSubscribe
    title: On subscribe
    type: receive
    messages:
      - &ref_5
        id: subscribe
        payload:
          - name: subscribe
            type: object
            properties:
              - name: action
                type: string
                description: subscribe
                required: true
              - name: chain_id
                type: integer
                required: true
              - name: dataset_id
                type: string
                description: '0404'
                required: true
              - name: params
                type: object
                required: true
                properties:
                  - name: base_token_address
                    type: string
                    required: false
                  - name: quote_token_address
                    type: string
                    required: false
                  - name: aggregation_interval
                    type: string
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            action:
              type: string
              const: subscribe
              x-parser-schema-id: <anonymous-schema-2>
            chain_id:
              type: integer
              x-parser-schema-id: <anonymous-schema-3>
            dataset_id:
              type: string
              const: '0404'
              x-parser-schema-id: <anonymous-schema-4>
            params:
              type: object
              properties:
                base_token_address:
                  type: string
                  x-parser-schema-id: <anonymous-schema-6>
                quote_token_address:
                  type: string
                  x-parser-schema-id: <anonymous-schema-7>
                aggregation_interval:
                  type: string
                  x-parser-schema-id: <anonymous-schema-8>
              x-parser-schema-id: <anonymous-schema-5>
          required:
            - action
            - chain_id
            - dataset_id
            - params
          x-parser-schema-id: <anonymous-schema-1>
        title: Subscribe
        example: |-
          {
            "action": "<string>",
            "chain_id": 123,
            "dataset_id": "<string>",
            "params": {
              "base_token_address": "<string>",
              "quote_token_address": "<string>",
              "aggregation_interval": "<string>"
            }
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: subscribe
          - id: x-parser-message-name
            value: subscribe
    bindings: []
    extensions: &ref_0
      - id: x-parser-unique-object-id
        value: spot-ohlc
  - &ref_3
    id: onUnsubscribe
    title: On unsubscribe
    type: receive
    messages:
      - &ref_6
        id: unsubscribe
        payload:
          - name: unsubscribe
            type: object
            properties:
              - name: action
                type: string
                description: unsubscribe
                required: true
              - name: chain_id
                type: integer
                required: true
              - name: dataset_id
                type: string
                description: '0404'
                required: true
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            action:
              type: string
              const: unsubscribe
              x-parser-schema-id: <anonymous-schema-10>
            chain_id:
              type: integer
              x-parser-schema-id: <anonymous-schema-11>
            dataset_id:
              type: string
              const: '0404'
              x-parser-schema-id: <anonymous-schema-12>
          required:
            - action
            - chain_id
            - dataset_id
          x-parser-schema-id: <anonymous-schema-9>
        title: Unsubscribe
        example: |-
          {
            "action": "<string>",
            "chain_id": 123,
            "dataset_id": "<string>"
          }
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: unsubscribe
          - id: x-parser-message-name
            value: unsubscribe
    bindings: []
    extensions: *ref_0
  - &ref_4
    id: emitUpdates
    title: Emit updates
    type: send
    messages:
      - &ref_7
        id: subscribe_response
        payload:
          - name: subscribe_response
            type: object
            properties:
              - name: action
                type: string
                description: subscribe
                required: true
              - name: chain_id
                type: integer
                required: true
              - name: dataset_id
                type: string
                description: '0404'
                required: true
              - name: status
                type: string
                enumValues:
                  - success
                  - error
                required: true
              - name: error
                type: object
                required: false
                properties:
                  - name: code
                    type: string
                    description: Machine-readable error code.
                    required: true
                  - name: message
                    type: string
                    description: Human-readable summary of the error.
                    required: true
                  - name: hint
                    type: string
                    description: Diagnostic hint to help resolve the issue.
                    required: false
                  - name: severity
                    type: string
                    enumValues:
                      - info
                      - warning
                      - error
                      - critical
                    required: true
                  - name: retryable
                    type: boolean
                    description: Whether the client should attempt to retry the operation.
                    required: true
                  - name: details
                    type: object
                    description: Additional structured metadata about the error.
                    required: false
                  - name: docs_url
                    type: string
                    description: Link to relevant documentation for the error.
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            action:
              type: string
              const: subscribe
              x-parser-schema-id: <anonymous-schema-14>
            chain_id:
              type: integer
              x-parser-schema-id: <anonymous-schema-15>
            dataset_id:
              type: string
              const: '0404'
              x-parser-schema-id: <anonymous-schema-16>
            status:
              type: string
              enum:
                - success
                - error
              x-parser-schema-id: <anonymous-schema-17>
            error: &ref_1
              type: object
              properties:
                code:
                  type: string
                  description: Machine-readable error code.
                  x-parser-schema-id: <anonymous-schema-18>
                message:
                  type: string
                  description: Human-readable summary of the error.
                  x-parser-schema-id: <anonymous-schema-19>
                hint:
                  type: string
                  description: Diagnostic hint to help resolve the issue.
                  x-parser-schema-id: <anonymous-schema-20>
                severity:
                  type: string
                  enum:
                    - info
                    - warning
                    - error
                    - critical
                  x-parser-schema-id: <anonymous-schema-21>
                retryable:
                  type: boolean
                  description: Whether the client should attempt to retry the operation.
                  x-parser-schema-id: <anonymous-schema-22>
                details:
                  type: object
                  description: Additional structured metadata about the error.
                  x-parser-schema-id: <anonymous-schema-23>
                docs_url:
                  type: string
                  format: uri
                  description: Link to relevant documentation for the error.
                  x-parser-schema-id: <anonymous-schema-24>
              required:
                - code
                - message
                - severity
                - retryable
              x-parser-schema-id: ErrorObject
          required:
            - action
            - chain_id
            - dataset_id
            - status
          x-parser-schema-id: <anonymous-schema-13>
        title: Subscribe_response
        example: No examples found
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: subscribe_response
          - id: x-parser-message-name
            value: subscribe_response
      - &ref_8
        id: unsubscribe_response
        payload:
          - name: unsubscribe_response
            type: object
            properties:
              - name: action
                type: string
                description: unsubscribe
                required: true
              - name: chain_id
                type: integer
                required: true
              - name: dataset_id
                type: string
                description: '0404'
                required: true
              - name: status
                type: string
                enumValues:
                  - success
                  - error
                required: true
              - name: error
                type: object
                required: false
                properties:
                  - name: code
                    type: string
                    description: Machine-readable error code.
                    required: true
                  - name: message
                    type: string
                    description: Human-readable summary of the error.
                    required: true
                  - name: hint
                    type: string
                    description: Diagnostic hint to help resolve the issue.
                    required: false
                  - name: severity
                    type: string
                    enumValues:
                      - info
                      - warning
                      - error
                      - critical
                    required: true
                  - name: retryable
                    type: boolean
                    description: Whether the client should attempt to retry the operation.
                    required: true
                  - name: details
                    type: object
                    description: Additional structured metadata about the error.
                    required: false
                  - name: docs_url
                    type: string
                    description: Link to relevant documentation for the error.
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            action:
              type: string
              const: unsubscribe
              x-parser-schema-id: <anonymous-schema-26>
            chain_id:
              type: integer
              x-parser-schema-id: <anonymous-schema-27>
            dataset_id:
              type: string
              const: '0404'
              x-parser-schema-id: <anonymous-schema-28>
            status:
              type: string
              enum:
                - success
                - error
              x-parser-schema-id: <anonymous-schema-29>
            error: *ref_1
          required:
            - action
            - chain_id
            - dataset_id
            - status
          x-parser-schema-id: <anonymous-schema-25>
        title: Unsubscribe_response
        example: No examples found
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: unsubscribe_response
          - id: x-parser-message-name
            value: unsubscribe_response
      - &ref_9
        id: update
        payload:
          - name: update
            type: object
            properties:
              - name: chain_id
                type: integer
                required: true
              - name: dataset_id
                type: string
                description: '0404'
                required: true
              - name: is_reorg
                type: boolean
                required: true
              - name: data
                type: object
                description: Mirrors blockdb_evm.b0404_token_to_token_prices_ohlc_v1
                required: true
                properties:
                  - name: pool_uid
                    type: string
                    required: false
                  - name: exchange_id
                    type: integer
                    required: false
                  - name: type_id
                    type: integer
                    required: false
                  - name: bucket_start
                    type: string
                    required: false
                  - name: bucket_end
                    type: string
                    required: false
                  - name: bucket_seconds
                    type: integer
                    required: false
                  - name: token_in
                    type: string
                    required: false
                  - name: token_out
                    type: string
                    required: false
                  - name: open
                    type: string
                    required: false
                  - name: high
                    type: string
                    required: false
                  - name: low
                    type: string
                    required: false
                  - name: close
                    type: string
                    required: false
                  - name: volume_in_raw
                    type: string
                    required: false
                  - name: volume_in
                    type: string
                    required: false
                  - name: volume_out_raw
                    type: string
                    required: false
                  - name: volume_out
                    type: string
                    required: false
                  - name: trades_count
                    type: integer
                    required: false
                  - name: _tracing_id
                    type: string
                    required: false
                  - name: _parent_tracing_ids
                    type: array
                    required: false
                    properties:
                      - name: item
                        type: string
                        required: false
                  - name: _created_at
                    type: string
                    required: false
                  - name: _updated_at
                    type: string
                    required: false
        headers: []
        jsonPayloadSchema:
          type: object
          properties:
            chain_id:
              type: integer
              x-parser-schema-id: <anonymous-schema-31>
            dataset_id:
              type: string
              const: '0404'
              x-parser-schema-id: <anonymous-schema-32>
            is_reorg:
              type: boolean
              x-parser-schema-id: <anonymous-schema-33>
            data:
              type: object
              description: Mirrors blockdb_evm.b0404_token_to_token_prices_ohlc_v1
              properties:
                pool_uid:
                  type: string
                  x-parser-schema-id: <anonymous-schema-35>
                exchange_id:
                  type: integer
                  x-parser-schema-id: <anonymous-schema-36>
                type_id:
                  type: integer
                  x-parser-schema-id: <anonymous-schema-37>
                bucket_start:
                  type: string
                  x-parser-schema-id: <anonymous-schema-38>
                bucket_end:
                  type: string
                  x-parser-schema-id: <anonymous-schema-39>
                bucket_seconds:
                  type: integer
                  x-parser-schema-id: <anonymous-schema-40>
                token_in:
                  type: string
                  x-parser-schema-id: <anonymous-schema-41>
                token_out:
                  type: string
                  x-parser-schema-id: <anonymous-schema-42>
                open:
                  type: string
                  x-parser-schema-id: <anonymous-schema-43>
                high:
                  type: string
                  x-parser-schema-id: <anonymous-schema-44>
                low:
                  type: string
                  x-parser-schema-id: <anonymous-schema-45>
                close:
                  type: string
                  x-parser-schema-id: <anonymous-schema-46>
                volume_in_raw:
                  type: string
                  x-parser-schema-id: <anonymous-schema-47>
                volume_in:
                  type: string
                  nullable: true
                  x-parser-schema-id: <anonymous-schema-48>
                volume_out_raw:
                  type: string
                  x-parser-schema-id: <anonymous-schema-49>
                volume_out:
                  type: string
                  nullable: true
                  x-parser-schema-id: <anonymous-schema-50>
                trades_count:
                  type: integer
                  x-parser-schema-id: <anonymous-schema-51>
                _tracing_id:
                  type: string
                  x-parser-schema-id: <anonymous-schema-52>
                _parent_tracing_ids:
                  type: array
                  items:
                    type: string
                    x-parser-schema-id: <anonymous-schema-54>
                  nullable: true
                  x-parser-schema-id: <anonymous-schema-53>
                _created_at:
                  type: string
                  x-parser-schema-id: <anonymous-schema-55>
                _updated_at:
                  type: string
                  x-parser-schema-id: <anonymous-schema-56>
              x-parser-schema-id: <anonymous-schema-34>
          required:
            - chain_id
            - dataset_id
            - is_reorg
            - data
          x-parser-schema-id: <anonymous-schema-30>
        title: Update
        example: No examples found
        bindings: []
        extensions:
          - id: x-parser-unique-object-id
            value: update
          - id: x-parser-message-name
            value: update
    bindings: []
    extensions: *ref_0
sendOperations:
  - *ref_2
  - *ref_3
receiveOperations:
  - *ref_4
sendMessages:
  - *ref_5
  - *ref_6
receiveMessages:
  - *ref_7
  - *ref_8
  - *ref_9
extensions:
  - id: x-parser-unique-object-id
    value: spot-ohlc
securitySchemes: []

````