Schema Reference

Here you'll find a breakdown of the schemas used throughout the L3 Atom data lake. We'll provide both human-readable tables that outline what each field represents, as well as equivalent Apache Avro schemas.

Notes

• A value of -1 indicates that the value is unknown

• The exact format of the event_timestamp depends on the source. In our PostgreSQL database, it's a timestamp (integer for the number of milliseconds since the UNIX epoch), however over the websocket API you will be given an ISO-formatted string

  • Why? This is to give as many options to you as possible. The atom_timestamp will always a be an integer value of the number of microseconds since the UNIX epoch, but you might find it more useful to have a timestamp in an ISO format instead. Having a millisecond and microsecond timestamp also means that we can use the data in a variety of different datastores which may have different conventions for what timestmaps should be. For most people, given that the timestamps are very close, they can be used interchangeably, however there may be use cases that want to compare them (e.g. determining latency between exchanges)

• Some exchanges don't provide an explicit event_timestamp. In those cases, we just convert the atom_timestamp into milliseconds as the next best thing. These cases will be specifically mentioned.

• Open interest can differ wildly between exchanges. This is mainly due to inconsistencies in formatting. Some exchanges provide OI in USD, while others provide it in the base/quote token. Because of this, open interest values should most likely not be aggregated across exchanges as you may see unexpected results.

Tables

L3 Trades

Name	Type	Description
exchange	string	Exchange the event occurred on
symbol	string	The symbol of the event
price	double	The price of the trade
size	double	The size of the trade
taker_side	string	What side the market taker was on (buy/sell)
trade_id	string	ID of the trade (if provided)
maker_order_id	string	ID of the market maker's order
taker_order_id	string	ID of the market taker's order
event_timestamp	timestamp (milliseconds)	Timestamp of when the event occurred on the exchange (milliseconds)
atom_timestamp	long	Timestamp of when the event was received by us (microseconds)

L2 Trades

Name	Type	Description
string	Exchange the event occurred on	exchange
string	The symbol of the event	symbol
double	The price of the trade	price
double	The size of the trade	size
string	What side the market taker was on (buy/sell)	taker_side
string	ID of the trade (if provided)	trade_id
timestamp (milliseconds)	Timestamp of when the event occurred on the exchange (milliseconds)	event_timestamp
long	Timestamp of when the event was received by us (microseconds)	atom_timestamp

Ticker

Name	Type	Description
exchange	string	Exchange the event occurred on
symbol	string	The symbol of the event
bid_price	double	Price of the best bid on the order book
bid_size	double	Size of the best bid on the order book
ask_price	double	Price of the best ask on the order book
ask_size	double	Size of the best askon the order book
event_timestamp	timestamp (milliseconds)	Timestamp of when the event occurred on the exchange (milliseconds)
atom_timestamp	long	Timestamp of when the event was received by us (microseconds)

L3 LOB

Name	Type	Description
exchange	string	Exchange the event occurred on
symbol	string	The symbol of the event
price	double	Price of the order
size	double	Size of the order
side	string	Side of the order (buy/sell)
order_id	string	ID of the order
event_timestamp	timestamp (milliseconds)	Timestamp of when the event occurred on the exchange (milliseconds)
atom_timestamp	long	Timestamp of when the event was received by us (microseconds)

L2 LOB

Name	Type	Description
exchange	string	Exchange the event occurred on
symbol	string	The symbol of the event
price	double	Price of the order
size	double	Size of the order
side	string	Side of the order (buy/sell)
event_timestamp	timestamp (milliseconds)	Timestamp of when the event occurred on the exchange (milliseconds)
atom_timestamp	long	Timestamp of when the event was received by us (microseconds)

Funding Rate

Name	Type	Description
exchange	string	Exchange the event occurred on
symbol	string	The symbol of the event
mark_price	double	Value of the mark price
funding_rate	double	The current funding rate
next_funding_time	timestamp (milliseconds)	The timestamp of the next funding
predicted_rate	double	The predicted funding rate at the next funding time
event_timestamp	timestamp (milliseconds)	Timestamp of when the event occurred on the exchange (milliseconds)
atom_timestamp	long	Timestamp of when the event was received by us (microseconds)

Open Interest

Name	Type	Description
exchange	string	Exchange the event occurred on
symbol	string	The symbol of the event
open_interest	double	The current open interest
event_timestamp	timestamp (milliseconds)	Timestamp of when the event occurred on the exchange (milliseconds)
atom_timestamp	long	Timestamp of when the event was received by us (microseconds)

Candle

Name	Type	Description
exchange	string	Exchange the event occurred on
symbol	string	The symbol of the event
start	timestamp (milliseconds)	The timestamp of when the candle started
end	timestamp (milliseconds)	The timestamp of when the candle ended
interval	string	The interval of the candle (e.g. "1m")
trades	int	How many trades occurred during the candle period (if provided)
closed	boolean	If the candle is closed or not
o	double	The open price of the candle
h	double	The high price of the candle
l	double	The low price of the candle
c	double	The close price of the candle
v	double	The volume of trades during the candle's period
event_timestamp	timestamp (milliseconds)	Timestamp of when the event occurred on the exchange (milliseconds)
atom_timestamp	long	Timestamp of when the event was received by us (microseconds)

Ethereum Blocks

Name	Type	Description
number	long	Block number
hash	string	Hash of the block
parentHash	string	Hash of the parent block
nonce	string	Hash of the generated proof-of-work
sha3Uncles	string	SHA3 of the uncles data in the block
logsBloom	string	The bloom filter for the logs of the block
transactionsRoot	string	The root of the transaction trie of the block
stateRoot	string	The root of the final state trie of the block
receiptsRoot	string	The root of the receipts trie of the block
miner	string	Address of the block's miner
difficulty	long	The difficulty of the block
totalDifficulty	decimal (38 precision, 0 scale)	Total difficulty of the chain until the block
extraData	string	The "extra data" field of the block
size	long	Size of the block in bytes
gasLimit	decimal (38 precision, 0 scale)	Maximum gas allowed in this block
gasUsed	decimal (38 precision, 0 scale)	Total used gas by all transactions in this block
timestamp	timestamp (milliseconds)	Timestamp of when the block was collated
atomTimestamp	long	Timestamp of when we received the block

Ethereum Transactions

Name	Type	Description
blockNumber	long	Number of the associated block
hash	string	Hash of the transaction
blockHash	string	Hash of the associated block
nonce	string	The number of transactions made by the sender prior to this one
transactionIndex	long	The transaction's index position in the block
fromAddr	string	Address of the sender
toAddr	string	The root of the transaction trie of the block
value	decimal (38 precision, 0 scale)	Value transferred in Wei
gas	long	Gas provided by the sender
gasPrice	long	Gas price provided by the sender in Wei
input	string	The data sent along with the transaction
maxFeePerGas	long	maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Only for EIP-1559 transactions
maxPriorityFeePerGas	long	Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Only for EIP-1559 transactions
type	string	The transaction type
blockTimestamp	timestamp (milliseconds)	Timestamp of when the associated block was collated
atomTimestamp	long	Timestamp of when we received the transaction

Ethereum Logs

Name	Type	Description
blockNumber	long	Number of the associated block
transactionHash	string	Hash of the associated transaction
blockHash	string	Hash of the associated block
address	string	Address of the log's contract
transactionIndex	long	The associated transaction's index position in the block
logIndex	long	Log index position in the block
data	string	One or more 32 Bytes non-indexed arguments of the log
topic0	string	Indexed argument 0. In Solidity, the hash of the event signature.
topic1	string	Indexed argument 1
topic2	string	Indexed argument 2
topic3	string	Indexed argument 3
blockTimestamp	timestamp (milliseconds)	Timestamp of when the associated block was collated
atomTimestamp	long	Timestamp of when we received the log

Ethereum Token Transfers

Name	Type	Description
blockNumber	long	Number of the associated block
transactionHash	string	Hash of the associated transaction
blockHash	string	Hash of the associated block
tokenAddr	string	Address of the token transferred
fromAddr	string	Address of the sender
toAddr	string	Address of the receiver
value	decimal (38 precision, 0 scale)	Raw value of the transfer
blockTimestamp	timestamp (milliseconds)	Timestamp of when the associated block was collated
atomTimestamp	long	Timestamp of when we received the log

Dex Trades

Name	Type	Description
blockNumber	long	Number of the associated block
transactionHash	string	Hash of the associated transaction
blockHash	string	Hash of the associated block
logIndex	long	Index of the associated log in the block
exchange	string	Exchange the trade occurred on
maker	string	Address of the market maker (if the DEX has market makers for specific trades)
taker	string	Address of the market taker
tokenBought	string	Symbol of the bought token
tokenSold	string	Symbol of the sold token
tokenBoughtAddr	string	Contract address of the bought token
tokenSoldAddr	string	Contract address of the sold token
amountBought	decimal (38 precision, 24 scale)	Amount bought in the trade (the true value, accounting for the decimals of the token)
amountSold	decimal (38 precision, 24 scale)	Amount sold in the trade (the true value, accounting for the decimals of the token)
pairAddr	string	Address of the pair for the specific protocol
blockTimestamp	timestamp (milliseconds)	Timestamp of when the associated block was collated
atomTimestamp	long	Timestamp of when we received the trade event

Dex Liquidity

Name	Type	Description
blockNumber	long	Number of the associated block
transactionHash	string	Hash of the associated transaction
blockHash	string	Hash of the associated block
logIndex	long	Index of the associated log in the block
exchange	string	Exchange the trade occurred on
eventType	string ('add', 'remove')	Whether the liquidity event added liquidity ('add') or removed liquidity ('remove')
token0	string	Symbol of the first token in the pool
token1	string	Symbol of the second token in the pool
token0Addr	string	Contract address of the first token
token1Addr	string	Contract address of the second token
amount0	decimal (38 precision, 24 scale)	Amount of the first token added / removed (the true value, accounting for the decimals of the token)
amount1	decimal (38 precision, 24 scale)	Amount of the second token added / removed (the true value, accounting for the decimals of the token)
owner	string	Owner of the liquidity pool
pairAddr	string	Address of the pair for the specific protocol
blockTimestamp	timestamp (milliseconds)	Timestamp of when the associated block was collated
atomTimestamp	long	Timestamp of when we received the trade event

Avro

L3 Trades

{
    "type": "record",
    "name": "L3_Trades",
    "namespace": "com.acme.avro",
    "fields": [
        {
            "name": "exchange",
            "type": "string"
        },
        {
            "name": "symbol",
            "type": "string"
        },
        {
            "name": "price",
            "type": "double"
        },
        {
            "name": "size",
            "type": "double"
        },
        {
            "name": "taker_side",
            "type": "string"
        },
        {
            "name": "trade_id",
            "type": "string"
        },
        {
            "name": "maker_order_id",
            "type": "string"
        },
        {
            "name": "taker_order_id",
            "type": "string"
        },
        {
            "name": "event_timestamp",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "atom_timestamp",
            "type": "long"
        }
    ]
}

L2 Trades

{
    "type": "record",
    "name": "Trade",
    "namespace": "com.acme.avro",
    "fields": [
        {
            "name": "exchange",
            "type": "string"
        },
        {
            "name": "symbol",
            "type": "string"
        },
        {
            "name": "price",
            "type": "double"
        },
        {
            "name": "size",
            "type": "double"
        },
        {
            "name": "taker_side",
            "type": "string"
        },
        {
            "name": "trade_id",
            "type": "string"
        },
        {
            "name": "event_timestamp",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "atom_timestamp",
            "type": "long"
        }
    ]
}

Ticker

{
    "type": "record",
    "name": "Ticker",
    "namespace": "com.acme.avro",
    "fields": [
        {
            "name": "exchange",
            "type": "string"
        },
        {
            "name": "symbol",
            "type": "string"
        },
        {
            "name": "bid_price",
            "type": "double"
        },
        {
            "name": "bid_size",
            "type": "double"
        },
        {
            "name": "ask_price",
            "type": "double"
        },
        {
            "name": "ask_size",
            "type": "double"
        },
        {
            "name": "event_timestamp",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "atom_timestamp",
            "type": "long"
        }
    ]
}

L3 LOB

{
    "type": "record",
    "name": "L3_LOB",
    "namespace": "com.acme.avro",
    "fields": [
        {
            "name": "exchange",
            "type": "string"
        },
        {
            "name": "symbol",
            "type": "string"
        },
        {
            "name": "price",
            "type": "double"
        },
        {
            "name": "size",
            "type": "double"
        },
        {
            "name": "side",
            "type": "string"
        },
        {
            "name": "order_id",
            "type": "string"
        },
        {
            "name": "event_timestamp",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "atom_timestamp",
            "type": "long"
        }
    ]
}

L2 LOB

{
    "type": "record",
    "name": "LOB",
    "namespace": "com.acme.avro",
    "fields": [
        {
            "name": "exchange",
            "type": "string"
        },
        {
            "name": "symbol",
            "type": "string"
        },
        {
            "name": "price",
            "type": "double"
        },
        {
            "name": "size",
            "type": "double"
        },
        {
            "name": "side",
            "type": "string"
        },
        {
            "name": "event_timestamp",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "atom_timestamp",
            "type": "long"
        }
    ]
}

Funding Rate

{
    "type": "record",
    "name": "funding_rate",
    "namespace": "com.acme.avro",
    "fields": [
        {
            "name": "exchange",
            "type": "string"
        },
        {
            "name": "symbol",
            "type": "string"
        },
        {
            "name": "mark_price",
            "type": "double"
        },
        {
            "name": "funding_rate",
            "type": "double"
        },
        {
            "name": "next_funding_time",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "predicted_rate",
            "type": "double"
        },
        {
            "name": "event_timestamp",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "atom_timestamp",
            "type": "long"
        }
    ]
}

Open Interest

{
    "type": "record",
    "name": "open_interest",
    "namespace": "com.acme.avro",
    "fields": [
        {
            "name": "exchange",
            "type": "string"
        },
        {
            "name": "symbol",
            "type": "string"
        },
        {
            "name": "open_interest",
            "type": "double"
        },
        {
            "name": "event_timestamp",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "atom_timestamp",
            "type": "long"
        }
    ]
}

Candle

{
    "type": "record",
    "name": "Candle",
    "namespace": "com.acme.avro",
    "fields": [
        {
            "name": "exchange",
            "type": "string"
        },
        {
            "name": "symbol",
            "type": "string"
        },
        {
            "name": "start",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "end",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "interval",
            "type": "string"
        },
        {
            "name": "trades",
            "type": "int"
        },
        {
            "name": "closed",
            "type": "boolean"
        },
        {
            "name": "o",
            "type": "double"
        },
        {
            "name": "h",
            "type": "double"
        },
        {
            "name": "l",
            "type": "double"
        },
        {
            "name": "c",
            "type": "double"
        },
        {
            "name": "v",
            "type": "double"
        },
        {
            "name": "event_timestamp",
            "type": {
                "type": "long",
                "logicalType": "timestamp-millis"
            }
        },
        {
            "name": "atom_timestamp",
            "type": "long"
        }
    ]
}

Ethereum Blocks

{
  "doc": "Blocks on the Ethereum Chain.",
  "fields": [
    {
      "name": "atomTimestamp",
      "type": "long"
    },
    {
      "name": "number",
      "type": "long"
    },
    {
      "name": "hash",
      "type": "string"
    },
    {
      "name": "parentHash",
      "type": "string"
    },
    {
      "name": "nonce",
      "type": "string"
    },
    {
      "name": "sha3Uncles",
      "type": [
        "string",
        "null"
      ]
    },
    {
      "name": "logsBloom",
      "type": [
        "string",
        "null"
      ]
    },
    {
      "name": "transactionsRoot",
      "type": [
        "string",
        "null"
      ]
    },
    {
      "name": "stateRoot",
      "type": [
        "string",
        "null"
      ]
    },
    {
      "name": "receiptsRoot",
      "type": [
        "string",
        "null"
      ]
    },
    {
      "name": "miner",
      "type": "string"
    },
    {
      "name": "difficulty",
      "type": "long"
    },
    {
      "name": "totalDifficulty",
      "type": {
        "logicalType": "decimal",
        "precision": 38,
        "scale": 0,
        "type": "bytes"
      }
    },
    {
      "name": "extraData",
      "type": [
        "string",
        "null"
      ]
    },
    {
      "name": "size",
      "type": "long"
    },
    {
      "name": "gasLimit",
      "type": {
        "logicalType": "decimal",
        "precision": 38,
        "scale": 0,
        "type": "bytes"
      }
    },
    {
      "name": "gasUsed",
      "type": {
        "logicalType": "decimal",
        "precision": 38,
        "scale": 0,
        "type": "bytes"
      }
    },
    {
      "name": "blockTimestamp",
      "type": {
        "logicalType": "timestamp-millis",
        "type": "long"
      }
    }
  ],
  "name": "ethereum_blocks",
  "namespace": "com.mycorp.mynamespace",
  "type": "record"
}

Ethereum Transactions

{
  "doc": "Ethereum Transaction Objects",
  "fields": [
    {
      "name": "atomTimestamp",
      "type": "long"
    },
    {
      "name": "blockTimestamp",
      "type": {
        "logicalType": "timestamp-millis",
        "type": "long"
      }
    },
    {
      "name": "hash",
      "type": "string"
    },
    {
      "name": "nonce",
      "type": "string"
    },
    {
      "name": "blockHash",
      "type": "string"
    },
    {
      "name": "blockNumber",
      "type": "long"
    },
    {
      "name": "transactionIndex",
      "type": "long"
    },
    {
      "name": "fromAddr",
      "type": "string"
    },
    {
      "name": "toAddr",
      "type": [
        "string",
        "null"
      ]
    },
    {
      "name": "value",
      "type": {
        "logicalType": "decimal",
        "precision": 38,
        "scale": 0,
        "type": "bytes"
      }
    },
    {
      "name": "gas",
      "type": "long"
    },
    {
      "name": "gasPrice",
      "type": "long"
    },
    {
      "name": "input",
      "type": "string"
    },
    {
      "name": "maxFeePerGas",
      "type": [
        "long",
        "null"
      ]
    },
    {
      "name": "maxPriorityFeePerGas",
      "type": [
        "long",
        "null"
      ]
    },
    {
      "name": "type",
      "type": "string"
    }
  ],
  "name": "ethereum_transactions",
  "namespace": "com.mycorp.mynamespace",
  "type": "record"
}

Ethereum Logs

{
  "doc": "Logs for Ethereum Events",
  "fields": [
    {
      "name": "atomTimestamp",
      "type": "long"
    },
    {
      "name": "blockTimestamp",
      "type": {
        "logicalType": "timestamp-millis",
        "type": "long"
      }
    },
    {
      "name": "logIndex",
      "type": "long"
    },
    {
      "name": "transactionIndex",
      "type": "long"
    },
    {
      "name": "transactionHash",
      "type": "string"
    },
    {
      "name": "blockHash",
      "type": "string"
    },
    {
      "name": "blockNumber",
      "type": "long"
    },
    {
      "name": "address",
      "type": "string"
    },
    {
      "name": "data",
      "type": "string"
    },
    {
      "name": "topic0",
      "type": [
        "null",
        "string"
      ]
    },
    {
      "name": "topic1",
      "type": [
        "null",
        "string"
      ]
    },
    {
      "name": "topic2",
      "type": [
        "null",
        "string"
      ]
    },
    {
      "name": "topic3",
      "type": [
        "null",
        "string"
      ]
    }
  ],
  "name": "ethereum_logs",
  "namespace": "com.mycorp.mynamespace",
  "type": "record"
}

Ethereum Token Transfers

{
  "doc": "Ethereum Token Transfer Objects",
  "fields": [
    {
      "name": "atomTimestamp",
      "type": "long"
    },
    {
      "name": "blockTimestamp",
      "type": {
        "logicalType": "timestamp-millis",
        "type": "long"
      }
    },
    {
      "name": "tokenAddr",
      "type": "string"
    },
    {
      "name": "fromAddr",
      "type": "string"
    },
    {
      "name": "toAddr",
      "type": "string"
    },
    {
      "name": "value",
      "type": {
        "logicalType": "decimal",
        "precision": 38,
        "scale": 0,
        "type": "bytes"
      }
    },
    {
      "name": "transactionHash",
      "type": "string"
    },
    {
      "name": "logIndex",
      "type": "long"
    },
    {
      "name": "blockNumber",
      "type": "long"
    },
    {
      "name": "blockHash",
      "type": "string"
    }
  ],
  "name": "ethereum_token_transfers",
  "namespace": "com.mycorp.mynamespace",
  "type": "record"
}

Dex Trades

{
  "doc": "Trades that occur on Ethereum DEXes",
  "fields": [
    {
      "name": "atomTimestamp",
      "type": "long"
    },
    {
      "name": "blockTimestamp",
      "type": {
        "logicalType": "timestamp-millis",
        "type": "long"
      }
    },
    {
      "name": "exchange",
      "type": "string"
    },
    {
      "name": "maker",
      "type": [
        "null",
        "string"
      ]
    },
    {
      "name": "taker",
      "type": [
        "null",
        "string"
      ]
    },
    {
      "name": "tokenBought",
      "type": "string"
    },
    {
      "name": "tokenSold",
      "type": "string"
    },
    {
      "name": "tokenBoughtAddr",
      "type": "string"
    },
    {
      "name": "tokenSoldAddr",
      "type": "string"
    },
    {
      "name": "amountBought",
      "type": {
        "logicalType": "decimal",
        "precision": 38,