Integration Guide

Quick Start

Integrate Aria Wallet into your dApp in three simple steps. No SDK installation required - Aria injects itself directly into the page as window.aria.

// 1. Check if Aria Wallet is installed if (!window.aria) { alert("Please install Aria Wallet extension"); return; } // 2. Request connection to a chain await window.aria.enable("cosmoshub-4"); // 3. Get the user's account const key = await window.aria.getKey("cosmoshub-4"); console.log("Address:", key.bech32Address); console.log("Public Key:", key.pubKey); console.log("Algorithm:", key.algo);

Detecting Aria Wallet

Aria Wallet injects itself into the page when loaded. However, you should wait for the document to be ready before checking for the wallet to ensure proper detection.

// Method 1: Check on window load window.onload = async () => { if (!window.aria) { console.log("Aria Wallet not installed"); return; } // Wallet is available const aria = window.aria; }; // Method 2: Check document ready state (recommended) async function getAria() { if (window.aria) { return window.aria; } if (document.readyState === "complete") { return window.aria; } return new Promise((resolve) => { const onReady = (event) => { if (event.target.readyState === "complete") { resolve(window.aria); document.removeEventListener("readystatechange", onReady); } }; document.addEventListener("readystatechange", onReady); }); } // Usage const aria = await getAria(); if (aria) { await aria.enable("cosmoshub-4"); }

Tip: The wallet injection happens at document_start, so it should be available before your JavaScript runs. However, using the document ready check ensures compatibility with all loading scenarios.

Connecting to the Wallet

Use enable() to request access to a chain. This will show an approval popup to the user if they haven't previously approved your dApp.

// Enable access to a single chain await window.aria.enable("cosmoshub-4"); // Get the key after enabling const key = await window.aria.getKey("cosmoshub-4"); // The AriaKey object contains: // { // name: "My Wallet", // User's wallet name // algo: "secp256k1", // Signing algorithm // pubKey: Uint8Array, // Raw public key bytes // address: Uint8Array, // Raw address bytes // bech32Address: "cosmos1...", // Human-readable address // isNanoLedger: false // Hardware wallet flag // }

AriaKey Properties

PropertyTypeDescription
namestringUser's wallet display name
algostringSigning algorithm (typically "secp256k1")
pubKeyUint8ArrayRaw public key bytes
bech32AddressstringHuman-readable address (e.g., cosmos1...)
isNanoLedgerbooleanWhether using a Ledger hardware wallet

Multi-Chain Support

Aria Wallet supports multiple Cosmos chains simultaneously. You can enable several chains in a single call, and each chain will have its own address derived from the same seed phrase.

// Enable multiple chains at once await window.aria.enable([ "cosmoshub-4", "osmosis-1" ]); // Get keys for each chain const cosmosKey = await window.aria.getKey("cosmoshub-4"); const osmosisKey = await window.aria.getKey("osmosis-1"); // Each chain has a different address (same mnemonic, different derivation) console.log("Cosmos:", cosmosKey.bech32Address); // cosmos1... console.log("Osmosis:", osmosisKey.bech32Address); // osmo1...

Keplr Compatibility

Aria Wallet is fully Keplr-compatible. It exposes the same API on both window.aria and window.keplr, allowing existing Keplr integrations to work without modification.

// Aria Wallet also injects window.keplr for compatibility // You can use either interface - they're identical // Using window.aria (recommended) if (window.aria) { await window.aria.enable("cosmoshub-4"); } // Using window.keplr (for existing Keplr integrations) if (window.keplr) { await window.keplr.enable("cosmoshub-4"); } // Feature detection for wallet type const walletName = window.aria?.version ? "Aria Wallet" : window.keplr ? "Keplr" : "Unknown";

Note: When both Aria and Keplr are installed, Aria can be configured to coexist with Keplr. In this case, window.aria will always point to Aria, while window.keplr may point to either wallet depending on user settings.

Event Listeners

Listen for account changes to keep your dApp in sync with the wallet state. These events fire when the user switches accounts or wallets.

// Listen for account changes window.addEventListener("aria_keystore_change", async () => { console.log("Account changed!"); // Re-fetch the key to get updated account info const key = await window.aria.getKey("cosmoshub-4"); console.log("New address:", key.bech32Address); // Update your app state updateUserAccount(key); }); // Alternative event names (Keplr compatibility) window.addEventListener("keplr_keystorechange", callback); window.addEventListener("aria_keystorechange", callback);

Available Events

  • aria_keystore_change - Primary event for account changes
  • aria_keystorechange - Keplr compatibility event
  • keplr_keystorechange - Keplr compatibility event

Error Handling

Always wrap wallet interactions in try-catch blocks. The wallet can throw errors for various reasons including user rejection, unsupported chains, and timeouts.

async function connectWallet() { try { // Request connection await window.aria.enable("cosmoshub-4"); // Get key const key = await window.aria.getKey("cosmoshub-4"); return key; } catch (error) { if (error.message.includes("rejected")) { // User clicked "Reject" in the popup console.log("User rejected the connection request"); } else if (error.message.includes("not supported")) { // Chain is not configured in the wallet console.log("Chain not supported - try suggestChain first"); } else if (error.message.includes("locked")) { // Wallet is locked console.log("Please unlock your wallet"); } else { // Other error console.error("Connection failed:", error); } return null; } }

Common Errors

Error TypeCauseSolution
Request rejectedUser clicked RejectShow a message and allow retry
Chain not supportedChain not in walletUse suggestChain()
Wallet lockedUser hasn't unlockedPrompt user to unlock wallet
Request timeoutNo response in 30sRetry the request

TypeScript Support

For TypeScript projects, you can add type definitions for the wallet interface. This provides autocompletion and type checking for all wallet methods.

// Install types (if publishing to npm) // npm install @aria-wallet/types // Or use the types from this documentation interface AriaKey { name: string; algo: string; pubKey: Uint8Array; address: Uint8Array; bech32Address: string; isNanoLedger: boolean; } interface InjectedAria { version: string; mode: "extension"; enable: (chainIds: string | string[]) => Promise<void>; getKey: (chainId: string) => Promise<AriaKey>; // ... see API Reference for full interface } // Type augmentation for window declare global { interface Window { aria?: InjectedAria; keplr?: InjectedAria; } } // Now TypeScript knows about window.aria const key = await window.aria?.getKey("cosmoshub-4"); if (key) { console.log(key.bech32Address); // TypeScript knows this is a string }