# How to Use

## Installation <a href="#installation" id="installation"></a>

```
yarn add @xchainjs/xchain-util
```

The following peer dependencies have to be installed into your project. These are not included in `@xchainjs/xchain-util`.

```
yarn add bignumber.js
```

## Development <a href="#development" id="development"></a>

#### Build <a href="#build" id="build"></a>

```
yarn build
```

#### Tests <a href="#tests" id="tests"></a>

```
yarn test
```

## Example for Asset Helpers <a href="#basic-example-usage-for-asset-helpers" id="basic-example-usage-for-asset-helpers"></a>

Imports

```
import {
  assetAmount,
  baseAmount,
  isAssetAmount,
  isBaseAmount,
  baseToAsset,
  assetToBase,
  formatAssetAmount,
  formatBaseAsAssetAmount,
  formatAssetAmountCurrency,
} from '@xchainjs/xchain-util'
```

#### Convert Between Asset and Base Vice Versa <a href="#convert-between-asset-and-base-vice-versa" id="convert-between-asset-and-base-vice-versa"></a>

Use the helper to convert between base amounts and Assets.\
The Decimal represents the denomination of the asset. i.e BTC\_DECIMAL = 8\
These are normally a constant exported by the client.

```
const assetConversions = async () => {

    let amountToTransfer = 0.01
    // convert to type baseAmount
    let amount = assetToBase(assetAmount(amountToTransfer, BTC_DECIMAL)) 
    console.log(`Amount has been converted to type base amount: ${JSON.stringify(amount)}`)
    // Convert back to asset amount
    let asset = (baseToAsset(amount).amount()) 
    console.log(`Converted back to ${asset}`)
}
```

#### Format Helpers for Assets <a href="#format-helpers-for-assets" id="format-helpers-for-assets"></a>

Format Assets from and to baseAmount Retrieve symbols using assets

```
// Imports 
import { 
    assetToBase,
    assetAmount, 
    formatAssetAmount,
    formatBaseAmount,
    formatBNCurrency,
    AssetBTC,
    AssetCurrencySymbol, 
    formatAssetAmountCurrency,
    currencySymbolByAsset, 
    AssetRuneNative,
    AssetETH,
    AssetLTC } from "@xchainjs/xchain-util"

// usage Example
const formatHelpers = async () => {
    let amountToTransfer = 0.01
    let Amount = assetToBase(assetAmount(amountToTransfer, DECIMAL))

    // Formats an `AssetAmount` into `string` based on decimal places
    let formatAsset = formatAssetAmount({ amount: assetAmount(amountToTransfer, BTC_DECIMAL), decimal: BTC_DECIMAL})  
    console.log(formatAsset)
    
    // Formats a `BaseAmount` value into a `string`
    let formatBase = formatBaseAmount(Amount)
    console.log(formatBase)

    // Formats a big number value by prefixing it with `$`
    let formatBN = formatBNCurrency(Amount.amount())
    console.log(formatBN)

    //  Formats an asset amount using its currency symbol
    let formatAssetCurrency = formatAssetAmountCurrency({ amount: assetAmount(amountToTransfer, BTC_DECIMAL), asset: AssetBTC, decimal: BTC_DECIMAL})
    console.log(formatAssetCurrency)

    // Returns Asset symbol from ticker. 
    let assetA = currencySymbolByAsset(AssetRuneNative)
    let assetB = currencySymbolByAsset(AssetBTC)
    let assetC = currencySymbolByAsset(AssetETH)
    let assetD = currencySymbolByAsset(AssetLTC)
     console.log(assetA, assetB, assetC, assetD)

    // Respective outputs
    /*0.01000000
    1,000,000
    $1,000,000.00
    ⚡ 1,000,000
    ᚱ ₿ Ξ LTC */
}

```

#### BigNumber Helper Functions <a href="#bignumber-helper-functions" id="bignumber-helper-functions"></a>

```
// Imports
import { 
    bnOrZero,
    validBNOrZero,
    fixedBN} from "@xchainjs/xchain-util"

const bigNumberhelpers = async () => {
    
    let amountToTransfer = 0.01
    let Amount = assetToBase(assetAmount(amountToTransfer, DECIMAL))

    // Helper to create a big number from string or number If it fails to create a big number
    console.log(bnOrZero(amountToTransfer))

    // Helper to validate a possible BigNumber If the given value is invalid or undefined
    console.log(validBNOrZero(Amount.amount()))

    // Helper to get a fixed BigNumber
    console.log(fixedBN(Amount.amount()))
}
```

#### Chain Helper <a href="#chain-helper" id="chain-helper"></a>

```
//Imports
import { isChain } from from "@xchainjs/xchain-util"

const chain = async () => {
    // Type guard to check whether string is based on type Chain
    let thor = "THOR"
    console.log(isChain(thor)) // Returns true
}
```

#### Async Helper <a href="#async-helper" id="async-helper"></a>

```
//Imports
import delay from '@xchainjs/xchain-util'

// Helper to delay anything within an async function
const anyAsyncFunc = async () => {
     // do something
    console.log('before delay')
    // wait for 200ms
    await delay(200)
    // and do other things
    console.log('after delay')
    
}
```


---

# 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://xchainjs.gitbook.io/xchainjs/others/xchain-util/how-to-use.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.