Bitcoin Transaction Example

Requesting Bitcoin-specific information via the API

Chains

curl --request GET \
     --url 'https://li.quest/v1/chains?chainTypes=UTXO' \
     --header 'accept: application/json'

Tools

curl --request GET \
  --url 'https://li.quest/v1/tools?chains=20000000000001' \
  --header 'accept: application/json'

Tokens

curl --request GET \
     --url 'https://li.quest/v1/tokens?chains=BTC' \
     --header 'accept: application/json'

Token details

curl --request GET \
     --url 'https://li.quest/v1/token?chain=20000000000001&token=bitcoin' \
     --header 'accept: application/json'

Requesting a Quote

Bitcoin to Ethereum

The quote and advanced route calls target the same transfer but differ in shape: GET /quote accepts query parameters such as fromChain and fromToken, whereas POST /advanced/routes expects a JSON body with fields like fromChainId and fromTokenAddress.

curl --request GET \
     --url 'https://li.quest/v1/quote?fromAddress=bc1qmdpxhzarlxrygtvlxrkkl0eqguszkzqdgg4py5&fromAmount=500000&fromChain=BTC&fromToken=bitcoin&toAddress=0x39333638696578786b61393361726b63717a6773&toChain=1&toToken=0x0000000000000000000000000000000000000000' \
     --header 'accept: application/json'

curl --request POST \
     --url https://li.quest/v1/advanced/routes \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "toTokenAddress": "0x0000000000000000000000000000000000000000",
  "fromTokenAddress": "bitcoin",
  "fromChainId": 20000000000001,
  "fromAmount": "10000000",
  "toChainId": 1,
  "fromAddress": "YOUR_BTC_WALLET",
  "toAddress": "YOUR_EVM_WALLET"
}
'

Ethereum to Bitcoin

curl --request GET \
     --url 'https://li.quest/v1/quote?fromChain=1&toChain=20000000000001&fromToken=0x0000000000000000000000000000000000000000&toToken=bitcoin&fromAddress=0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0&toAddress=bc1qmdpxhzarlxrygtvlxrkkl0eqguszkzqdgg4py5&fromAmount=500000000000000000' \
     --header 'accept: application/json'

curl --request POST \
     --url https://li.quest/v1/advanced/routes \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "toTokenAddress": "bitcoin",
  "fromTokenAddress": "0x0000000000000000000000000000000000000000",
  "fromChainId": 1,
  "fromAmount": "500000000000000000",
  "toChainId": 20000000000001,
  "fromAddress": "YOUR_EVM_WALLET",
  "toAddress": "YOUR_BTC_WALLET"
}
'

Executing the transaction

Building Custom Bitcoin Transactions

Partners may want to build custom Bitcoin transactions to select specific UTXOs for various reasons such as coin control, UTXO consolidation, or fee optimization. Requirements when building custom transactions:

Preserve the exact output structure and order from the API response
Ensure selected UTXOs have sufficient value to cover:
- Bridge deposit amount (1st output)
- Refund output if required by the bridge (3rd output, must be above dust threshold)
- Integrator fees (additional outputs)

Critical: The output order and structure cannot be modified. Deviating from the API response structure will result in stuck or failed transactions.

Transaction Data

BTC to Ethereum, Avalanche, or BNB Smart Chain (BSC) After retrieving the quote, the funds need to be sent to the BTC vault address provided in the response, along with a memo. Memo Functionality: Similar to Thorchain, LI.FI uses memos for BTC to EVM swaps. Depending on the tool, the memo in the BTC transaction specifies the bridge-specific tx data to execute and internal LI.FI details for the tracking. Transaction Handling: The transaction that leaves BTC and goes to EVM needs to be sent to an EVM address. The memo ensures that the swap details are correctly processed by the validators.

NOTE: Only send transactions in a timely manner (~30 min). It is always recommended to request an up-to-date quote to ensure to get the latest information.

Risk of modifying Bitcoin transaction dataModifying PSBT or raw Bitcoin transaction data received from our API (for example removing outputs, changing amounts, or editing opcodes/scripts) can invalidate signatures or spending conditions and lead to irreversible loss of funds.Do not alter PSBTs unless you are an expert and have explicitly confirmed with us the modification you intend to make.

The following is an example of transaction data

"transactionRequest": {
    "to": "bc1qawcdxplxprc64fh38ryy4crndmfgwrffpac743", //thorswap vault to send BTC to
    "data": "=:ETH.USDC:0x29DaCdF7cCaDf4eE67c923b4C22255A4B2494eD7::lifi:0|0x4977d81c2a5d6bd8",
    "value": "500000"
  }

Extracting Transaction Data from PSBT

When building custom Bitcoin transactions with selected UTXOs, partners need to extract the memo and other transaction details from the PSBT (Partially Signed Bitcoin Transaction) returned by the API. Key Information:

The memo is contained in the OP_RETURN output (2nd output) of the PSBT
This memo must be preserved exactly as provided - it contains bridge-specific calldata and LI.FI tracking details
The depositor address is in the 1st output
The refund address (if required) is in the 3rd output

Partners can parse the PSBT to extract these values and reconstruct the transaction with their selected UTXOs while maintaining the exact output structure.

Bitcoin transaction requirements per tool

Critical: Output Structure Cannot Be ModifiedThe output order and structure provided by the API must be replicated exactly. Changing the order, removing outputs, or modifying amounts will result in stuck transactions. Partners building custom transactions must preserve the exact structure while only changing the input UTXOs.

The general requirements for the outputs structure are the following:

1st output: Bridged amount sent to the bridge depositor address
2nd output: OP_RETURN containing the memo with bridge-specific and LI.FI tracking details (must be preserved exactly)
3rd output: Refund output back to sender’s address (optional for some bridges, mandatory for others - see details below)
Remaining outputs: Integrator-specific fee transfers

Dust Threshold Requirements: All outputs containing value must exceed the dust threshold, which is determined by the output address type:

Pay To Witness Public Key Hash (p2wpkh) - 294 sats
Pay To Witness Script Hash (p2wsh) - 330 sats
Pay To Script Hash (p2sh) - 540 sats
Pay To Public Key Hash (p2pkh) - 546 sats
Pay To Taproot (p2tr) - 330 sats

Bridge Requirements Summary

Thorswap

The memo (OP_RETURN output) contains Thorswap calldata to be executed and LI.FI tracking id. It’s important to keep both to avoid stuck or failed transactions.

// Memo example
=:ETH.USDC:0x29DaCdF7cCaDf4eE67c923b4C22255A4B2494eD7::lifi:0|0x4977d81c2a5d6bd8

Unit

Unit bridge doesn’t have any bridge-specific details stored in memo so it includes only LI.FI tracking details.

// Memo example
// =|lifi02bf57fe

Symbiosis

Symbiosis bridge doesn’t have any bridge-specific details stored in memo so it includes only LI.FI tracking details.

// Memo example
=|lifi02bf57fe

Incorrect transaction structure will cause stuck transfers that require manual refund intervention. Ensure the output order matches the API response exactly.

Relay

The memo (OP_RETURN output) contains Relay calldata to be executed and LI.FI tracking id. It’s important to keep both to avoid stuck or failed transactions.

// Memo example
0x986c2efd25b8887e9c187cfe2162753567339b6313e7137b749e83d4a1a79b03=|lifi92c9cbbc5

Chainflip

Chainflip PSBT requires to have three outputs as described above. The refund output is required, if it’s skipped, the transaction will not be correctly processed. The memo (OP_RETURN output) contains Chainflip payload to be executed and LI.FI tracking id. It’s important to keep both to avoid stuck or failed transactions.

// Memo example
0x01071eb6638de8c571c787d7bc24f98bfa735425731c6400f4c5ef05000000000000000000000000ff010002001e0200=|lifi92c9cbbc5

CRITICAL: Chainflip Fund Loss RiskChainflip transactions with incorrect output structure will result in permanent, unrecoverable loss of funds. Unlike other bridges, Chainflip cannot manually refund stuck transactions.Mandatory Requirements:

All three outputs must be present in exact order: (1) deposit amount, (2) OP_RETURN memo, (3) refund output
Refund output (3rd output) is mandatory and must be above dust threshold
Do not modify, remove, or reorder any outputs from the API response

Failure to follow these requirements exactly will result in irreversible fund loss with no recovery option.

Learn About LI.FI

Supported Systems

LI.FI Architecture

User Flows and Examples

Learn More

Changelog

Bitcoin Transaction Example

Requesting Bitcoin-specific information via the API

Chains

Tools

Tokens

Token details

Requesting a Quote

Bitcoin to Ethereum

Ethereum to Bitcoin

Executing the transaction

Building Custom Bitcoin Transactions

Transaction Data

Extracting Transaction Data from PSBT

Bitcoin transaction requirements per tool

Bridge Requirements Summary

Thorswap

Unit

Symbiosis

Relay

Chainflip

​Requesting Bitcoin-specific information via the API

​Chains

​Tools

​Tokens

​Token details

​Requesting a Quote

​Bitcoin to Ethereum

​Ethereum to Bitcoin

​Executing the transaction

​Building Custom Bitcoin Transactions

​Transaction Data

​Extracting Transaction Data from PSBT

​Bitcoin transaction requirements per tool

​Bridge Requirements Summary

Thorswap

Unit

Symbiosis

Relay

Chainflip

Requesting Bitcoin-specific information via the API

Chains

Tools

Tokens

Token details

Requesting a Quote

Bitcoin to Ethereum

Ethereum to Bitcoin

Executing the transaction

Building Custom Bitcoin Transactions

Transaction Data

Extracting Transaction Data from PSBT

Bitcoin transaction requirements per tool

Bridge Requirements Summary