Skip to main content

​
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'

​
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'

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