Paradex Chain

Node Setup

This guide explains how to set up a Paradex full node using either Pathfinder or Juno via Docker.

Prerequisites

  1. Docker: Install Docker using the official guide.

  2. Ethereum Node URL: Obtain an Ethereum node URL for the target network (Mainnet or Sepolia Testnet) from a provider like Infura or Alchemy.

    • Pathfinder requires a WebSocket URL (wss://).
    • Juno supports WebSocket (wss://) or HTTP (https://).

    Export the URL(s) as environment variables before running docker run:

    $# Required for Pathfinder (Mainnet)
    >export ETHEREUM_NODE_WSS_URL="wss://ethereum-mainnet.core.chainstack.com/YOUR_API_KEY"
    ># Optionally required for Juno (Mainnet)
    >export ETHEREUM_NODE_HTTP_URL="https://ethereum-mainnet.core.chainstack.com/YOUR_API_KEY"
    >
    ># Example for Testnet (WSS, suitable for both)
    >export ETHEREUM_NODE_WSS_URL_TESTNET="wss://sepolia.infura.io/ws/v3/YOUR_PROJECT_ID"
    ># Example for Testnet (HTTP, suitable for Juno)
    >export ETHEREUM_NODE_HTTP_URL_TESTNET="https://sepolia.infura.io/v3/YOUR_PROJECT_ID"

  3. (Optional) AWS CLI & Decompression Tools: For downloading snapshots, you’ll need awscli installed and configured, plus zstd (for Pathfinder snapshots) or tar (for Juno snapshots).

Running Pathfinder

Set up a Paradex node using the Pathfinder client.

Setup Steps

  1. Create Data Directory:

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

  2. (Optional) Download Snapshot: Download and decompress a snapshot to speed up sync. (Requires awscli and zstd).

    $# 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 (Paradex Mainnet): Requires ETHEREUM_NODE_WSS_URL variable (see Prerequisites).

    $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 # Specify version if needed

    Key Paradex Parameters: PATHFINDER_CHAIN_ID, PATHFINDER_FEEDER_GATEWAY_URL, PATHFINDER_GATEWAY_URL, PATHFINDER_NETWORK="custom".

  4. Check Logs:

    $docker logs -f pathfinder-paradex-mainnet

  5. Stop Container:

    $docker stop pathfinder-paradex-mainnet

Running Juno

Set up a Paradex node using the Juno client.

Setup Steps

  1. Create Data Directory:

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

  2. (Optional) Download Snapshot: Download and decompress a snapshot to speed up sync. (Requires awscli and tar).

    $# Example: Paradex Mainnet Juno snapshot
    >aws s3 cp s3://paradex-prod-juno-ap-northeast-1/2025-04-09/juno.tar.xz $HOME/juno/
    >tar -xJf $HOME/juno/juno.tar.xz -C $HOME/juno/

    Note: Snapshot URLs/availability may change.

  3. Run Container (Paradex Mainnet): Requires ETHEREUM_NODE_WSS_URL or ETHEREUM_NODE_HTTP_URL variable (see Prerequisites).

    $docker run -d \
    >  --name juno-paradex-mainnet \
    >  --restart unless-stopped \
    >  -p 6060:6060 `# JSON-RPC port` \
    >  -p 6061:6061 `# WebSocket port` \
    >  --user "$(id -u):$(id -g)" \
    >  -e JUNO_LOG_LEVEL=info \
    >  -e JUNO_HTTP=true \
    >  -e JUNO_HTTP_PORT=6060 \
    >  -e JUNO_HTTP_HOST=0.0.0.0 \
    >  -e JUNO_WS=true \
    >  -e JUNO_WS_PORT=6061 \
    >  -e JUNO_WS_HOST=0.0.0.0 \
    >  -e JUNO_ETHEREUM_NODE_URL="${ETHEREUM_NODE_WSS_URL}" `# Or use HTTP var` \
    >  -e JUNO_NETWORK=custom \
    >  -e JUNO_STARKNET_FEEDER_URL="https://paraclear-mainnet.starknet.io/feeder_gateway/" \
    >  -e JUNO_STARKNET_GATEWAY_URL="https://paraclear-mainnet.starknet.io/gateway/" \
    >  -e JUNO_CUSTOM_NETWORK_NAME=sn-mainnet \
    >  -e JUNO_ETHEREUM_CHAIN_ID="1" \
    >  -e JUNO_UNVERIFIABLE_RANGE="0,10" \
    >  -e JUNO_ETHEREUM_CORE_CONTRACT_ADDRESS="0xF338cad020D506e8e3d9B4854986E0EcE6C23640" \
    >  -e JUNO_DB_PATH=/var/lib/juno `# Internal path` \
    >  -v $HOME/juno:/var/lib/juno `# Mount host directory` \
    >  nethermind/juno:latest # Specify version if needed

    Key Paradex Parameters: JUNO_NETWORK=custom, JUNO_STARKNET_FEEDER_URL, JUNO_STARKNET_GATEWAY_URL, JUNO_ETHEREUM_CHAIN_ID, JUNO_UNVERIFIABLE_RANGE, JUNO_ETHEREUM_CORE_CONTRACT_ADDRESS.

  4. Check Logs:

    $docker logs -f juno-paradex-mainnet

  5. Stop Container:

    $docker stop juno-paradex-mainnet

Running on Testnet

To run either Pathfinder or Juno on the Paradex Testnet, adapt the respective Mainnet docker run command:

  1. Use Sepolia Ethereum Node: Ensure you are using a Sepolia Ethereum Node URL (WSS for Pathfinder, WSS or HTTP for Juno). Set the appropriate environment variable (e.g., ETHEREUM_NODE_WSS_URL_TESTNET or ETHEREUM_NODE_HTTP_URL_TESTNET from Prerequisites).

  2. Adjust Parameters: Modify the environment variables (-e flags) in the docker run command to use the correct Testnet values. Key parameters to change include:

    • Starknet Chain ID (PATHFINDER_CHAIN_ID or inferred by Juno via gateways)
    • Starknet Gateway URLs (PATHFINDER_FEEDER_GATEWAY_URL, PATHFINDER_GATEWAY_URL, JUNO_STARKNET_FEEDER_URL, JUNO_STARKNET_GATEWAY_URL)
    • Ethereum Chain ID (JUNO_ETHEREUM_CHAIN_ID)
    • Ethereum Core Contract Address (JUNO_ETHEREUM_CORE_CONTRACT_ADDRESS)

    Find the precise Testnet values by querying the Testnet System Config API: https://api.testnet.paradex.trade/v1/system/config

  3. (Optional) Use Testnet Snapshot: If available, download and use a Testnet-specific database snapshot. Update the S3 URL and potentially the host directory path in the snapshot download commands.

  4. Use Different Names/Paths: Change the Docker container name (--name) and the host volume path (-v) to avoid conflicts with your Mainnet node configuration (e.g., --name pathfinder-paradex-testnet, -v $HOME/pathfinder-testnet:/usr/share/pathfinder/data).