Developer Tools

Wallet Endpoints#

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