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
| Property | Type | Description |
|---|---|---|
name | string | User's wallet display name |
algo | string | Signing algorithm (typically "secp256k1") |
pubKey | Uint8Array | Raw public key bytes |
bech32Address | string | Human-readable address (e.g., cosmos1...) |
isNanoLedger | boolean | Whether 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 changesaria_keystorechange- Keplr compatibility eventkeplr_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 Type | Cause | Solution |
|---|---|---|
| Request rejected | User clicked Reject | Show a message and allow retry |
| Chain not supported | Chain not in wallet | Use suggestChain() |
| Wallet locked | User hasn't unlocked | Prompt user to unlock wallet |
| Request timeout | No response in 30s | Retry 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
}