Wallet Endpoints

Query wallet UTXOs and balances directly from Anvil's indexed blockchain data.

Query wallet data server-side without a browser wallet. Returns data ready for the Anvil transaction builder.

Endpoint	Method	Purpose
/wallets/utxos	GET	Fetch UTXOs for transaction building
/wallets/balance	GET	Get aggregated balance (ADA + native assets)

GET /wallets/utxos

Returns hex-encoded CBOR UTXOs ready for transaction building—same format as CIP-30 getUtxos().

Parameters:

Parameter	Type	Required	Description
address	string	One required	Bech32 payment address
stakeAddress	string	One required	Bech32 stake address (queries all derived addresses)
withScripts	boolean	No	Include reference scripts
includeMempool	boolean	No	Include UTXOs from pending transactions

const API_BASE = 'https://preprod.api.ada-anvil.app/v2/services';

// Fetch UTXOs by payment address
const response = await fetch(`${API_BASE}/wallets/utxos?address=addr_test1qz...`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const utxos = await response.json(); // string[]

// Use directly in transaction building
await fetch(`${API_BASE}/transactions/build`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-Api-Key': 'YOUR_API_KEY' },
  body: JSON.stringify({
    changeAddress: 'addr_test1qz...',
    utxos, // Ready to use!
    outputs: [{ address: 'addr_test1qy...', lovelace: 5_000_000 }]
  })
});

Query by stake address (all derived addresses)

// Gets UTXOs from ALL addresses under this stake key
const response = await fetch(`${API_BASE}/wallets/utxos?stakeAddress=stake_test1uq...`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const utxos = await response.json();

Include mempool for chained transactions

// Include UTXOs created by pending (unconfirmed) transactions
const response = await fetch(
  `${API_BASE}/wallets/utxos?address=addr_test1qz...&includeMempool=true`,
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
);

Use includeMempool when building chained transactions before the previous one confirms.

GET /wallets/balance

Returns aggregated balance as hex-encoded CBOR Value (lovelace + native assets).

Parameters:

Parameter	Type	Required	Description
address	string	One required	Bech32 payment address
stakeAddress	string	One required	Bech32 stake address

const response = await fetch(`${API_BASE}/wallets/balance?address=addr_test1qz...`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const balanceHex = await response.json(); // CBOR hex string

The response is CBOR-encoded Value—same format as CIP-30 api.getBalance(). Parse with any Cardano serialization library to extract lovelace and native assets.

When to Use

Scenario	Endpoint
Building transactions	/wallets/utxos — exact format for transactions/build
Displaying wallet balance	/wallets/balance — single aggregated value
Checking for specific asset	/wallets/utxos — inspect individual UTXOs
Query entire stake account	Either with stakeAddress parameter

For browser dApps with connected wallets, use Weld instead—UTXOs come directly from the user's wallet.

---

Related: Selecting UTXOs · Wallet CLI