Explore the standardized unified format for events across various protocols and networks.
Events sent are formatted using the UNIFIED_V1
schema, which is a standardized format across all supported protocols and networks. This section will provide more details on the UNIFIED_V1
schema for each supported event type.
Info:
The
UNIFIED_V1
format is currently still in development. Some fields might still be subject to change.
This section contains the unified format that is available in the Event Streaming:
1. Standardized Envelope
All events produced by Event Streaming will be produced in a standardized envelope. Below is an example of the structure:
{
"protocol":"bitcoin",
"network":"mainnet",
"event_type":"unified_confirmed_balance",
"data": {}
}
Schema
Field | Type | Description |
---|---|---|
protocol | string | The blockchain protocol. |
network | string | The blockchain network. |
event_type | string | The name/type of the event. |
data | object | The event payload. |
2. unified_block
This event is triggered when:
- A customer has a rule using the
event_type
as a variable type, with the variable set toblock
. - A new
block
is mined or validated on the blockchain.
See the example below:
{
"protocol": "bitcoin",
"network": "mainnet",
"event_type": "unified_block",
"data": {
"block_hash": "0000000000000000000278b53131091627eaa00f772f3c7b2a59c374666520d7",
"block_number": 831663,
"block_timestamp": 1708679008,
"parent_hash": "00000000000000000001030ba3d1016bd94e4c48b90b3fd64d1b18bdb29c4f6f"
}
}
Schema
Field | Type | Description |
---|---|---|
block_hash | string | The block hash. |
block_number | integer | The block number. |
block_timestamp | integer | The UNIX timestamp when the block was mined/validated. |
parent_hash | string | The hash of the parent block. |
3. unified_confirmed_balance
This event is sent under the following conditions:
- Balance events are emitted once per block whenever a balance changes.
- Balances are emitted per asset, per address, and per block. If multiple transactions within the same block change a balance, the balance event reflects all changes in a single event.
- A customer must have a rule with the
address
variable type and the variable must contain the address of the balance as its value.
See the example below:
{
"event_type": "unified_confirmed_balance",
"protocol": "bitcoin",
"network": "mainnet",
"data": {
"block_number": 831401,
"block_hash": "0000000000000000000004264eb2cfa81bdd04998932e960644fa979030f5fda",
"block_timestamp": 1708519012,
"address": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
"value": 1118789134970,
"asset":"native"
}
}
Schema
Field | Type | Description |
---|---|---|
block_hash | string | The block hash. |
block_number | integer | The block number. |
block_timestamp | integer | The UNIX timestamp when the block was mined/validated. |
address | string | The account address. This matches the address in a customer’s variable values for the address variable type. |
asset | string | The asset type of the balance. - For native tokens like ETH for Ethereum, the asset will be set to native .- For non-native tokens like ERC20 tokens will have their specific denomination. |
value | integer | The value of the balance for the address and asset at this block height. The value is in the lowest denomination of the asset. For example: - For ETH , the value is in wei .- For BTC , the value is in satoshi . |
4. unified_confirmed_tx
This event is sent when:
- A new transaction is mined.
- A customer has a rule with the
address
variable type and the variable contains the address of the transaction as its value. The address could be the sender or the recipient of any transfers during the transaction.
See the example below:
{
"protocol": "bitcoin",
"network": "mainnet",
"event_type": "unified_confirmed_tx",
"data": {
"block_number": 831386,
"block_hash": "0000000000000000000157bdde026859b310ba79f905f1514f022d1dd6129a00",
"tx_id": "77d80eb55bc1e99db7617c5b508452306e7049a54e7ec398a25a293339077763",
"txn_hash": "8dc10b4e32f1d0900e8786cd81875190533c2dc4310a360116409e26a700f19e",
"timestamp": 1233321795,
"status": "success",
"transfers": [
{
"asset": "native",
"from": "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
"value": 22349655,
"event_name": "vin"
},
{
"asset": "native",
"from": "bc1qxrzs7r49zhg6nhpxntzl0u4en2svksw4ynfp8h",
"value": 497411,
"event_name": "vout"
},
{
"asset": "native",
"from": "bc1qzxcunle4hems53uehszlq84fn5cm6ejekd7f0e",
"value": 2288371,
"event_name": "vout"
},
{
"asset": "native",
"from": "bc1qjc0cejltt57te78akwsc5ckuz250czp20r8y52",
"value": 77420,
"event_name": "vout"
},
{
"asset": "native",
"from": "bc1qe8l0s5ktdhpnys388xtt5vd0em8j38h7ktse4q",
"value": 60000,
"event_name": "vout"
}
],
"fee": 27850
}
}
Schema
Field | Type | Description |
---|---|---|
block_hash | string | The block hash. |
block_number | integer | The block number. |
block_timestamp | integer | The UNIX timestamp when the block was mined/validated. |
tx_id | string | The transaction identifier, such as the transaction hash or other unique identifier. |
tx_hash | string | The transaction hash. This only applies to Bitcoin, where transactions have an ID and a hash that might not always be the same value. |
status | string | The status of the transaction when available. The default status for successful transactions is completed and failed for failed transactions. |
transfers | array of transfer | An array of transfers took place during the transaction. See the Transfer schema for reference. |
fee | object | The fee paid for this transaction. The default value is Transfer , but some protocols like Ethereum use their object to represent the fee. |
Each protocol can use its fee object to denote the fee paid for a transaction. Currently, we denote two ways to denote the fee:
Type | Description | Protocol/Network |
---|---|---|
Transfer | Represents transfers of assets. | bitcoin/mainnet bitcoin/testnet polkadot/mainnet polkadot/westend |
EVMFee | Represents fees on EVM based chains. | ethereum/mainnet ethereum/holesky polygon/mainnet polygon/testnet |
Transfer Schema
Field | Type | Description |
---|---|---|
asset | string | The asset type of the balance. - For native tokens like Ethereum, the asset will be set to "native". - For non-native tokens will have their denomination. |
value | integer | The value transferred. The value is in the lowest denomination of the asset. For example: - For ETH, the value is in wei .- For BTC, the value is in satoshi . |
from | string | The sender's account address. |
to | string | The recipient's account address. |
event_name | string | A protocol-specific name for the transfer (if applicable). This field can provide more information on the type of transfer. For example, Bitcoin will set this to vin for inputs and vout for outputs. |
EVMFee Schema
Field | Type | Description |
---|---|---|
gas_used | integer | The amount of gas used for the transaction. |
gas_price | integer | The gas price. |
gas_limit | integer | The gas limit. |
value | integer | The fee value. The value is in the lowest denomination of the asset. For example: - For ETH, the value is in wei .- For BTC, the value is in satoshi . |
max_fee_per_gas | integer | The maximum fee per gas set for this transaction. |
max_priority_fee_per_gas | integer | The maximum priority fee per gas set for this transaction. |
👋 Need Help?
Contact us through email or our support page for any issues, bugs, or assistance you may need.