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