Transfer assets

ChainGate lets you transfer funds from your wallet to any valid recipient address across a wide range of supported blockchains. Whether you're using a UTXO-based chain (like Bitcoin, Litecoin, or Dogecoin) or an EVM-based chain (like Ethereum, BNB, Polygon, or Arbitrum), the API provides a consistent way to prepare, sign, and broadcast transactions – abstracting away many network-specific differences.

Transaction fees

Every blockchain transaction incurs a fee. This fee compensates miners or validators for processing your transaction and is essential for ensuring that your transfer is included in the blockchain. Always ensure you have enough funds to cover both the transaction amount and its fee.

Basic transaction flow

Below is a generic example that works with any supported currency. It demonstrates how to create a transfer, fetch suggested fees, and broadcast the transaction.

// 1. Get a currency instance from the wallet
const currency = wallet.currency('bitcoin')

// 2. Specify the amount to send
//    `currency.amount(...)` converts a string into an internal, chain-aware amount object.
const amountToSend = await currency.amount('0.00005', 'btc')

// 3. Create a transfer
const transfer = await currency.createTransfer(
  'bc1qlh7kx4dbad4cqapc9tpugfj0n799z5myq3rd93',  // recipient address
  amountToSend                                   // chain-aware amount object
)

// 4. Get suggested fees (levels: low, normal, high, maximum)
const suggestedFees = await transfer.getSuggestedFees()

// 5. Choose a fee level and broadcast the transaction
if (suggestedFees.normal.enoughFunds) {
  const txResult = await transfer.broadcast('normal')
  console.log('Broadcasted Tx ID:', txResult.txId)
} else {
  console.log('Insufficient funds for the normal fee level.')
}

currency.amount(...)

Use currency.amount(value, unit) to safely convert a numeric string into a properly scaled internal amount.

• Example: currency.amount('1.5', 'eth') ensures the library knows it’s 1.5 ETH, not 1.5 wei.

Encrypted wallets

If your wallet is encrypted, you will be prompted for a password when broadcasting the transaction.
Implement askForPassword in your wallet initialization (or a similar method) to handle this prompt.

What are suggested fees?

When you call transfer.getSuggestedFees(), ChainGate returns a set of pre-calculated fee levels for the target blockchain. This allows you to balance between transaction cost and confirmation speed without needing to understand all the underlying fee mechanics.

Available fee levels

Level	Description
low	Cheapest option, but slower confirmation
normal	A balanced option for typical transactions
high	Higher fee for faster confirmation
maximum	Highest fee for the fastest possible confirmation

Each fee level object includes the following properties:

• isApproximate: A boolean indicating if the fee is an estimate.
• enoughFunds: true if your balance is sufficient to cover both the transaction amount and the fee.
• confirmationTimeSecs: Estimated time (in seconds) until the transaction is confirmed.
• feeAmount: Currency amount representing the total fee to be paid.

Example:

const fees = await transfer.getSuggestedFees()

console.log('Is approximate?', fees.normal.isApproximate)
console.log('Enough funds?', fees.normal.enoughFunds)
console.log('Estimated confirmation time (secs):', fees.normal.confirmationTimeSecs)
console.log('Fee amount:', fees.normal.feeAmount?.str)

Manual (custom) fees

Instead of using suggested fees, you can manually specify your own fee parameters. This is useful when you want full control over cost and speed. The approach differs slightly depending on whether the blockchain is UTXO-based or EVM-based.

UTXO-based blockchains (e.g., Bitcoin)

For UTXO-based blockchains, you can specify fees in:

• BTC/kB (or similar, like LTC/kB or DOGE/kB)
• satoshi/byte

// 1. Get the currency instance
const bitcoin = wallet.currency('bitcoin')

// 2. Create a transfer
const transfer = await bitcoin.createTransfer(
  'bc1q...', 
  await bitcoin.amount('0.00005', 'btc')
)

// 3. Set a manual fee, e.g. 0.00002 BTC per kilobyte:
const customFee = await transfer.fee('0.00002', 'btc/kB')
// Alternatively, specify fee in satoshi per byte:
// const customFee = await transfer.fee('25', 'satoshi/byte')

// 4. Broadcast if you have enough funds
if (customFee.enoughFunds) {
  console.log('Custom fee amount:', customFee.feeAmount?.str)
  const tx = await transfer.broadcast(customFee)
  console.log('Custom Fee Tx ID:', tx.txId)
} else {
  console.log('Not enough funds to cover the custom fee and amount.')
}

EVM-based blockchains (e.g., Ethereum)

For EVM-based chains, fees are determined by gas parameters. You can set:

• maxFeePerGas: The maximum gas price you are willing to pay.
• maxPriorityFeePerGas: The additional tip for miners/validators.

// 1. Get the currency instance
const ethereum = wallet.currency('ethereum')

// 2. Create a transfer
const transfer = await ethereum.createTransfer(
    '0xF3eD6Fe1ab2DaB6BBA9Cf451354106736d7c58EB',
    await ethereum.amount('0.0025', 'eth')
)

// 3. Create the fee using amounts in **wei**
const maxFeePerGas = await ethereum.amount('30000000000', 'wei')        // 30 gwei
const maxPriorityFeePerGas = await ethereum.amount('2000000000', 'wei') // 2 gwei

const customFee = await transfer.fee(maxFeePerGas, maxPriorityFeePerGas)

// 4. Broadcast if you have enough funds
if (customFee.enoughFunds) {
    console.log('Custom fee amount:', customFee.feeAmount?.str)
    const tx = await transfer.broadcast(customFee)
    console.log('Custom Fee Tx ID:', tx.txId)
} else {
    console.log('Not enough funds to cover the custom fee and amount.')
}

4. Having enough funds

To successfully broadcast a transaction, your wallet must have sufficient balance to cover both the transaction amount and the fee. Always check the enoughFunds property in the fee object. If this property is false, the transaction will fail or an error will be thrown.

Key points

• Uniform API: Use createTransfer(), getSuggestedFees(), fee(), and broadcast() for any supported currency.
• currency.amount(...): Converts string values to properly scaled amounts based on the currency (e.g., ETH vs. wei, BTC vs. satoshis).
• Suggested fees: These are pre-calculated fee levels (low, normal, high, maximum) that balance cost and speed. Each level includes properties such as isApproximate, enoughFunds, confirmationTimeSecs, and feeAmount.
• Custom fees: Use transfer.fee(...) to manually set fee parameters. The method varies between UTXO-based and EVM-based chains.
• Sufficient balance required: You must have enough funds to cover both the transaction amount and the fee.
• Signing at broadcast: Actual signing occurs during the broadcast. If your wallet is encrypted, you will be prompted for a password at that time.