Mapping wallets to on-chain addresses

An Anchorage Digital wallet isn’t necessarily an on-chain address. Sometimes the two line up one to one, sometimes one wallet pools many addresses, and sometimes several wallets sit behind a single address. This page shows each case, then lets you try the permutations. Two ideas are worth keeping apart as you read. An on-chain wallet is a keypair and the address derived from it, and it works on every network that shares its key derivation. An Anchorage Digital wallet is a container for balances on one network inside one vault, with its own walletId. For where wallets sit in the wider structure, see Account hierarchy.

​

How a wallet ID maps to addresses

The walletId is the identifier your integration operates on. Withdrawals, balances, and calls to GET /v2/wallets all name a wallet, never an address. How many on-chain addresses sit underneath it depends on the network’s transaction model, which Account hierarchy covers in detail. On account-based networks the wallet and the address are interchangeable in practice, which is why the distinction is easy to miss. On UTXO networks they clearly aren’t: a transfer pulls from multiple source addresses automatically, and the unspent remainder returns to a new change address inside the same wallet.

​

What one address can hold

A single on-chain address holds more than one type of asset. The network’s native asset and every token issued on that network arrive at the same address and sit in the same wallet, each with its own balance. Because the address is shared across the whole token layer, you can’t add a second deposit address to an existing wallet on an account-based network. Create another wallet in the vault instead, and it comes with its own walletId.

​

Two ways to map compatible networks

Compatible networks share a key derivation, so one keypair works across all of them. In the API, each network carries a keyFamily: an opaque identifier where two networks can share wallet private keys when their values match. Treat it as an equality comparison within a single response, and don’t parse or cache the value. Address sharing is available on EVM, SPL, and Tendermint networks. When you create wallets on more than one network in a family, you choose between two setups. The choice is made at creation: the selected network only, all compatible networks, or a subset you pick. See Creating and managing wallets for the flow, including how to extend an existing wallet’s address onto more networks later.

​

Plan a configuration

Set a network, decide how many networks to cover, and pick an address strategy. The diagram redraws to show the wallets you’d create, their wallet IDs, and the addresses underneath them.

​

What follows from the model

• The first wallet created for a network in a vault becomes that vault’s default wallet, and the source of funds for external withdrawals, trade settlement, and holds executed by API.
• A generated address stays live on the blockchain and can’t be deleted, so it keeps receiving. Addresses can be reused.
• Trusted destinations are per network. The same address on two networks needs two entries, and a withdrawal fails if the address is allowlisted on a different network than the one you send on. See Trusted destinations.
• On certain networks, creating one wallet also generates the wallets for all compatible networks and archives them. Archived wallets still receive deposits, but unarchive them before staking or withdrawing.
• A deposit that arrives on a compatible network where you have no wallet is still detected on the shared address. We run spam attribution and create the wallet if the deposit clears.
• Each asset carries an availableBalance and a totalBalance per wallet. See Account hierarchy for what each one includes.