Paradex Chain

Node Setup

How to set up a Paradex full node using Docker

Prerequisites

Before you begin, ensure you have:

  1. Docker installed using the official guide
  2. Ethereum Node URL from a provider like Infura or Alchemy
  • Pathfinder only supports WebSocket
  • Juno supports WebSocket and HTTP

Required Environment Variables

Export these URLs as environment variables before running docker run:

$# If using WS
>export ETHEREUM_NODE_WSS_URL=
>  "wss://ethereum-mainnet.core.chainstack.com/YOUR_API_KEY"
>
># If using HTTP
>export ETHEREUM_NODE_HTTP_URL=
>  "https://ethereum-mainnet.core.chainstack.com/YOUR_API_KEY"
Recommend tools for downloading snapshots
  • awscli
  • zstd (for Pathfinder snapshots)
  • tar (for Juno snapshots)

Choose Your Client

Pathfinder
  • Original Starknet Client
  • Written in Rust
  • Recommended for most users
Juno
  • Newer Starknet Client
  • Written in Rust

Running Your Client

1

Create Data Directory

$# Ensure $HOME/pathfinder exists and is writable
>mkdir -p $HOME/pathfinder
2

Download Snapshot (Optional)

Download and decompress a snapshot to speed up sync:

$# Example: Paradex Mainnet snapshot
>aws s3 cp s3://paradex-prod-pathfinder-ap-northeast-1/2025-04-09/custom.sqlite.zst $HOME/pathfinder/
>unzstd $HOME/pathfinder/custom.sqlite.zst -o $HOME/pathfinder/pathfinder.sqlite

Note: Snapshot URLs/availability may change.

3

Run Container

Run the Pathfinder container for Paradex Mainnet:

$docker run \
> --name pathfinder-paradex-mainnet \
> --restart unless-stopped \
> --detach \
> -p 9545:9545 `# JSON-RPC port` \
> --user "$(id -u):$(id -g)" \
> -e RUST_LOG=info \
> -e EVENT_BLOOM_FILTER_CACHE_SIZE=1024 \
> -e PATHFINDER_ETHEREUM_API_URL="${ETHEREUM_NODE_WSS_URL}" \
> -e PATHFINDER_CHAIN_ID="PRIVATE_SN_PARACLEAR_MAINNET" \
> -e PATHFINDER_FEEDER_GATEWAY_URL="https://paraclear-mainnet.starknet.io/feeder_gateway" \
> -e PATHFINDER_GATEWAY_URL="https://paraclear-mainnet.starknet.io/gateway" \
> -e PATHFINDER_NETWORK="custom" \
> -e PATHFINDER_SYNC_ENABLED="true" \
> -e PATHFINDER_GATEWAY_REQUEST_TIMEOUT=30 \
> -v $HOME/pathfinder:/usr/share/pathfinder/data \
> eqlabs/pathfinder:v0.16.4
4

Monitor and Manage

$# Check logs
>docker logs -f pathfinder-paradex-main
># Stop container
>docker stop pathfinder-paradex-mainnet

Running on Testnet

1

Use Sepolia Ethereum Node

Ensure you are using a Sepolia Ethereum Node URL and set the appropriate environment variable:

$# For WebSocket (both clients)
>export ETHEREUM_NODE_WSS_URL_TESTNET="wss://sepolia.infura.io/ws/v3/YOUR_PROJECT_ID"
>
># For HTTP (Juno only)
>export ETHEREUM_NODE_HTTP_URL_TESTNET="https://sepolia.infura.io/v3/YOUR_PROJECT_ID"
2

Adjust Parameters

Modify these environment variables in the docker run command:

  • Starknet Chain ID
  • Starknet Gateway URLs
  • Ethereum Chain ID
  • Ethereum Core Contract Address
3

Get Testnet Values

Query the Testnet System Config API to get the correct values: https://api.testnet.paradex.trade/v1/system/config

4

Use Different Names/Paths

Change the Docker container name and host volume path to avoid conflicts:

$# Example for Pathfinder
>--name pathfinder-paradex-testnet
>-v $HOME/pathfinder-testnet:/usr/share/pathfinder/data
>
># Example for Juno
>--name juno-paradex-testnet
>-v $HOME/juno-testnet:/var/lib/juno