How to Retrieve the Current Account Address and Balance in Osmosis Agent Toolkit

Use toolkit.account.address to derive the local Bech32 address and await toolkit.accountTool.call() to fetch balances enriched with USD valuations from the Cosmos Bank module.

The jonator/osmosis-agent-toolkit provides a TypeScript interface for interacting with the Osmosis blockchain. To retrieve the current account address and balance, the toolkit exposes synchronous address derivation alongside asynchronous balance queries that aggregate on-chain data with real-time pricing from the Osmosis SQS service.

Architecture Overview

The toolkit separates concerns across four core components to handle address generation and balance retrieval:

• Account (packages/core/src/account.ts) – Derives the Bech32 address from a BIP-39 mnemonic using local cryptographic operations.
• AccountTool (packages/core/src/tools/account.ts) – Fetches raw balances, resolves token prices via the SQS client, and returns a structured response with USD valuations.
• queryBalances (packages/core/src/queries/cosmos/bank.ts) – Executes the low-level HTTP request to the Cosmos SDK Bank module endpoint.
• OsmosisAgentToolkit (packages/core/src/toolkit.ts) – Public façade that wires the account, SQS client, and tools together, exposing account and accountTool properties.

Retrieving the Current Account Address

Local Address Derivation

The Account class in packages/core/src/account.ts generates the on-chain address without making network requests. The address getter (lines 66‑78) performs BIP-32 hierarchical deterministic derivation from the mnemonic seed, hashes the resulting public key with SHA-256 and RIPEMD-160, and encodes the final bytes using the chain-specific Bech32 prefix (e.g., osmo).

import { OsmosisAgentToolkit } from '@osmosis-agent-toolkit/core';

// Replace with your 24-word mnemonic (keep it secret!)
const mnemonic = 'sustain ...';
const toolkit = new OsmosisAgentToolkit(mnemonic);

const address = toolkit.account.address;
console.log('Current address →', address);

The address is derived locally; no network request is made.

Retrieving Account Balances

Raw Balance Queries

For low-level access, the queryBalances function in packages/core/src/queries/cosmos/bank.ts queries the /cosmos/bank/v1beta1/balances/{address} REST endpoint. This returns the raw list of { denom, amount } pairs held by the address without price decoration or metadata.

Enriched Balance Data with USD Valuations

The AccountTool class in packages/core/src/tools/account.ts provides the high-level interface. Its call() method (lines 39‑84) orchestrates several operations:

1. Fetches raw balances via queryBalances.
2. Queries the OsmosisSqsQueryClient for current USD prices of each token.
3. Matches each denomination to the chain-registry asset data to extract symbols and decimals.
4. Adjusts amounts for token decimals and calculates individual and total USD values.

import { OsmosisAgentToolkit } from '@osmosis-agent-toolkit/core';

const mnemonic = 'sustain ...';
const toolkit = new OsmosisAgentToolkit(mnemonic);

// `accountTool` internally calls the Cosmos Bank API and the SQS price service.
const accountInfo = await toolkit.accountTool.call();

console.log('Address:', accountInfo.address);
console.log('Total USD value:', accountInfo.balances.valueUsd.toFixed(2));
console.table(accountInfo.balances.balances);
/*
┌─────────┬─────────┬───────┬─────────┬─────────┐
│ (index) │ amount  │ ticker│ priceUsd│ valueUsd │
├─────────┼─────────┼───────┼─────────┼─────────┤
│   0     │ '12.34' │ 'OSMO'│  0.87   │ 10.74   │
│   1     │ '5.20'  │ 'ATOM'│  9.12   │ 47.42   │
└─────────┴─────────┴───────┴─────────┴─────────┘
*/

accountTool.call() returns an object of shape { address, balances: { valueUsd, balances: [...] } } as defined in AccountTool.

Summary

• Use toolkit.account.address for synchronous local address derivation via BIP-32/BIP-39 and Bech32 encoding.
• Use await toolkit.accountTool.call() to fetch balances enriched with token metadata and USD valuations from the Cosmos Bank module and Osmosis SQS.
• The underlying implementation resides in packages/core/src/account.ts, packages/core/src/tools/account.ts, and packages/core/src/queries/cosmos/bank.ts.

Frequently Asked Questions

How is the address derived without making a network request?

The Account class in packages/core/src/account.ts performs local cryptographic operations using BIP-32 hierarchical deterministic derivation and BIP-39 mnemonic seed generation. The address getter hashes the derived public key and encodes it with the chain-specific Bech32 prefix (e.g., osmo), all client-side.

What information does the balance response include?

The accountTool.call() method returns an object containing the Bech32 address, a balances array with each token's amount, ticker symbol, decimal places, USD price, and USD value, plus a valueUsd field representing the total portfolio value in dollars.

Can I retrieve raw balances without USD price data?

Yes. You can import queryBalances directly from packages/core/src/queries/cosmos/bank.ts and pass the Bech32 address to receive the raw { denom, amount } pairs from the Cosmos Bank module without invoking the SQS price client or token registry lookups.

Which Cosmos SDK endpoint does the toolkit query?

The queryBalances function queries the /cosmos/bank/v1beta1/balances/{address} REST endpoint of the Cosmos SDK Bank module, returning the native denomination and amount for each token held by the specified address.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}