> ## Documentation Index
> Fetch the complete documentation index at: https://docs.li.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitcoin Transaction Example

## Requesting Bitcoin-specific information via the API

### Chains

```JS theme={"system"}
curl --request GET \
     --url 'https://li.quest/v1/chains?chainTypes=UTXO' \
     --header 'accept: application/json'
```

### Tools

```JS theme={"system"}
curl --request GET \
  --url 'https://li.quest/v1/tools?chains=20000000000001' \
  --header 'accept: application/json'
```

### Tokens

```JS theme={"system"}
curl --request GET \
     --url 'https://li.quest/v1/tokens?chains=BTC' \
     --header 'accept: application/json'
```

### Token details

```JS theme={"system"}
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`.

<CodeGroup>
  ```javascript /quote theme={"system"}
  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'
  ```

  ```javascript /advanced/routes theme={"system"}
  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"
  }
  '
  ```
</CodeGroup>

### Ethereum to Bitcoin

<CodeGroup>
  ```javascript /quote theme={"system"}
  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'
  ```

  ```javascript /advanced/routes theme={"system"}
  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"
  }
  '
  ```
</CodeGroup>

## 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>
  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.
</Note>

<Warning>
  **Risk of modifying Bitcoin transaction data**

  Modifying 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.
</Warning>

The following is an example of transaction data

```JS theme={"system"}
"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

<Warning>
  **Critical: Output Structure Cannot Be Modified**

  The 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.
</Warning>

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.

```JS theme={"system"}
// 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.

```JS theme={"system"}
// Memo example
// =|lifi02bf57fe
```

##### **Symbiosis**

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

```JS theme={"system"}
// Memo example
=|lifi02bf57fe
```

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

##### **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.

```JS theme={"system"}
// 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.

```JS theme={"system"}
// Memo example
0x01071eb6638de8c571c787d7bc24f98bfa735425731c6400f4c5ef05000000000000000000000000ff010002001e0200=|lifi92c9cbbc5
```

<Warning>
  **CRITICAL: Chainflip Fund Loss Risk**

  Chainflip 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.
</Warning>