Chainflip Docs

Running a Light RPC node

As of version 1.12.0, you can run a light-rpc node which requires fewer resources but allows only to query recent blocks. A light-rpc node is just a normal Chainflip node running in a specialized --sync light-rpc mode. This light-rpc mode prunes older blocks and permits querying only recent blocks, significantly reducing disk space requirements compared to running a full node. The recommended minimum requirements for running a light-rpc node include:

2 vCPU
4 GB RAM
20 GB SSD

Starting the node

Clone the chainflip-mainnet-apis repo


git clone https://github.com/chainflip-io/chainflip-mainnet-apis.git
cd chainflip-mainnet-apis

Start an RPC node and wait for it to sync:


docker compose --profile rpc-node up -d

View the logs to monitor sync progress


docker compose --profile rpc-node logs -f

You should see something like this:


node-1  | 2025-10-29 14:33:10 Chainflip Node
node-1  | 2025-10-29 14:33:10 ✌️  version 1.12.0-11b2cc9c943
node-1  | 2025-10-29 14:33:10 ❤️  by Chainflip Team <https://github.com/chainflip-io>, 2021-2025
node-1  | 2025-10-29 14:33:10 📋 Chain specification: Chainflip-Berghain
node-1  | 2025-10-29 14:33:10 🏷  Node name: subsequent-size-1441
node-1  | 2025-10-29 14:33:10 👤 Role: FULL
node-1  | 2025-10-29 14:33:10 💾 Database: RocksDb at /etc/chainflip/chaindata/chains/Chainflip-Berghain/db/full_light
node-1  | 2025-10-29 14:33:10 ⚡  Light-RPC mode enabled
node-1  | 2025-10-29 14:33:10 Deleting old db files and recreating a new RocksDB database on startup.
node-1  | 2025-10-29 14:33:12 🔨 Initializing Genesis block/state (state: 0xceb9…3b8d, header-hash: 0x8b8c…6eb9)
node-1  | 2025-10-29 14:33:12 🏷  Local node identity is: 12D3KooWKKd5C739WEyesEB2CsjE4HuHzRYMXSuCbCpmA3kzpJZ4
node-1  | 2025-10-29 14:33:12 Running libp2p network backend
node-1  | 2025-10-29 14:33:12 💻 Operating system: linux
node-1  | 2025-10-29 14:33:12 💻 CPU architecture: x86_64
node-1  | 2025-10-29 14:33:12 💻 Target environment: gnu
node-1  | 2025-10-29 14:33:12 💻 Memory: 23996MB
node-1  | 2025-10-29 14:33:12 💻 Kernel: 6.10.14-linuxkit
node-1  | 2025-10-29 14:33:12 💻 Linux distribution: Ubuntu 22.04.5 LTS
node-1  | 2025-10-29 14:33:12 💻 Virtual machine: no
node-1  | 2025-10-29 14:33:12 📦 Highest known block at #0
node-1  | 2025-10-29 14:33:12 〽️ Prometheus exporter started at 127.0.0.1:9615
node-1  | 2025-10-29 14:33:12 Running JSON-RPC server: addr=0.0.0.0:9944, allowed origins=["*"]

Make sure to see that light-rpc mode is enabled in the logs. Log line similar to: ⚡ Light-RPC mode enabled

Wait until the node is synced before start making RPC calls. This should take around 2 minutes.

💡 Note: Your node is considered synced when you see logs similar to:


chainflip-mainnet-apis-node-1  | 2023-12-14 10:22:24 ✨ Imported #438968 (0x3fba…8e06)
chainflip-mainnet-apis-node-1  | 2023-12-14 10:22:28 ⏩ Block history, #26112 (8 peers), best: #438968 (0x3fba…8e06), finalized #438966 (0x99bd…0628), ⬇ 3.4MiB/s ⬆ 182.8kiB/s

You can check the node’s health and verify it is synced by using this RPC call:


curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "system_health"}' \
    http://localhost:9944

You should a response showing that isSyncing is false, similar to:


{"jsonrpc":"2.0","result":{"peers":8,"isSyncing":false,"shouldHavePeers":true},"id":1}

To stop the node:


docker compose --profile rpc-node down

Interacting with the APIs

Now you can interact with the APIs using any HTTP or WS client. Here we use the curl and wscat commands.

For example, to get Chainflip’s Ethereum vault

curl


curl -H "Content-Type: application/json" \
-d '{ "id":1, "jsonrpc":"2.0", "method":"cf_eth_vault"}' \
http://localhost:9944

To get a list of all RPC endpoints available on the node

curl


curl -H "Content-Type: application/json" \
-d '{ "id":1, "jsonrpc":"2.0", "method":"rpc_methods"}' \
http://localhost:9944 | tr ',' '\n'

Subscribe to scheduled swaps. Note that subscriptions are only supported over WebSockets.


wscat -c ws://localhost:9944 -w 20 -x '{ "id":1, "jsonrpc":"2.0", "method":"cf_subscribe_scheduled_swaps", "params":{ "base_asset":{ "chain":"Ethereum", "asset":"USDT" }, "quote_asset":{ "chain":"Ethereum", "asset":"USDC" } }}'