Skip to main content
WSS
Messages
subscribe
type:object
unsubscribe
type:object
subscribe_response
type:object
unsubscribe_response
type:object
update
type:object

​
Overview

​
Subscription Parameters

​
chain_id
number
required
Target EVM network. See the Chain enumeration for supported values.
​
from_addresses
string[]
Filter by sender address (20 bytes, hex string, no 0x prefix).
​
to_addresses
string[]
Filter by recipient address (20 bytes, hex string, no 0x prefix).
​
status_success
boolean
Filter by execution status (true = success, false = revert).

​
Message Fields

​
tx_hash
string
Keccak-256 hash of the transaction (hex string, 32 bytes, no 0x prefix).
​
block_number
number
Block height containing the transaction.
​
block_time
string
UTC timestamp of the block (ISO-8601).
​
tx_index
number
Zero-based index of the transaction within the block.
​
from_address
string
Sender address (hex string, 20 bytes, no 0x prefix).
​
to_address
string | null
Recipient address (hex string, 20 bytes, no 0x prefix). null for contract creation.
​
created_contract_address
string | null
Address of the contract created by this transaction. null for non-creation transactions.
​
gas_used
string
Gas consumed by the transaction (string to preserve NUMERIC(78) precision).
​
effective_gas_price_wei
string
Effective gas price paid in wei (string to preserve NUMERIC(78) precision).
​
status_success
boolean
Execution status: true = success, false = revert, null for pre-Byzantium blocks.
​
root
string | null
Pre-Byzantium: state root after tx execution; null for Byzantium+.
​
tx_type
number
Transaction type identifier (e.g., 2 = EIP-1559, 1 = legacy).
​
trace_failed
boolean | null
true if trace failed, false if trace succeeded, null if trace not available.
​
value_wei
string
Value transferred in wei (string to preserve NUMERIC precision).
​
input
string
Calldata sent with the transaction (hex string, no 0x prefix).
​
nonce
number
Sender nonce.
​
gas_limit
string
Gas limit provided by the sender (string to preserve NUMERIC precision).
​
gas_price_wei
string
Gas price in wei (legacy, string to preserve NUMERIC precision).
​
max_fee_per_gas_wei
string
Max fee per gas in wei (EIP-1559, string to preserve NUMERIC precision).
​
max_priority_fee_per_gas_wei
string
Max priority fee per gas in wei (EIP-1559, string to preserve NUMERIC precision).
​
_tracing_id
string
Tracing identifier for cross-referencing with other datasets.
​
_created_at
string
Record creation timestamp.
​
_updated_at
string
Record last update timestamp.

​
Subscription Example

# 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": "0102", "chain_id": 1, "params": {"status_success": true}}'

​
Response Example

{
  "chain_id": 1,
  "dataset_id": "0102",
  "is_reorg": false,
  "data": {
    "block_number": 12345678,
    "block_time": "2025-11-11T18:42:15.123Z",
    "tx_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
    "tx_index": 4,
    "from_address": "0000000000000000000000000000000000000000",
    "to_address": "0000000000000000000000000000000000000001",
    "created_contract_address": null,
    "gas_used": "21000",
    "effective_gas_price_wei": "1234567890123456789",
    "status_success": true,
    "root": null,
    "tx_type": 2,
    "trace_failed": null,
    "value_wei": "0",
    "input": "",
    "nonce": 1,
    "gas_limit": "21000",
    "gas_price_wei": "1234567890123456789",
    "max_fee_per_gas_wei": "0",
    "max_priority_fee_per_gas_wei": "0",
    "_tracing_id": "010200000000000000000000000000000000",
    "_created_at": "2025-11-11T18:42:15.123Z",
    "_updated_at": "2025-11-11T18:42:15.123Z"
  }
}
Last modified on April 6, 2026