Schema Reference

Openmesh APIs is currently under development, information here pertains to Openmesh-Collectors

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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,
        "scale": 24,
        "type": "bytes"
      }
    },
    {
      "name": "amountSold",
      "type": {
        "logicalType": "decimal",
        "precision": 38,
        "scale": 24,
        "type": "bytes"
      }
    },
    {
      "name": "logIndex",
      "type": "long"
    },
    {
      "name": "transactionHash",
      "type": "string"
    },
    {