# Balances

Documentation Link: [Here](https://bitbadges.github.io/bitbadgesjs/packages/bitbadgesjs-sdk/docs) -> Balances

### Tutorial: Using the TypeScript SDK for Balance Operations

**1. Define the Balance**

Here's how you create a balance using the provided `Balance` interface:

<pre class="language-typescript"><code class="lang-typescript"><strong>const userBalance = BalanceArray.From([{
</strong>  "amount": 5n, // example amount using the BigInt type
  "tokenIds": [{ start: 1n, end: 5n }],
  "ownershipTimes": [{ start: 1628770800000n, end: 1628857200000n }] // example timestamps using BigInt
}])
</code></pre>

Note: The `UintRange` type is assumed to be an object with `start` and `end` properties of type `bigint`. Adjust as necessary based on the actual definition.

**2. Add Balance**

To add a balance to an array of existing balances:

```typescript
const balanceToAdd = {
    amount: 3n,
    tokenIds: [{ start: 6n, end: 8n }],
    ownershipTimes: [{ start: 1628860800000n, end: 1628947200000n }],
};
userBalance.addBalances([balanceToAdd]);
```

This will add `balanceToAdd` to the list of existing balances.

**3. Subtract Balance**

To subtract a balance from an array of existing balances:

```typescript
const balanceToRemove = {
    amount: 2n,
    tokenIds: [{ start: 2n, end: 3n }],
    ownershipTimes: [{ start: 1628784400000n, end: 1628870800000n }],
};
userBalance.subtractBalances([balanceToRemove], false); //second param is to allow underflow (negatives)
```

**Conclusion**

This SDK provides a clear and structured way to manage and operate on balances. With the `addBalance` and `subtractBalance` functions, you can effortlessly update and maintain balances in your application.\
\
Given the new functions you've shared, I'll provide a tutorial snippet for each of them.

### Tutorial: Retrieving Balances Based on Token ID and Time

**1. Get Balance for a Specific ID and Time**

If you need to retrieve the balance for a specific token ID and a specific ownership time, you can use the `getBalanceForIdAndTime` function:

```typescript
const tokenIdToLookup = 3n;
const timeToLookup = 1628784400000n; // example timestamp using BigInt
const specificBalance = balances.getBalanceForIdAndTime(
    tokenIdToLookup,
    timeToLookup
);

console.log(specificBalance); // This will show the balance for the specified token ID and time, if found.
```

**2. Get Balances for a Specific Token ID**

To get all balances associated with a specific token ID:

```typescript
const tokenIdToLookup = 4n;
const balances = balances.getBalancesForId(tokenIdToLookup);

console.log(balances); // This will display all the balances for the given token ID.
```

**3. Get Balances for a Specific Time**

If you need to retrieve all balances for a specific ownership time:

```typescript
const timeToLookup = 1628784400000n;
const timeSpecificBalances = balances.getBalancesForTime(timeToLookup);

console.log(timeSpecificBalances); // This will show all the balances that have the specified ownership time.
```

Alright, given the new function `getBalancesForIds` which retrieves balances for a range of token IDs and a range of times, let's create a tutorial snippet for it:

4. **Get Balances for Specific Ranges of Token IDs and Times**

If you need to retrieve balances for a range of token IDs and a range of ownership times, you can utilize the `getBalancesForIds` function:

```typescript
// Define the range of token IDs and times you want to look up
const idRangesToLookup = [
    { start: 1n, end: 3n },
    { start: 5n, end: 7n },
];

const timeRangesToLookup = [
    { start: 1628770800000n, end: 1628857200000n }, // example timestamp range using BigInt
    { start: 1628943600000n, end: 1629030000000n }, // another timestamp range
];

// Retrieve the balances
const specificBalances = balances.getBalancesForIds(
    idRangesToLookup,
    timeRangesToLookup
);
console.log(specificBalances); // This will show the balances that fall within the specified token ID ranges and time ranges.
```

**Conclusion**

The provided functions in this SDK make it easy to retrieve specific balances based on different criteria, such as token ID and ownership time. Utilize these functions to access and display relevant data as per your application's requirements.


---

# 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.bitbadges.io/for-developers/bitbadges-sdk/common-snippets/balances.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.