L1 Data Schemas

This page documents the data formats for GX Chain L1 blocks, transactions, and events. These schemas are relevant for node operators, indexers, and applications that consume raw chain data.

Block Schema

GX Chain blocks contain both GX Core and GX EVM data.

Block Header

{
  "height": 1000000,
  "time": "2026-03-30T12:00:00.000Z",
  "proposer": "0xValidatorAddress...",
  "hash": "0xBlockHash...",
  "parentHash": "0xParentHash...",
  "stateRoot": "0xStateRoot...",
  "coreRoot": "0xCoreStateRoot...",
  "evmRoot": "0xEvmStateRoot...",
  "txCount": 42,
  "gasUsed": 1500000,
  "gasLimit": 2000000
}

Field	Type	Description
`height`	`int`	Sequential block number
`time`	`string`	ISO 8601 timestamp
`proposer`	`address`	Validator that proposed this block
`hash`	`hex`	Block hash (32 bytes)
`parentHash`	`hex`	Previous block hash
`stateRoot`	`hex`	Combined state trie root
`coreRoot`	`hex`	GX Core state root (orderbooks, positions, balances)
`evmRoot`	`hex`	GX EVM state root
`txCount`	`int`	Number of transactions in the block
`gasUsed`	`int`	Total gas consumed (EVM transactions only)
`gasLimit`	`int`	Block gas limit (2M fast / 30M slow)

Transaction Types

Core Transactions

GX Core transactions are signed exchange actions:

{
  "type": "core",
  "hash": "0xTxHash...",
  "sender": "0xSenderAddress...",
  "action": {
    "type": "order",
    "orders": [
      {
        "a": 0,
        "b": true,
        "p": "67000.0",
        "s": "0.01",
        "r": false,
        "t": { "limit": { "tif": "Gtc" } }
      }
    ],
    "grouping": "na"
  },
  "nonce": 1700000000123,
  "signature": { "r": "0x...", "s": "0x...", "v": 27 },
  "result": {
    "status": "ok",
    "fills": [],
    "restingOrders": [{ "oid": 12345 }]
  }
}

Core Transaction Action Types

Action Type	Description
`order`	Place one or more orders
`cancel`	Cancel orders by ID
`cancelByCloid`	Cancel orders by client ID
`modify`	Modify an existing order
`usdTransfer`	Transfer USD between addresses
`withdraw`	Withdraw from bridge
`updateLeverage`	Change leverage setting
`approveAgent`	Authorize/revoke an API wallet
`coreToEvm`	Transfer from Core to EVM
`spotDeploy`	Deploy GIP-1/GIP-2 asset
`deployerAction`	GIP-3 deployer action

EVM Transactions

Standard Ethereum transactions:

{
  "type": "evm",
  "hash": "0xTxHash...",
  "from": "0xSenderAddress...",
  "to": "0xRecipientOrContract...",
  "value": "0",
  "data": "0xCalldata...",
  "gasLimit": 100000,
  "gasUsed": 52000,
  "gasPrice": "1000000000",
  "nonce": 42,
  "status": 1,
  "logs": [
    {
      "address": "0xContractAddress...",
      "topics": ["0xTopic0...", "0xTopic1..."],
      "data": "0xLogData..."
    }
  ]
}

Event Schemas

Order Event

Emitted when an order is placed, filled, or cancelled:

{
  "type": "order",
  "subType": "placed",
  "user": "0xAddress...",
  "asset": 0,
  "oid": 12345,
  "side": "B",
  "price": "67000.0",
  "size": "0.01000",
  "tif": "Gtc",
  "timestamp": 1700000000000
}

subType	Description
`placed`	Order resting on the book
`filled`	Order fully filled
`partialFill`	Order partially filled
`cancelled`	Order cancelled by user
`expired`	Order expired (e.g., IOC unfilled portion)

Fill Event

Emitted for every trade execution:

{
  "type": "fill",
  "maker": "0xMakerAddress...",
  "taker": "0xTakerAddress...",
  "asset": 0,
  "price": "67000.0",
  "size": "0.01000",
  "makerOid": 12345,
  "takerOid": 12346,
  "fee": "0.335",
  "isBuyerMaker": true,
  "timestamp": 1700000000000
}

Liquidation Event

{
  "type": "liquidation",
  "user": "0xLiquidatedAddress...",
  "asset": 0,
  "size": "0.50000",
  "price": "65000.0",
  "bankruptcyPrice": "64800.0",
  "timestamp": 1700000000000
}

Funding Payment Event

{
  "type": "funding",
  "asset": 0,
  "fundingRate": "0.0001",
  "premium": "0.00005",
  "timestamp": 1700000000000,
  "payments": [
    {
      "user": "0xAddress...",
      "amount": "-1.25",
      "positionSize": "0.50000"
    }
  ]
}

Transfer Event

{
  "type": "transfer",
  "subType": "usdTransfer",
  "from": "0xSenderAddress...",
  "to": "0xRecipientAddress...",
  "amount": "1000.0",
  "timestamp": 1700000000000
}

Querying Historical Data

Via Node API

If you run a node with pruning = "none", you can query any historical block:

# Get block at height 1000000
curl http://localhost:4001/v1/height
curl http://localhost:26657/block?height=1000000

Via EVM RPC

const provider = new ethers.JsonRpcProvider("http://localhost:3001");
 
// Get historical block
const block = await provider.getBlock(1000000);
 
// Get logs from a range
const logs = await provider.getLogs({
  fromBlock: 1000000,
  toBlock: 1000100,
});

Data Encoding

Format	Usage
Addresses	20-byte hex with `0x` prefix, EIP-55 checksum
Hashes	32-byte hex with `0x` prefix
Amounts	String-encoded decimal numbers
Timestamps	Milliseconds since Unix epoch (Core) or seconds (EVM blocks)
Prices	String-encoded, max 5 significant figures
Sizes	String-encoded, precision governed by `szDecimals`

Nodes Non-Validating Node