# Wallet

#### Balance Endpoint

**Overview**

The Balance Endpoint offers comprehensive balance and transaction data for specified wallet addresses. This endpoint is specifically tailored to provide detailed insights into the runes and bitcoin associated with a given address.

**Functionality**

* **Address Parameter**: Users must specify a wallet address to query its balance and transaction data.
* **Real-Time Data on Runes**: The endpoint focuses on providing detailed information about runes and bitcoin held in the queried wallet.
* **UTXOs and UTXOsIds**: Understanding the difference between `utxos` and `utxosIds` is crucial:
  * **utxos**: This array contains detailed information about each unspent transaction output (UTXO) that has been parsed and is available for the specified wallet address.
  * **utxosIds**: Represents all UTXOs associated with the wallet, including those not yet parsed. Initially, new wallet queries may show only `utxosIds` without corresponding `utxos` data, indicating that parsing is pending. Subsequent queries will reveal detailed UTXO data as parsing is completed.

**Endpoint Details**

## GET /v0/wallet/balance

> Get wallet balance and UTXO data

```json
{"openapi":"3.1.0","info":{"title":"@saturnbtcio/api","version":"0.0.1"},"tags":[{"name":"Wallet"}],"servers":[{"url":"https://api-dev.saturnbtc.io","description":"Development Server"},{"url":"https://api.saturnbtc.io","description":"Production Server"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"apiKey","name":"x-api-key","in":"header"}}},"paths":{"/v0/wallet/balance":{"get":{"summary":"Get wallet balance and UTXO data","tags":["Wallet"],"parameters":[{"name":"address","in":"query","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Wallet - The wallet's balance runes, btc and UTXO data.","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"balance":{"type":"string"},"utxosIds":{"type":"array","items":{"type":"string"}},"utxos":{"type":"array","items":{"type":"object","properties":{"collectionStatuses":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"const":"btc"},"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"oneOf":[{"type":"null"},{"type":"string"}]},"divisibility":{"type":"number"},"supply":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isWatchedByUser":{"type":"boolean"},"amount":{"type":"string"},"riskyAmount":{"type":"string"}},"required":["type","id","name","displayName","divisibility","supply","createdAt","updatedAt","isWatchedByUser","amount","riskyAmount"]},{"type":"object","properties":{"type":{"const":"rune"},"verified":{"type":"boolean"},"icon":{"oneOf":[{"type":"null"},{"type":"string"}]},"premined":{"type":"string"},"burned":{"type":"string"},"transactionId":{"oneOf":[{"type":"null"},{"type":"string"}]},"id":{"type":"string"},"name":{"type":"string"},"displayName":{"type":"string"},"symbol":{"oneOf":[{"type":"null"},{"type":"string"}]},"divisibility":{"type":"number"},"supply":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"isWatchedByUser":{"type":"boolean"},"amount":{"type":"string"},"riskyAmount":{"type":"string"}},"required":["type","verified","premined","burned","id","name","displayName","divisibility","supply","createdAt","updatedAt","isWatchedByUser","amount","riskyAmount"]}]}},"isUsed":{"type":"boolean"},"hasInscription":{"type":"boolean"},"inscriptionIds":{"type":"array","items":{"type":"string"}},"txid":{"type":"string"},"vout":{"type":"number"},"status":{"type":"object","properties":{"confirmed":{"type":"boolean"},"block_height":{"type":"number"},"block_hash":{"type":"string"},"block_time":{"type":"number"}},"required":["confirmed"]},"value":{"type":"string"}},"required":["collectionStatuses","isUsed","hasInscription","inscriptionIds","txid","vout","status","value"]}}},"required":["address","balance","utxosIds","utxos"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"string"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"string"}}}}}}}}}
```

* **Parameters**:
  * `address` (string, required): The wallet address for which balance and UTXO data is requested.

**Response Structure**

The response from this endpoint provides a JSON object with the following key details:

* `address`: The queried wallet address.
* `balance`: The overall balance of the wallet.
* `utxos`: An array of UTXO objects, each containing:
  * Details about its balance and associated collections.
  * Information on any inscriptions, including their content and metadata.
* `utxosIds`: An array of UTXO IDs representing all UTXOs associated with the wallet.
* Each UTXO and collection item contains additional fields such as market price, batch size, verification status, and timestamps.


---

# 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://docs.saturnbtc.io/builders/saturn-api/pool-api/wallet.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.