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