# Get UTXOs

The `getUtxos` method retrieves the Unspent Transaction Outputs (UTXOs) for one or more MNEE addresses. UTXOs represent the spendable MNEE tokens associated with an address and are essential for constructing new transactions.

### Usage

#### Basic Usage

```typescript
const address = '1G6CB3Ch4zFkPmuhZzEyChQmrQPfi86qk3';

// Returns up to 10 UTXOs by default
const utxos = await mnee.getUtxos(address);
console.log('UTXOs:', utxos);
```

{% hint style="success" %}
For convenience, you can also call [getEnoughUtxos()](/mnee-sdk/get-enough-utxos.md) or [getAllUtxos()](/mnee-sdk/get-all-utxos.md)
{% endhint %}

#### With Pagination

```typescript
const address = '1G6CB3Ch4zFkPmuhZzEyChQmrQPfi86qk3';

// Get first page with 20 UTXOs
const page1 = await mnee.getUtxos(address, 0, 20);
console.log('First 20 UTXOs:', page1);

// Get second page
const page2 = await mnee.getUtxos(address, 1, 20);
console.log('Next 20 UTXOs:', page2);

// Get UTXOs in ascending order (oldest first)
const ascUtxos = await mnee.getUtxos(address, 0, 50, 'asc');
console.log('Oldest UTXOs first:', ascUtxos);
```

#### Multiple Addresses

```typescript
const addresses = ['1G6CB3Ch4zFkPmuhZzEyChQmrQPfi86qk3', '1BFaJwJz5KPYGe28afDkGswbuKK6uK8hzQ'];

// Returns up to 10 UTXOs by default
const utxos = await mnee.getUtxos(addresses);
console.log('UTXOs from all addresses:', utxos);

// Get more UTXOs by specifying size
const moreUtxos = await mnee.getUtxos(addresses, 0, 100, 'desc');
console.log('First 100 UTXOs (newest first):', moreUtxos);
```

### Parameters

* **address**: Single Bitcoin address or array of addresses
* **page** (optional): Page number starting from 0
* **size** (optional): Number of UTXOs per page (default: 10)
* **order** (optional): Sort order - 'asc' for oldest first, 'desc' for newest first (default: 'desc')

### Response

The method returns a Promise that resolves to an array of `MNEEUtxo` objects. Each UTXO contains detailed information about the MNEE tokens, including BSV21 protocol data and cosigner information.

#### Sample Response

```json5
[
  {
    "data": {
      "bsv21": {
        "amt": 95799,
        "dec": 5,
        "icon": "1FGEBTUu7EqWWK5DKrG6pxjEGLahpATnA8",
        "id": "ae59f3b898ec61acbdb6cc7a245fabeded0c094bf046f35206a3aec60ef88127_0",
        "op": "transfer",
        "sym": "MNEE"
      },
      "cosign": {
        "address": "17cgGUmStWwcYgHg3kxmzXSp6JUbj8XA3u",
        "cosigner": "03d47c2e48c59b3f58b96c9e616d0a84c6e02725e47beefcb5b5a8fbe21a3c5e3a"
      }
    },
    "height": 857421,
    "idx": 0,
    "outpoint": "d7fe19af19332d8ab1d83ed82003ecc41c8c5def8e786b58e90512e82087302a:0",
    "owners": ["1G6CB3Ch4zFkPmuhZzEyChQmrQPfi86qk3"],
    "satoshis": 1000,
    "score": 85742100001
  },
  {
    "data": {
      "bsv21": {
        "amt": 50000,
        "dec": 5,
        "icon": "1FGEBTUu7EqWWK5DKrG6pxjEGLahpATnA8",
        "id": "ae59f3b898ec61acbdb6cc7a245fabeded0c094bf046f35206a3aec60ef88127_0",
        "op": "transfer",
        "sym": "MNEE"
      },
      "cosign": {
        "address": "1PqgNQwyPbc1Ue8QwEDFJUP2monKv9hSo4",
        "cosigner": "03d47c2e48c59b3f58b96c9e616d0a84c6e02725e47beefcb5b5a8fbe21a3c5e3a"
      }
    },
    "height": 857420,
    "idx": 1,
    "outpoint": "a9b2c3d4e5f678901234567890abcdef1234567890abcdef1234567890abcdef:1",
    "owners": ["1G6CB3Ch4zFkPmuhZzEyChQmrQPfi86qk3"],
    "satoshis": 1000,
    "score": 85742000002
  }
]
```

### UTXO Properties

#### Main Properties

* **outpoint**: The full UTXO identifier in format `txid:vout`
* **height**: The block height when this UTXO was created
* **idx**: The output index within the transaction
* **owners**: Array of addresses that can spend this UTXO
* **satoshis**: The BSV satoshis in this output (not MNEE amount)
* **score**: A sortable score based on height and index

#### BSV21 Data (`data.bsv21`)

* **amt**: The amount of MNEE tokens in atomic units (100,000 = 1 MNEE)
* **dec**: Number of decimal places (5 for MNEE)
* **icon**: The icon address for the token
* **id**: The token ID
* **op**: The operation type (typically "transfer")
* **sym**: The token symbol ("MNEE")

#### Cosigner Data (`data.cosign`)

* **address**: The cosigner address for this UTXO
* **cosigner**: The cosigner public key

### Common Use Cases

#### Calculate Total Spendable Balance

```typescript
// WARNING: Default only returns 10 UTXOs - may not be complete balance!
// Specify a larger size or use pagination for accurate balance
const utxos = await mnee.getUtxos(address, 0, 1000); // Get up to 1000 UTXOs
const totalAtomicUnits = utxos.reduce((sum, utxo) => sum + utxo.data.bsv21.amt, 0);
const totalMNEE = mnee.fromAtomicAmount(totalAtomicUnits);
console.log(`Total spendable: ${totalMNEE} MNEE`);

// For accurate balance, consider using the balance() method instead:
const balance = await mnee.balance(address);
console.log(`Total balance: ${balance.decimalAmount} MNEE`);
```

#### Get All UTXOs with Pagination

```typescript
async function getAllUtxosWithPagination(address) {
  const allUtxos = [];
  const pageSize = 100;
  let page = 0;
  
  while (true) {
    const utxos = await mnee.getUtxos(address, page, pageSize);
    allUtxos.push(...utxos);
    
    console.log(`Retrieved page ${page + 1}: ${utxos.length} UTXOs`);
    
    // If we got less than pageSize, we've reached the end
    if (utxos.length < pageSize) break;
    
    page++;
  }
  
  console.log(`Total UTXOs retrieved: ${allUtxos.length}`);
  return allUtxos;
}
```

#### Find UTXOs Above a Certain Amount

```typescript
const utxos = await mnee.getUtxos(address);
const largeUtxos = utxos.filter(utxo => utxo.data.bsv21.amt >= 10000); // 0.1 MNEE or more
console.log(`Found ${largeUtxos.length} UTXOs with 0.1 MNEE or more`);
```

#### Prepare UTXOs for Multi-Source Transfer

```typescript
const addresses = ['address1', 'address2', 'address3'];
const allUtxos = await mnee.getUtxos(addresses);

// Group UTXOs by owner address for transferMulti
const utxosByAddress = allUtxos.reduce((acc, utxo) => {
  const owner = utxo.owners[0];
  if (!acc[owner]) acc[owner] = [];
  acc[owner].push(utxo);
  return acc;
}, {});

// Convert to transferMulti format
const inputs = allUtxos.map(utxo => ({
  txid: utxo.outpoint.split(':')[0],
  vout: parseInt(utxo.outpoint.split(':')[1]),
  wif: 'private-key-for-owner' // You need to provide the WIF for each UTXO owner
}));
```

#### Filter UTXOs by Operation Type

```typescript
const utxos = await mnee.getUtxos(address);
const transferUtxos = utxos.filter(utxo => utxo.data.bsv21.op === 'transfer');
console.log(`Found ${transferUtxos.length} transfer UTXOs`);
```

### Performance Considerations

* The API returns only 10 UTXOs by default - specify a larger `size` parameter if you need more
* For addresses with many UTXOs, use pagination to retrieve all of them:

```typescript
// Get all UTXOs for an address
async function getAllUtxos(address) {
  const allUtxos = [];
  const pageSize = 100; // Balance between efficiency and memory
  let page = 0;
  let hasMore = true;
  
  while (hasMore) {
    const utxos = await mnee.getUtxos(address, page, pageSize);
    allUtxos.push(...utxos);
    hasMore = utxos.length === pageSize;
    page++;
  }
  
  return allUtxos;
}
```

### Important Notes

* **Default limit is 10 UTXOs** - Always specify the `size` parameter if you need more
* If an address has more UTXOs than your page size, use pagination to retrieve all of them
* For just checking balance, use the [`balance()`](/mnee-sdk/check-balance.md) method which is more efficient
* UTXOs are sorted by score (based on height and index) in descending order by default

### See Also

* [Balance](/mnee-sdk/check-balance.md) - Get balance without UTXO details (more efficient for balance checks)
* [Transfer Multi](/mnee-sdk/transfer-multi.md) - Use UTXOs for multi-source transfers
* [Get Enough UTXOs](/mnee-sdk/get-enough-utxos.md) - Get just enough UTXOs for and address and amount
* [Get All UTXOs](/mnee-sdk/get-all-utxos.md) - Get all UTXOs for a given address


---

# 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.mnee.io/mnee-sdk/get-utxos.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.