Run SQL Query

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/data/query/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sql": "SELECT block_number, transaction_hash FROM base.transactions WHERE block_number > 1000000 LIMIT 10",
  "cache": {
    "maxAgeMs": 1000
  }
}
'

{
  "result": [
    {
      "event_signature": "Transfer(address,address,uint256)",
      "from": "0x1234567890abcdef",
      "to": "0x1234567890abcdef",
      "amount": 1000000000000000000
    },
    {
      "event_signature": "Transfer(address,address,uint256)",
      "from": "0x1234567890abcdef",
      "to": "0x1234567890abcdef",
      "amount": 2000000000000000000
    }
  ],
  "schema": {
    "columns": [
      {
        "name": "block_number",
        "type": "UInt64"
      },
      {
        "name": "transaction_hash",
        "type": "String"
      }
    ]
  },
  "metadata": {
    "cached": false,
    "executionTimestamp": "2025-01-01T00:00:00.000Z",
    "executionTimeMs": 145,
    "rowCount": 2
  }
}

SQL API

Run SQL Query

Run a read-only SQL query against indexed blockchain data including transactions, events, and decoded logs.

This endpoint provides direct SQL access to comprehensive blockchain data across supported networks.

Queries are executed against optimized data structures for high-performance analytics.

Allowed Queries

Standard SQL syntax (CoinbaSeQL dialect, based on ClickHouse dialect)
Read-only queries (SELECT statements)
No DDL or DML operations
Query that follow limits (defined below)

Supported Networks

Base Mainnet: base
Base Sepolia: base_sepolia
Solana Mainnet: solana
Hyperevm Mainnet: hyperevm

Supported Tables

The below tables are supported for base and base_sepolia networks.

Table	Description
`<network>.events`	Decoded event logs with parameters, event signature, topics, and more.
`<network>.transactions`	Transaction data including hash, block number, and gas usage.
`<network>.blocks`	Block information.
`<network>.encoded_logs`	Encoded log data for event logs that cannot be decoded by our event decoder (ex: log0 opcode).
`<network>.decoded_user_operations`	Decoded user operations data including hash, block number, gas usage, builder codes, entrypoint version, and more.
`<network>.transaction_attributions`	Information about the attributions of a transaction to a builder and associated builder codes.

Following the above, the valid tables on Base Mainnet are base.events, base.transactions, base.blocks, base.encoded_logs, base.decoded_user_operations, and base.transaction_attributions.

Separately, there is a limited set of tables supported for solana and hyperevm networks:

Table	Description
`solana.instructions`	Solana instruction call data including program ID, instruction data, and more. Currently supports just Token2022 and SPL Token programs.
`hyperevm.events`	Hyperevm decoded event logs with parameters, event signature, topics, and more. Currently supports just B20 events.

Query Limits

Maximum result set: 50,000 rows
Maximum query length: 10,000 characters
Maximum on-disk data to read: 100GB
Maximum memory usage: 15GB
Query timeout: 30 seconds
Maximum JOINs: 12

Query Caching

By default, each query result is returned from cache so long as the result is from an identical query and less than 750ms old. This freshness tolerance can be modified upwards, to a maximum of 900000ms (i.e. 900s, 15m). This can be helpful for users who wish to reduce expensive calls to the SQL API by reusing cached results.

POST

data

query

run

Run SQL Query

curl --request POST \
  --url https://api.cdp.coinbase.com/platform/v2/data/query/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sql": "SELECT block_number, transaction_hash FROM base.transactions WHERE block_number > 1000000 LIMIT 10",
  "cache": {
    "maxAgeMs": 1000
  }
}
'

{
  "result": [
    {
      "event_signature": "Transfer(address,address,uint256)",
      "from": "0x1234567890abcdef",
      "to": "0x1234567890abcdef",
      "amount": 1000000000000000000
    },
    {
      "event_signature": "Transfer(address,address,uint256)",
      "from": "0x1234567890abcdef",
      "to": "0x1234567890abcdef",
      "amount": 2000000000000000000
    }
  ],
  "schema": {
    "columns": [
      {
        "name": "block_number",
        "type": "UInt64"
      },
      {
        "name": "transaction_hash",
        "type": "String"
      }
    ]
  },
  "metadata": {
    "cached": false,
    "executionTimestamp": "2025-01-01T00:00:00.000Z",
    "executionTimeMs": 145,
    "rowCount": 2
  }
}

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Body

application/json

Request to execute a SQL query against indexed blockchain data.

sql

string

required

SQL query to execute against the indexed blockchain data.

Required string length: 1 - 100000

Example:

"SELECT block_number, transaction_hash FROM base.transactions WHERE block_number > 1000000 LIMIT 10"

cache

Query result cache configuration · object

Enables control over how often queries need to be fully re-executed on the backing store. This can be useful in scenarios where API calls might be made frequently, API latency is critical, and some freshness lag (ex: 750ms, 2s, 5s) is tolerable. By default, each query result is returned from cache so long as the result is from an identical query and less than 500ms old. This freshness tolerance can be modified upwards, to a maximum of 900000ms (i.e. 900s, 15m).

Show child attributes

Example:

{ "maxAgeMs": 1000 }

Response

Query run successfully.

Result of executing a SQL query.

result

object[]

Query result as an array of objects representing rows.

Example:

[
  {
    "event_signature": "Transfer(address,address,uint256)",
    "from": "0x1234567890abcdef",
    "to": "0x1234567890abcdef",
    "amount": 1000000000000000000
  },
  {
    "event_signature": "Transfer(address,address,uint256)",
    "from": "0x1234567890abcdef",
    "to": "0x1234567890abcdef",
    "amount": 2000000000000000000
  }
]

schema

object

Schema information for the query result. This is a derived schema from the query result, so types may not match the underlying table.

Show child attributes

Example:

{
  "columns": [
    { "name": "block_number", "type": "UInt64" },
    {
      "name": "transaction_hash",
      "type": "String"
    }
  ]
}

metadata

object

Metadata about query execution.

Show child attributes

Example:

{
  "cached": false,
  "executionTimestamp": "2025-01-01T00:00:00.000Z",
  "executionTimeMs": 145,
  "rowCount": 2
}

Get SQL grammar

Webhooks

⌘I