> For the complete documentation index, see [llms.txt](https://xchainjs.gitbook.io/xchainjs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xchainjs.gitbook.io/xchainjs/clients/xchain-utxo/xchain-bitcoin/how-to-use.md).

# How to use

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

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

### Peer Dependencies

You can visit the [xchain-bitcoin](https://github.com/xchainjs/xchainjs-lib/blob/master/packages/xchain-bitcoin/package.json) package repository to get the updated peer dependencies by looking at the "peerDependencies" object in the "package.json" file.

### Testing <a href="#bitcoin-client-testing" id="bitcoin-client-testing"></a>

```
yarn install
yarn test
```

## Examples <a href="#basic-usage-examples" id="basic-usage-examples"></a>

#### Connect Wallet to New Client and Access Class Methods <a href="#connect-wallet-to-new-client-and-access-class-methods" id="connect-wallet-to-new-client-and-access-class-methods"></a>

Decrypt keystore returns `phrase`\
Create a new client instance\
Use the client to getAddress() & getBalance() of address\
The network default is Mainnet

```
//Imports
import { Client } from "@xchainjs/xchain-bitcoin"

// Connect wallet to new btc client 
const connectWallet = async () => {
    let phrase = "phrase"
    const btcClient = new Client({ phrase})
    let address = btcClient.getAddress()     
    console.log(`Asset Address is: ${address}`)

    let balances = await btcClient.getBalance(address)
    try { 
        let assetAmount = (baseToAsset(balances[0].amount)).amount()
        console.log(`Asset address balance: ${assetAmount}`)
    } catch (error) {
        console.log('Address has no balance')
    }
}
```

#### Transfer BTC Using btcClient <a href="#transfer-btc-using-btcclient" id="transfer-btc-using-btcclient"></a>

Default feeRate is `fast`\
Import helper functions from `@xchainjs/xchain-util`\
Decrypt keystore to retrieve a phrase\
Use utils to convert to BaseAmount for tx params\
Build TX using parameters\
Client.transfer() > returns `Promise<string>` - The transaction hash

```
//Imports
import { assetToBase, baseToAsset, assetAmount, AssetBTC } from "@xchainjs/xchain-util"

let amountToTransfer = 0.0001
let recipient = 'Recipent_address'

const transfer = async () => {
    let phrase = "phrase"
    let btcClient = new Client({phrase })
    let amount = assetToBase(assetAmount(amountToTransfer, 8))
    try {
        const txid = await btcClient.transfer({
            'asset': AssetBTC,
            'recipient': recipient,
            'amount': amount,
            'memo': "payment"
        })
        console.log(`Amount: ${amount.amount().toString()} ${AssetBTC.symbol} Transaction id: ${txid}`)
    } catch (error){
        console.log(`Transfer failed ${error}`)
    }
}

```

#### Transfer & Set feeRate <a href="#transfer--set-feerate" id="transfer--set-feerate"></a>

Build transactions using parameters\
Set feeRate in transaction parameters\
Or use getFeeRates()

```
//Returns FeeRates > this allows for dynamic feeRate adjustment on selection
const { fast, fastest, average } = await btcClient.getFeeRates()

try {
        const txid = await btcClient.transfer({
            'asset': AssetBTC,
            'recipient': recipient,
            'amount': amount,
            'memo': "test transfer",
            feeRate: fast
        })
        console.log(`Amount ${baseToAsset(amount).amount()} ${AssetBTC.symbol} Transaction id ${txid}`)
    } catch (error){
        console.log(`Transfer failed ${error}`)
    }
```

#### Get Fees & FeeRates Estimations <a href="#get-fees--feerates-estimations" id="get-fees--feerates-estimations"></a>

Client function getFees() returns an object\
`Fast: {"type":"BASE","decimal":8}`

```
//Get Fees - returns FeeOption & fee in BaseAmount 
` Fees Fast: 0.00001 Fastest: 0.0000468 Average: 0.00001 `
    try{
        const { fast, fastest, average } = await btcClient.getFees()
        console.log(`Fees Fast: ${baseToAsset(fast).amount()} Fastest: ${baseToAsset(fastest).amount()} Average: ${baseToAsset(average).amount()}`)

    }catch (error){
        console.log(error)
    }

//Get FeeRates - returns FeeOption & rate  
` Fast: 12, Fastest 60, Average: 6 `

    try{
        const { fast, fastest, average } = await btcClient.getFeeRates()
        console.log(`Fast: ${fast}, Fastest ${fastest}, Average: ${average}`)

    }catch (error){
        console.log(error)
    }

```

#### Get Transaction Data <a href="#get-transaction-data" id="get-transaction-data"></a>

Create a new btcClient instance\
Call getTransaction(hash) returns JSON object

```
const transactionData = async () => {
    let phrase = "phrase"
    let btcClient = new Client({network: Network.Mainnet, phrase })
    let hash = "txhash string" 
    try{
        const txData = await btcClient.getTransactionData(hash)
        console.log(`From ${JSON.stringify(txData)}`)

    }catch (error) {
        console.log(`Error: ${error}`)
    }
}

```

#### Get Transaction History <a href="#get-transaction-history" id="get-transaction-history"></a>

Search the client for transaction history\
Create a new client instance\
Call a function with a variable `address`\
Results can be filtered with extra parameters { offset, limit, startTime, asset?}

```
const transactionHistory = async () => {
    let phrase = "phrase"
    let btcClient = new Client({phrase })
    let Address = keystore1Address

    try {
        const txHistory = await btcClient.getTransactions({ address: Address, limit: 4 })
        console.log(`Found ${txHistory.total.toString()}`)
        txHistory.txs.forEach(tx => console.log(tx.hash))

    } catch (error) {
            console.log(`Error: ${error}`)
    }
}
```