The SQL API schema is a set of opinionated tables and columns used to organize onchain data for efficient retrieval.
Supported Tables
| Table | Description |
|---|
| base.blocks | Block metadata including timestamps, gas usage, and consensus fields |
| base.transactions | Transaction data including hash, block number, gas usage, and signatures |
| base.events | Decoded event logs with contract interactions on Base |
| base.encoded_logs | Encoded log data of event logs that aren’t able to be decoded by our event decoder (ex: log0 opcode) |
| base.decoded_user_operations | Decoded ERC-4337 user operations bundled into transactions |
| base.transaction_attributions | Builder/searcher attribution metadata for transactions |
base.blocks
Block metadata including timestamps, gas usage, and consensus fields.
See an example block on Basescan to understand how blockchain data corresponds to these SQL fields. | Field | Type | Description |
|---|
| block_number | UInt64 | The sequential number of the block in the chain |
| block_hash | String | The keccak256 hash of the block header |
| parent_hash | String | The keccak256 hash of the parent block header |
| timestamp | DateTime | The timestamp in UTC when the block was produced |
| miner | String | The address of the miner/validator who produced the block |
| nonce | UInt64 | The nonce used in the block proof-of-work (legacy, 0 post-merge) |
| sha3_uncles | String | The hash of the ommers/uncles list in the block |
| transactions_root | String | The root of the transaction trie of the block |
| state_root | String | The root of the state trie after the block |
| receipts_root | String | The root of the receipts trie of the block |
| logs_bloom | String | The bloom filter for log entries in the block |
| gas_limit | UInt64 | The maximum gas allowed in the block |
| gas_used | UInt64 | The total gas used by all transactions in the block |
| base_fee_per_gas | UInt64 | The base fee per gas in the block (EIP-1559) |
| total_difficulty | String | The total difficulty of the chain up to this block |
| size | UInt64 | The size of the block in bytes |
| extra_data | String | Arbitrary extra data included by the block producer |
| mix_hash | String | A hash used in the proof-of-work algorithm (legacy) |
| withdrawals_root | String | The root hash of the withdrawals trie (EIP-4895) |
| parent_beacon_block_root | String | The root of the parent beacon block (EIP-4788) |
| blob_gas_used | UInt64 | The total blob gas consumed by transactions in the block (EIP-4844) |
| excess_blob_gas | UInt64 | The running total of excess blob gas after this block (EIP-4844) |
| transaction_count | UInt64 | The number of transactions in the block |
| action | Int8 | Block state: 1=added to chain, -1=removed via re-org |
base.transactions
Transaction data including hash, block number, gas usage, and signatures.
See an example transaction on Basescan to understand how transaction data corresponds to these SQL fields. timestamp on base.blocks and base.transactions is DateTime (second precision, server timezone), while block_timestamp on base.events, base.encoded_logs, base.decoded_user_operations, and base.transaction_attributions is DateTime64(3, 'UTC') (millisecond precision, UTC). When joining or comparing timestamps across these tables, cast explicitly (for example, toDateTime64(timestamp, 3, 'UTC')) to avoid precision loss or timezone surprises.
| Field | Type | Description |
|---|
| block_number | UInt64 | The number of the block containing this transaction |
| block_hash | String | The hash of the block containing this transaction |
| transaction_hash | String | The keccak256 hash of the transaction |
| transaction_index | UInt64 | The index position of the transaction within the block |
| from_address | String | The address that sent the transaction (EOA) |
| to_address | String | The recipient address (EOA or contract). Empty for contract creation. |
| value | String | The value transferred in wei (decimal string) |
| gas | UInt64 | The gas limit provided by the sender |
| gas_price | UInt64 | The gas price in wei provided by the sender |
| input | String | The calldata sent with the transaction (hex-encoded) |
| nonce | UInt64 | The number of prior transactions from the sender |
| type | UInt64 | The EIP-2718 transaction type (0=legacy, 1=access list, 2=EIP-1559, 3=blob) |
| max_fee_per_gas | UInt64 | Maximum fee per gas the sender is willing to pay (EIP-1559) |
| max_priority_fee_per_gas | UInt64 | Maximum priority fee (tip) per gas for the validator (EIP-1559) |
| chain_id | UInt64 | The EIP-155 chain identifier |
| v | String | ECDSA signature recovery id |
| r | String | ECDSA signature r value |
| s | String | ECDSA signature s value |
| is_system_tx | Bool | Whether this is a system transaction (OP Stack) |
| max_fee_per_blob_gas | String | Maximum fee per blob gas the sender is willing to pay (EIP-4844) |
| blob_versioned_hashes | Array(String) | List of versioned blob hashes for blob transactions (EIP-4844) |
| timestamp | DateTime | The timestamp in UTC of the block containing this transaction |
| action | Int8 | Transaction state: 1=added to chain, -1=removed via re-org |
base.events
Decoded event logs with contract interactions on Base.
Schema changes: timestamp has been renamed to block_timestamp, and transaction_index has been removed. To retrieve a log’s transaction position within its block, join to base.transactions on transaction_hash and select transaction_index from there.
See example events on Basescan to see how event logs appear on the blockchain. | Field | Type | Description |
|---|
| log_id | String | A unique identifier for the log. It is derived from information inherent to the log, so if a log is processed multiple times, the unique log id will be the same. |
| block_number | UInt64 | The number of the block that the log is in |
| block_hash | FixedString(66) | The hash of the block that the log is in |
| block_timestamp | DateTime64(3, ‘UTC’) | The timestamp in UTC of the block that the log is in |
| transaction_hash | FixedString(66) | The hash of the transaction that the log is in |
| transaction_to | FixedString(42) | The address the transaction is acting against. Could be either an EOA (ex: ETH transfer) or a contract (ex: smart contract call). |
| transaction_from | FixedString(42) | The address that originated the transaction. Will be an EOA. |
| log_index | UInt32 | The index of the log within the transaction. First log is in the transaction at index 0, second is index 1, etc. |
| address | FixedString(42) | The address of the contract that the log was created from |
| topics | Array(FixedString(66)) | The topics of the log. Topics are the indexed parameters of the event and the keccak256 hash of the event signature. |
| event_name | LowCardinality(String) | The name of the event. Ex: Transfer |
| event_signature | LowCardinality(String) | The signature of the event. Ex: Transfer(address,address,uint256) |
| parameters | Map(String, Variant(Bool, Int256, String, UInt256)) | Map of parameter name to its value. Ex: {"from": "0x1234...", "to": "0x1234...", "value": "1000000000000000000"} |
| parameter_types | Map(String, String) | Map of parameter name to its ABI type |
| action | Enum8(‘removed’ = -1, ‘added’ = 1) | If the log is created, it is 1. If the log is re-orged out it is -1. If the sum of all actions for a given log is greater than 0, the log is “active”, meaning it is still in the chain (has not been re-orged out). |
base.encoded_logs
Encoded log data of event logs that aren’t able to be decoded by our event decoder (ex: log0 opcode).
| Field | Type | Description |
|---|
| log_id | String | A unique identifier for the log. It is derived from information inherent to the log, so if a log is processed multiple times, the unique log id will be the same. |
| block_number | UInt64 | The number of the block that the log is in |
| block_hash | FixedString(66) | The hash of the block that the log is in |
| block_timestamp | DateTime64(3, ‘UTC’) | The timestamp in UTC of the block that the log is in |
| transaction_hash | FixedString(66) | The hash of the transaction that the log is in |
| transaction_to | FixedString(42) | The address the transaction is acting against. Could be either an EOA (ex: ETH transfer) or a contract (ex: smart contract call). |
| transaction_from | FixedString(42) | The address that originated the transaction. Will be an EOA. |
| log_index | UInt32 | The index of the log within the transaction. First log is in the transaction at index 0, second is index 1, etc. |
| address | FixedString(42) | The address of the contract that the log was created from |
| topics | Array(FixedString(66)) | The topics of the log. Topics are the indexed parameters of the event and the keccak256 hash of the event signature. |
| action | Enum8(‘removed’ = -1, ‘added’ = 1) | If the log is created, it is 1. If the log is re-orged out it is -1. If the sum of all actions for a given log is greater than 0, the log is “active”, meaning it is still in the chain (has not been re-orged out). |
base.decoded_user_operations
Decoded ERC-4337 user operations bundled into Base transactions.
| Field | Type | Description |
|---|
| block_number | UInt64 | The number of the block containing the bundle transaction |
| block_timestamp | DateTime64(3, ‘UTC’) | The timestamp in UTC of the block containing the bundle transaction |
| transaction_hash | FixedString(66) | The hash of the bundle transaction containing the user operation |
| transaction_index | UInt32 | The index of the bundle transaction within the block |
| user_op_hash | FixedString(66) | The unique hash identifying the user operation |
| bundler | FixedString(42) | The address of the bundler that submitted the bundle transaction |
| entry_point | FixedString(42) | The address of the EntryPoint contract that executed the user operation |
| entry_point_version | LowCardinality(String) | The version of the EntryPoint contract (ex: v0.6, v0.7) |
| beneficiary | FixedString(42) | The address designated to receive the gas refund for the bundle |
| method_name | Enum8(‘handleOps’ = 1, ‘handleAggregatedOps’ = 2) | The EntryPoint method invoked to execute the bundle |
| method_signature | LowCardinality(String) | The full canonical signature of the invoked EntryPoint method |
| sender | FixedString(42) | The smart account address that originated the user operation |
| user_op_data | String | The raw, encoded user operation payload |
| actual_gas_cost | String | The actual gas cost paid for executing the user operation (decimal string in wei) |
| actual_gas_used | String | The actual amount of gas consumed by the user operation (decimal string) |
| success | Enum8(‘failure’ = 0, ‘success’ = 1) | Whether the user operation executed successfully |
| builder_codes | Array(LowCardinality(String)) | Builder attribution codes associated with the user operation |
| annotation_data | String | Additional annotation metadata for the user operation |
| action | Int8 | User operation state: 1=added to chain, -1=removed via re-org |
base.transaction_attributions
Builder/searcher attribution metadata for Base transactions.
| Field | Type | Description |
|---|
| builder_code | LowCardinality(String) | Identifier code attributing the transaction to a builder or searcher |
| block_timestamp | DateTime64(3, ‘UTC’) | The timestamp in UTC of the block containing the transaction |
| block_number | UInt64 | The number of the block containing the transaction |
| transaction_hash | FixedString(66) | The hash of the attributed transaction |
| transaction_index | UInt32 | The index of the attributed transaction within the block |
| action | Int8 | Attribution state: 1=added to chain, -1=removed via re-org |
| annotation_data | String | Additional annotation metadata for the attribution |
| ingested_at | DateTime64(3, ‘UTC’) | The timestamp in UTC when the attribution record was ingested |
