> For the complete documentation index, see [llms.txt](https://dev.ada-anvil.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev.ada-anvil.io/developer-tools/wallet-endpoints.md).

# 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()`](https://cips.cardano.org/cip/CIP-0030#apigetutxosamount-cborvalue--undefined-paginate-paginate--undefined-promisetransactionunspentoutput--null).

**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              |

```typescript
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 }]
  })
});
```

<details>

<summary>Query by stake address (all derived addresses)</summary>

```typescript
// 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();
```

</details>

<details>

<summary>Include mempool for chained transactions</summary>

```typescript
// 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.

</details>

## 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   |

```typescript
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
```

{% hint style="info" %}
The response is CBOR-encoded Value—same format as [CIP-30 `api.getBalance()`](https://cips.cardano.org/cip/CIP-0030#apigetbalance-promisecborvalue). Parse with any Cardano serialization library to extract lovelace and native assets.
{% endhint %}

## 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                     |

{% hint style="info" %}
For browser dApps with connected wallets, use [Weld](https://github.com/Cardano-Forge/weld) instead—UTXOs come directly from the user's wallet.
{% endhint %}

***

**Related:** [Selecting UTXOs](/guides/transaction/selecting-utxos.md) · [Wallet CLI](/developer-tools/wallet-cli.md)