Add Aria AI to your dApp
Overview
A dApp connected to Aria through WalletConnect can open Aria's AI chat with a request already written, such as "Stake 10 OSMO with Chorus One", plus context the AI can use, such as the validator's address. The user approves the request in Aria, reads it, can edit it, and sends it. Anything the AI proposes still goes through Aria's confirmation card before it signs. Register your own commands as tools and the AI can call them through your dApp, in a loop the wallet runs (see Tools and the Agent Loop).
Where it works
- Aria extension: on the
cosmosnamespace (its WalletConnect is Cosmos only). - Aria mobile: on
cosmos,eip155andsolana. - The request uses the user's own AI chats. A user with none left sees Aria's usual message in the chat, and your dApp still gets
{ opened: true }.
WalletConnect Setup
You need a WalletConnect project ID from Reown Cloud and the sign client.
npm install @walletconnect/sign-client
# Or with yarn
yarn add @walletconnect/sign-clientAsk for the methods
Aria approves the AI methods only when your connection proposal lists them. Put them in optionalNamespaces.
// List the Aria AI methods next to the methods you already use, in optionalNamespaces.
// In requiredNamespaces, a wallet without them would refuse the whole connection.
const ARIA_AI_METHODS = [
"aria_aiPrompt", "aria_aiCapabilities", "aria_aiRegisterTools", "aria_aiToolResult",
];
const optionalNamespaces = {
cosmos: {
chains: ["cosmos:osmosis-1"],
methods: ["cosmos_signDirect", "cosmos_signAmino", "cosmos_getAccounts", ...ARIA_AI_METHODS],
events: ["accountsChanged", "chainChanged"],
},
};Detect support
A wallet approves only the methods it supports, so check the session instead of the wallet's name.
// The wallet approves a method only if it supports it, so the session tells you
function supportsAriaAI(session) {
return Object.values(session.namespaces).some(ns => ns.methods.includes("aria_aiPrompt"));
}
// The chain to send the request on: any chain of a namespace that has the method
function ariaAIChain(session) {
const ns = Object.values(session.namespaces).find(n => n.methods.includes("aria_aiPrompt"));
return ns?.accounts[0]?.split(":").slice(0, 2).join(":"); // "cosmos:osmosis-1"
}Methods
aria_aiCapabilities
Answers right away, without a screen, since it says nothing about the user. When the user approves the connection, Aria tells them the app can ask Aria AI and that each request needs their approval.
// Request
{ "method": "aria_aiCapabilities", "params": {} }
// Response: static facts, nothing about the user
{
"version": 2,
"wallet": "Aria",
"platform": "extension", // or "android", "ios"
"methods": ["aria_aiPrompt", "aria_aiCapabilities", "aria_aiRegisterTools", "aria_aiToolResult"],
"limits": {
"promptMaxLength": 500, "contextMaxLength": 2000,
"maxTools": 16, "toolNamePattern": "^[a-z][a-z0-9_]{0,47}$", "reservedToolNames": ["web_search"],
"toolDescriptionMaxLength": 300, "toolSchemaMaxLength": 4000, "toolSchemaMaxDepth": 5,
"maxToolRounds": 5, "toolResultMaxLength": 4000, "toolResultWaitSeconds": 300,
"maxAttachments": 3, "attachmentNameMaxLength": 100,
"textAttachmentMaxLength": 20000, "audioAttachmentMaxBytes": 500000,
"textAttachmentTypes": ["text/plain", "text/markdown", "text/csv", "application/json"],
"audioAttachmentTypes": ["audio/webm", "audio/ogg", "audio/mpeg", "audio/mp4", "audio/wav"]
}
}aria_aiPrompt
Shows the user your app's name, URL, domain check, prompt and context, each labeled as written by your app. Approving opens the chat with the prompt in the input box.
// Request: params is an object, or a one-element array of it
{
"method": "aria_aiPrompt",
"params": {
"prompt": "Stake 10 OSMO with Chorus One", // 1-500 characters
"context": "{\"validator\":\"osmovaloper1...\"}", // optional, up to 2,000 characters
"attachments": [ // optional, up to 3
{ "name": "notes.txt", "type": "text/plain", "text": "..." }, // text: up to 20,000 characters
{ "name": "clip.webm", "type": "audio/webm", "data": "GkXf..." } // audio: base64, up to 500,000 bytes
]
}
}
// Response once the user approves, when your app has no tools:
// Aria's chat is open with your prompt in it
{ "opened": true }
// When your app has tools, the answer waits for the AI (see Tools and the Agent Loop)
{ "opened": true, "promptId": "…", "status": "toolCalls", "toolCalls": [ … ] }
// Errors
{ "code": 5000, "message": "User rejected." } // the user declined
{ "code": -32602, "message": "Invalid params: prompt must be a string" } // bad params, no screen shown| Field | Type | Rules |
|---|---|---|
prompt | string | Required, 1 to 500 characters after trimming |
context | string | Optional, up to 2,000 characters. Send structured data as a JSON string. |
Control characters other than newlines and tabs are removed before the limits are checked. Aria never sends balances or transaction results back to your dApp, and sends the AI's reply only when your app has tools and the user allows it: watch the chain for the outcome.
Tools and the Agent Loop
Your dApp can register its own commands as tools. When it then sends a prompt, Aria's AI can call them: the call comes back to your dApp as structured data, you run it, send the result back, and the AI continues until it answers. The wallet is the harness: it runs the loop, asks the user, and keeps everything else private.
aria_aiRegisterTools
Aria lists each tool's name and description and the user approves the set once. The tools are saved for your app, keyed by its verified origin, and the user can remove them in Connected Apps. Registering the same set again answers without a screen; a different set asks again.
// Request: register (or replace) your app's tools; the user approves the set once
{
"method": "aria_aiRegisterTools",
"params": {
"tools": [
{
"name": "get_quote", // lowercase letters, digits and _
"description": "Quote a swap on this DEX", // what the user and the AI read, up to 300 characters
"inputSchema": { // JSON Schema, root type "object"
"type": "object",
"properties": {
"from": { "type": "string" },
"to": { "type": "string" },
"amount": { "type": "number", "minimum": 0 }
},
"required": ["from", "to", "amount"],
"additionalProperties": false
}
}
]
}
}
// Response once the user approves (the same set again answers without a screen)
{ "registered": ["get_quote"] }Schemas use a subset of JSON Schema that both Aria wallets and the AI service check the same way: type (one type name), description, properties, required, additionalProperties (true or false), items, enum, minLength, maxLength, minimum, maximum, minItems and maxItems, nested at most 5 levels and 4,000 characters as JSON. Up to 16 tools. Anything else is refused with -32602 before the user sees a screen.
The loop
With approved tools, the user's approval of aria_aiPrompt sends the prompt as shown, and the answer waits for the AI. It has a promptId and a status: toolCalls means the AI wants your tools, and done ends the loop. Answer tool calls with aria_aiToolResult; its answer is the next step.
// The AI asked for your tools (from aria_aiPrompt or the previous aria_aiToolResult)
{
"opened": true,
"promptId": "6f1c…",
"status": "toolCalls",
"toolCalls": [{ "id": "toolu_01…", "name": "get_quote", "arguments": { "from": "USDC", "to": "OSMO", "amount": 20 } }],
"text": "Checking the price." // only if the user let your app see the AI's reply
}
// Request: answer every call of the last toolCalls, once each
{
"method": "aria_aiToolResult",
"params": {
"promptId": "6f1c…",
"results": [{ "id": "toolu_01…", "result": { "out": "41.2", "route": "pool 1251" } }]
// a failure: { "id": "toolu_01…", "result": "no such pool", "isError": true }
}
}
// Response: the next step, the same shape again
{ "opened": true, "promptId": "6f1c…", "status": "done", "text": "Swap 20 USDC for about 41.2 OSMO …" }- Every call is checked against your schema before it reaches you. Answer each call of a round once, with any JSON value up to 4,000 characters.
- After 5 rounds of tool calls the AI must answer without tools, so the loop always ends.
- Answer within 5 minutes or the loop ends. If the user ends the chat, your open request gets error 5000.
- Swaps, sends, stakes and other wallet actions are never tool calls. The AI proposes them in Aria, and they go to the user's confirmation card at Maximum Security.
- Your dApp gets the tool calls and nothing else, plus the AI's reply when the user ticks "Let your app see Aria AI's reply". Balances, other addresses, contacts and chat history stay out of the AI's view unless the user ticks the box that shares them for that request, so they can't end up in a call's arguments. The AI does see the session's accounts, which you already know.
- Each AI step uses the user's own AI chats, as a chat in Aria does.
Attachments
aria_aiPrompt takes up to 3 files: text (text/plain, text/markdown, text/csv, application/json) as text, and audio (audio/webm, audio/ogg, audio/mpeg, audio/mp4, audio/wav) as base64 data, which Aria transcribes like a voice message. The user sees each file's name on the approval screen, and the AI reads them as your app's data. Other types, more files or larger ones get -32602 before any screen.
Agent Example
Register tools, prompt, answer the tool calls and get the final answer, with the sign client. On the extension, keep Aria's window open while the loop runs.
import SignClient from "@walletconnect/sign-client";
const ARIA_AI_METHODS = [
"aria_aiPrompt", "aria_aiCapabilities", "aria_aiRegisterTools", "aria_aiToolResult",
];
const CHAIN = "cosmos:osmosis-1";
// The user approves and the AI thinks before each answer: give requests a few minutes
const EXPIRY_SECONDS = 600;
const client = await SignClient.init({
projectId: "YOUR_WALLETCONNECT_PROJECT_ID",
metadata: {
name: "My DEX",
description: "Swaps on Osmosis",
url: "https://mydex.example",
icons: ["https://mydex.example/icon.png"],
},
});
const { uri, approval } = await client.connect({
optionalNamespaces: {
cosmos: {
chains: [CHAIN],
methods: ["cosmos_signDirect", "cosmos_signAmino", "cosmos_getAccounts", ...ARIA_AI_METHODS],
events: ["accountsChanged", "chainChanged"],
},
},
});
showConnectDialog(uri);
const session = await approval();
const ask = (method, params) =>
client.request({ topic: session.topic, chainId: CHAIN, expiry: EXPIRY_SECONDS, request: { method, params } });
// 1. Register your commands as tools. The user approves them once, in plain words.
await ask("aria_aiRegisterTools", {
tools: [
{
name: "get_quote",
description: "Quote a swap on this DEX: what you get for an amount of one coin in another",
inputSchema: {
type: "object",
properties: {
from: { type: "string" },
to: { type: "string" },
amount: { type: "number", minimum: 0 },
},
required: ["from", "to", "amount"],
additionalProperties: false,
},
},
{
name: "list_pools",
description: "List this DEX's pools for a coin, with their fees",
inputSchema: {
type: "object",
properties: { coin: { type: "string" } },
required: ["coin"],
additionalProperties: false,
},
},
],
});
// Your own implementations: they run in your app, with your data
const TOOLS = {
get_quote: async ({ from, to, amount }) => myDex.quote(from, to, amount),
list_pools: async ({ coin }) => myDex.pools(coin),
};
async function runCall(call) {
try {
return { id: call.id, result: await TOOLS[call.name](call.arguments) };
} catch (error) {
return { id: call.id, result: String(error.message ?? error), isError: true };
}
}
// 2. Prompt. 3. Answer each round of tool calls. 4. Get the final answer.
async function askAriaAgent(prompt, context) {
let step;
try {
step = await ask("aria_aiPrompt", { prompt, context });
} catch (error) {
if (error?.code === 5000) return null; // the user declined
throw error;
}
if (!step.status) return step; // no tools approved: the chat opened for the user to send
while (step.status === "toolCalls") {
const results = await Promise.all(step.toolCalls.map(runCall));
step = await ask("aria_aiToolResult", { promptId: step.promptId, results });
}
// "done": any swap, send or stake the AI proposed is now on the user's confirmation card
return step.text ?? null; // present only if the user let you see the reply
}
const reply = await askAriaAgent(
"Swap 20 USDC to OSMO at the best price here",
JSON.stringify({ slippage: "0.5%" }),
);Vanilla JavaScript
import SignClient from "@walletconnect/sign-client";
const client = await SignClient.init({
projectId: "YOUR_WALLETCONNECT_PROJECT_ID",
metadata: {
name: "My dApp",
description: "Staking made simple",
url: "https://mydapp.example",
icons: ["https://mydapp.example/icon.png"],
},
});
const CHAIN = "cosmos:osmosis-1";
const { uri, approval } = await client.connect({
optionalNamespaces: {
cosmos: {
chains: [CHAIN],
methods: ["cosmos_signDirect", "cosmos_signAmino", "cosmos_getAccounts",
"aria_aiPrompt", "aria_aiCapabilities"],
events: ["accountsChanged", "chainChanged"],
},
},
});
// Show uri as a QR code for Aria mobile, or let the user paste it into the
// extension's WalletConnect screen
showConnectDialog(uri);
const session = await approval();
const canAskAria = session.namespaces.cosmos?.methods.includes("aria_aiPrompt");
async function askAria(prompt, context) {
if (!canAskAria) return false;
try {
await client.request({
topic: session.topic,
chainId: CHAIN,
request: { method: "aria_aiPrompt", params: { prompt, context } },
});
return true; // the user is now in Aria's chat with your request
} catch (error) {
if (error?.code === 5000) return false; // the user declined
throw error;
}
}
await askAria(
"Stake 10 OSMO with Chorus One",
JSON.stringify({ validator: "osmovaloper1..." }),
);React with @walletconnect/sign-client
import { useCallback, useMemo, useState } from "react";
const ARIA_AI = "aria_aiPrompt";
// client: an initialised SignClient; session: the approved session
export function useAriaAI(client, session) {
const [status, setStatus] = useState("idle"); // idle | waiting | opened | declined | error
const chainId = useMemo(() => {
const ns = session && Object.values(session.namespaces).find(n => n.methods.includes(ARIA_AI));
return ns?.accounts[0]?.split(":").slice(0, 2).join(":");
}, [session]);
const ask = useCallback(
async (prompt, context) => {
if (!client || !session || !chainId) return;
setStatus("waiting");
try {
await client.request({
topic: session.topic,
chainId,
request: { method: ARIA_AI, params: { prompt, context } },
});
setStatus("opened");
} catch (error) {
setStatus(error?.code === 5000 ? "declined" : "error");
}
},
[client, session, chainId],
);
return { supported: Boolean(chainId), status, ask };
}
export function StakeWithAria({ client, session, validator }) {
const { supported, status, ask } = useAriaAI(client, session);
if (!supported) return null;
return (
<div>
<button
disabled={status === "waiting"}
onClick={() =>
ask(`Stake 10 OSMO with ${validator.name}`, JSON.stringify({ validator: validator.address }))
}
>
Ask Aria to stake
</button>
{status === "waiting" && <p>Approve the request in Aria.</p>}
{status === "opened" && <p>Aria's chat is open. Review and confirm there.</p>}
{status === "declined" && <p>Request declined in Aria.</p>}
</div>
);
}Reown AppKit
AppKit's EVM adapter connects over eip155, so this reaches Aria mobile. The extension's WalletConnect is Cosmos only; use the sign client above for it.
import { createAppKit, useAppKitProvider } from "@reown/appkit/react";
import { WagmiAdapter } from "@reown/appkit-adapter-wagmi";
import { base, mainnet } from "@reown/appkit/networks";
const projectId = "YOUR_WALLETCONNECT_PROJECT_ID";
const networks = [mainnet, base];
const wagmiAdapter = new WagmiAdapter({ projectId, networks });
createAppKit({
adapters: [wagmiAdapter],
networks,
projectId,
metadata: {
name: "My dApp",
description: "Swaps made simple",
url: "https://mydapp.example",
icons: ["https://mydapp.example/icon.png"],
},
// This replaces AppKit's default EVM method list, so keep the ones you use
universalProviderConfigOverride: {
methods: {
eip155: [
"eth_sendTransaction", "personal_sign", "eth_signTypedData_v4",
"wallet_switchEthereumChain", "wallet_addEthereumChain",
"aria_aiPrompt", "aria_aiCapabilities",
],
},
},
});
export function SwapWithAria() {
const { walletProvider } = useAppKitProvider("eip155");
// Present when the wallet connected over WalletConnect
const methods = walletProvider?.session?.namespaces?.eip155?.methods ?? [];
if (!methods.includes("aria_aiPrompt")) return null;
const ask = () =>
walletProvider.request({
method: "aria_aiPrompt",
params: [{ prompt: "Swap 20 USDC on Base to ETH", context: "Pool: USDC/WETH 0.05%" }],
});
return <button onClick={ask}>Ask Aria to swap</button>;
}Security Notes
- Aria treats your prompt and context as untrusted text. The user sees them labeled as yours, and the AI is told they came from your app and are data, not instructions. Context that fails Aria's security check is withheld from the AI.
- Nothing runs on approval alone. Every transaction from the chat gets Aria's confirmation card, whatever the user's AI trust settings are.
- Write the prompt the user would write: one plain request with the amounts and names. Put addresses and IDs in the context, and say what they are.
- Don't put secrets or personal data in either field. The text reaches Aria's AI service and the model provider.
- Send one request per user action. A stream of requests is a stream of approval screens, and users decline them.
- Aria shows WalletConnect's domain check for your URL. Serve the dApp from the domain in your metadata so it shows as verified.
Testing
- Connect, then check that
supportsAriaAI(session)is true. If it's false, the methods are missing from your proposal. - Call
aria_aiCapabilities: it answers without anything showing in Aria. - Call
aria_aiPrompt, approve in Aria, and check you get{ opened: true }and the chat shows your prompt with your app named above it. Decline once and check you get error 5000. - Send a 501-character prompt and check you get -32602 with no screen in Aria.
- Register a tool and approve it, then see it under Connected Apps. Register the same set again and check it answers without a screen.
- Prompt with a request your tool answers, such as "What would 20 USDC get me in OSMO?". Check you get
status: "toolCalls", answer witharia_aiToolResult, and check you getstatus: "done"and, if you allowed it, the reply. - Ask for a swap with the tools: the swap shows on Aria's confirmation card, never as a call to your app.
- Send
aria_aiToolResultwith a wrong id or an unknown promptId and check you get -32602.