Adding Custom Chains

Overview

Aria Wallet supports adding custom Cosmos SDK chains using the suggestChain() method. This allows your dApp to work with any Cosmos chain, even if it's not built into the wallet.

await window.aria.suggestChain({ chainId: "mychain-1", chainName: "My Chain", rpc: "https://rpc.mychain.com", rest: "https://api.mychain.com", bip44: { coinType: 118 }, bech32Config: { bech32PrefixAccAddr: "mychain", bech32PrefixAccPub: "mychainpub", bech32PrefixValAddr: "mychainvaloper", bech32PrefixValPub: "mychainvaloperpub", bech32PrefixConsAddr: "mychainvalcons", bech32PrefixConsPub: "mychainvalconspub" }, currencies: [{ coinDenom: "TOKEN", coinMinimalDenom: "utoken", coinDecimals: 6 }], feeCurrencies: [{ coinDenom: "TOKEN", coinMinimalDenom: "utoken", coinDecimals: 6, gasPriceStep: { low: 0.01, average: 0.025, high: 0.04 } }] });

ChainInfo Interface

The SuggestChainInfo interface defines all the information needed to add a chain.

interface SuggestChainInfo { // Required fields chainId: string; // Unique chain identifier chainName: string; // Display name rpc: string; // RPC endpoint (port 26657) rest: string; // REST endpoint (port 1317) bip44: { coinType: number; // Usually 118 for Cosmos }; bech32Config: Bech32Config; currencies: Currency[]; feeCurrencies: FeeCurrency[]; // Optional fields stakeCurrency?: Currency; features?: string[]; }

Required Fields

FieldDescription
chainIdUnique identifier (e.g., "cosmoshub-4")
chainNameHuman-readable name shown in UI
rpcRPC endpoint URL (typically port 26657)
restREST/LCD endpoint URL (typically port 1317)
bip44Derivation path config (coinType: 118 for Cosmos)
bech32ConfigAddress prefix configuration
currenciesAvailable tokens on this chain
feeCurrenciesTokens that can be used for transaction fees

Bech32 Configuration

The bech32 config defines the address prefixes for different address types.

bech32Config: { // Account address (e.g., "cosmos1abc...") bech32PrefixAccAddr: "cosmos", // Account public key (e.g., "cosmospub1...") bech32PrefixAccPub: "cosmospub", // Validator operator address (e.g., "cosmosvaloper1...") bech32PrefixValAddr: "cosmosvaloper", // Validator operator public key bech32PrefixValPub: "cosmosvaloperpub", // Consensus address (e.g., "cosmosvalcons1...") bech32PrefixConsAddr: "cosmosvalcons", // Consensus public key bech32PrefixConsPub: "cosmosvalconspub" }

Currencies

Define the tokens available on your chain.

// Basic currency definition { coinDenom: "ATOM", // Display symbol coinMinimalDenom: "uatom", // On-chain denomination coinDecimals: 6, // Decimal places (1 ATOM = 1,000,000 uatom) coinGeckoId: "cosmos" // Optional: CoinGecko ID for price } // Fee currency with gas price steps { coinDenom: "ATOM", coinMinimalDenom: "uatom", coinDecimals: 6, gasPriceStep: { low: 0.01, // Low priority gas price average: 0.025, // Average priority high: 0.04 // High priority } }

Feature Flags

Feature flags tell the wallet what capabilities your chain supports.

features: [ // IBC Support "ibc-transfer", // IBC token transfers (ICS-20) "ibc-go", // Uses ibc-go module // Smart Contracts "cosmwasm", // CosmWasm smart contracts "secretwasm", // Secret Network WASM // EVM Compatibility "eth-address-gen", // Ethereum-style addresses "eth-key-sign", // Keccak256 signing "eth-secp256k1-cosmos" // EVM-based Cosmos chains ]
FeatureDescription
ibc-transferIBC token transfers (ICS-20)
cosmwasmCosmWasm smart contracts
eth-address-genEthereum-style addresses

Full Example

Complete configuration for a custom Cosmos SDK chain.

// Complete configuration for a custom Cosmos SDK chain await window.aria.suggestChain({ chainId: "mychain-1", chainName: "My Chain", rpc: "https://rpc.mychain.example", rest: "https://api.mychain.example", bip44: { coinType: 118 }, bech32Config: { bech32PrefixAccAddr: "mychain", bech32PrefixAccPub: "mychainpub", bech32PrefixValAddr: "mychainvaloper", bech32PrefixValPub: "mychainvaloperpub", bech32PrefixConsAddr: "mychainvalcons", bech32PrefixConsPub: "mychainvalconspub" }, currencies: [{ coinDenom: "MYC", coinMinimalDenom: "umyc", coinDecimals: 6 }], feeCurrencies: [{ coinDenom: "MYC", coinMinimalDenom: "umyc", coinDecimals: 6, gasPriceStep: { low: 0.0025, average: 0.025, high: 0.04 } }], stakeCurrency: { coinDenom: "MYC", coinMinimalDenom: "umyc", coinDecimals: 6 }, features: ["ibc-transfer", "cosmwasm"] });

Best Practices

1. Chain ID Format

Use identifier-version format for automatic upgrade detection.

2. Use Coin Type 118

For Ledger hardware wallet compatibility with the Cosmos app.

3. Handle Already-Added Chains

suggestChain() succeeds silently if chain exists.

async function connectToCustomChain() { const chainId = "mychain-1"; // Check if chain is already added try { await window.aria.enable(chainId); } catch (e) { // Chain not found, suggest it await window.aria.suggestChain({ chainId: chainId, chainName: "My Chain", // ... rest of config }); // Now enable it await window.aria.enable(chainId); } // Get the user's address const key = await window.aria.getKey(chainId); console.log("Connected:", key.bech32Address); }