Custom Chain Setup

Learn how to configure custom Avalanche L1 chains in your BuilderKit application.

Chain Definition

Define your custom L1 chain using viem's defineChain:

import { defineChain } from "viem";

export const myL1 = defineChain({
    id: 173750,  // Your L1 chain ID
    name: 'My L1',  // Display name
    network: 'my-l1',  // Network identifier
    nativeCurrency: {
        decimals: 18,
        name: 'Token',
        symbol: 'TKN',
    },
    rpcUrls: {
        default: {
            http: ['https://api.avax.network/ext/L1/rpc']
        },
    },
    blockExplorers: {
        default: { 
            name: 'Explorer', 
            url: 'https://explorer.avax.network/my-l1' 
        },
    },
    // Optional: Custom metadata
    iconUrl: "/chains/logo/my-l1.png",
    icm_registry: "0x..."  // ICM registry contract
});

Provider Configuration

Add your custom L1 chain to the Web3Provider:

import { Web3Provider } from '@avalabs/builderkit';
import { avalanche } from '@wagmi/core/chains';
import { myL1 } from './chains/definitions/my-l1';

function App() {
  return (
    <Web3Provider
      chains={[avalanche, myL1]}
      defaultChain={avalanche}
    >
      <YourApp />
    </Web3Provider>
  );
}

Required Properties

Property	Type	Description
`id`	`number`	Unique L1 chain identifier
`name`	`string`	Human-readable chain name
`network`	`string`	Network identifier
`nativeCurrency`	`object`	Chain's native token details
`rpcUrls`	`object`	RPC endpoint configuration
`blockExplorers`	`object`	Block explorer URLs

Optional Properties

Property	Type	Description
`iconUrl`	`string`	Chain logo URL
`icm_registry`	`string`	ICM registry contract address
`testnet`	`boolean`	Whether the chain is a testnet

Example: Echo L1

Here's a complete example using the Echo L1:

import { defineChain } from "viem";

export const echo = defineChain({
    id: 173750,
    name: 'Echo L1',
    network: 'echo',
    nativeCurrency: {
        decimals: 18,
        name: 'Ech',
        symbol: 'ECH',
    },
    rpcUrls: {
        default: {
            http: ['https://subnets.avax.network/echo/testnet/rpc']
        },
    },
    blockExplorers: {
        default: { 
            name: 'Explorer', 
            url: 'https://subnets-test.avax.network/echo' 
        },
    },
    iconUrl: "/chains/logo/173750.png",
    icm_registry: "0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228"
});

Custom Chain Setup

Custom Chain Setup

Chain Definition

Provider Configuration

Required Properties

Optional Properties

Example: Echo L1

On this page