Adding a New Blockchain Network

This guide walks through adding a new EVM-compatible blockchain network to your Fystack instance.

EVM only

Currently, only new EVM-compatible blockchains can be added by users. For non-EVM chains (e.g., new Solana clusters, Tron networks, or entirely new blockchain architectures), contact the Fystack team for guidance.

Overview

Adding a new network requires changes in three places that must all match:

Step 1: Set Up System Admin

Only system admins can create new networks in the Fystack UI. Make sure your email is listed in config.yaml:

system_admins:
  - "your-email@yourcompany.com"

If you changed this, recreate Apex first:

docker compose -f ./dev/docker-compose.yaml up -d --force-recreate apex

Step 2: Create the Network in Fystack UI

1. Sign in to the Fystack UI with your system admin account
2. Navigate to the Networks page (see Fystack product docs on networks)
3. Click Add Network
4. Fill in the network details (name, chain ID, native asset, etc.)
5. Save the network

Step 3: Get the Network ID and Internal Code

After creating the network in the UI, call the networks API to get the id and internal_code. Replace the URL with your own API domain:

# Local development
curl -s http://localhost:8150/api/v1/networks | jq .

# Self-hosted VPS (replace with your API domain)
curl -s https://api.yourdomain.com/api/v1/networks | jq .

Find the network you just created in the response. You need two values:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "internal_code": "POLYGON_MAINNET",
  ...
}

Step 4: Update config.yaml

Add the network to the networks section in config.yaml. The network key must match the internal_code from the API:

networks:
  # ... existing networks ...

  POLYGON_MAINNET:                    # Must match internal_code
    enabled: true
    wss_enabled: false                # Set true if you want WSS indexing
    providers:
      - name: "alchemy"
        http: "https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY"
        wss: "wss://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY"
      - name: "publicnode"            # Backup RPC
        http: "https://polygon-bor-rpc.publicnode.com"

Step 5: Update config.indexer.yaml

Add the chain to the multichain indexer config. The network_id and internal_code must match the values from the API:

chains:
  # ... existing chains ...

  polygon_mainnet:
    network_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"   # From API response
    internal_code: "POLYGON_MAINNET"                       # Must match config.yaml key
    type: "evm"
    start_block: 65000000                                  # Recent block number
    nodes:
      - url: "https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY"

Also add the chain name to the CHAINS environment variable in docker-compose.yaml:

multichain-indexer:
  environment:
    - CHAINS=tron_testnet,polygon_mainnet    # Add your new chain

Step 6: Recreate Services

Recreate both Apex and the multichain indexer to pick up the changes:

docker compose -f ./dev/docker-compose.yaml up -d --force-recreate apex
docker compose -f ./dev/docker-compose.yaml up -d --force-recreate multichain-indexer

Step 7: Verify

Check that the indexer is processing blocks for the new chain:

docker compose -f ./dev/docker-compose.yaml logs -f multichain-indexer

You should see log lines showing block processing for your new chain.

Checklist

Make sure all three match:

Location	Field	Example Value
Fystack UI	Network ID (UUID)	a1b2c3d4-e5f6-7890-abcd-ef1234567890
config.yaml	Network key	POLYGON_MAINNET
config.indexer.yaml	internal_code	POLYGON_MAINNET
config.indexer.yaml	network_id	a1b2c3d4-e5f6-7890-abcd-ef1234567890
docker-compose.yaml	CHAINS env var	includes polygon_mainnet

Mismatched values

If any of these values don't match, deposits on the new chain will not be detected. See Deposits Not Detected for troubleshooting.