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
| Field | Description |
|---|---|
chainId | Unique identifier (e.g., "cosmoshub-4") |
chainName | Human-readable name shown in UI |
rpc | RPC endpoint URL (typically port 26657) |
rest | REST/LCD endpoint URL (typically port 1317) |
bip44 | Derivation path config (coinType: 118 for Cosmos) |
bech32Config | Address prefix configuration |
currencies | Available tokens on this chain |
feeCurrencies | Tokens 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
]| Feature | Description |
|---|---|
ibc-transfer | IBC token transfers (ICS-20) |
cosmwasm | CosmWasm smart contracts |
eth-address-gen | Ethereum-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);
}