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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ada-anvil.io/developer-tools/wallet-endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.