Running Nodes

GX Chain supports running external nodes that replicate the full chain state. Nodes enable direct access to block data, independent verification, and local API access without rate limits.

Node Types

Type	Description	Use Case
Non-validating node	Replicates state, does not participate in consensus	Data indexing, local API access, block exploration
Validator node	Participates in consensus and block production	Network security (requires staking)

Most developers and integrators should run a non-validating node. Validator nodes require staking and are covered in the validator documentation.

Why Run a Node

Benefit	Description
No rate limits	Access the full API locally without public endpoint rate limits
Lower latency	Eliminate network round-trip to the public API
Data independence	Verify chain state independently without trusting a third party
Custom indexing	Build custom indexes over historical block data
Archival access	Query any historical block without restrictions

System Requirements

Non-Validating Node

Resource	Minimum	Recommended
CPU	4 cores	8 cores
RAM	16 GB	32 GB
Storage	500 GB SSD	1 TB NVMe SSD
Network	100 Mbps	1 Gbps
OS	Linux (Ubuntu 22.04+)	Linux (Ubuntu 22.04+)

Storage requirements grow over time as the chain accumulates blocks. Plan for approximately 1 GB per day of additional storage.

Quick Start

1. Download the Binary

# Download the latest gx-node release
curl -L https://releases.gx.exchange/gx-node/latest/gx-node-linux-amd64 -o gx-node
chmod +x gx-node

2. Initialize Configuration

./gx-node init --network mainnet --data-dir /data/gx-node

This creates the data directory and downloads the genesis configuration.

3. Start the Node

./gx-node start \
  --network mainnet \
  --data-dir /data/gx-node \
  --rpc-addr 0.0.0.0:3001 \
  --api-addr 0.0.0.0:4001 \
  --ws-addr 0.0.0.0:4000

4. Verify Sync Status

curl http://localhost:4001/v1/height

The node is fully synced when the reported height matches the public API:

curl https://api.gx.exchange/v1/height

Configuration

Configuration File

Located at {data-dir}/config.toml:

[network]
chain_id = 42069
seeds = ["seed1.gx.exchange:26656", "seed2.gx.exchange:26656"]
 
[rpc]
listen_addr = "0.0.0.0:3001"
max_connections = 100
 
[api]
listen_addr = "0.0.0.0:4001"
cors_allowed_origins = ["*"]
 
[websocket]
listen_addr = "0.0.0.0:4000"
max_connections = 1000
 
[storage]
data_dir = "/data/gx-node"
pruning = "none"  # "none" for archive, "default" for pruned
 
[logging]
level = "info"
format = "json"

Pruning Options

Mode	Description	Storage Impact
`none`	Keep all historical blocks (archive node)	Grows indefinitely
`default`	Keep last 100,000 blocks	Bounded storage
`aggressive`	Keep last 10,000 blocks	Minimal storage

Ports

Port	Protocol	Service
`3001`	HTTP	EVM JSON-RPC
`4001`	HTTP	REST API
`4000`	WebSocket	Real-time data
`26656`	TCP	P2P (peer discovery)
`26657`	HTTP	Tendermint RPC

Monitoring

The node exposes Prometheus metrics at /metrics on the API port:

curl http://localhost:4001/metrics

Key metrics:

Metric	Description
`gx_node_block_height`	Current synced block height
`gx_node_peer_count`	Number of connected peers
`gx_node_sync_lag_seconds`	Seconds behind the chain tip
`gx_node_rpc_requests_total`	Total RPC requests served
`gx_node_evm_gas_used`	Cumulative EVM gas processed

Sections

L1 Data Schemas — Block and transaction data formats
Non-Validating Node — Detailed setup guide

JSON-RPC L1 Data Schemas