# Bitcoin Swap API

Broker as a Service (BaaS) swaps native BTC to and from every other supported chain, through the REST API and the [MCP server](https://docs.chainflip-broker.io/resources/ai-documentation/). This page collects what is specific to Bitcoin: minimums, addresses, deposits and refunds, vault swaps and Boost. For the general flow, start with [Starting a Swap](https://docs.chainflip-broker.io/features/start-swap/) and [View Available Assets](https://docs.chainflip-broker.io/features/view-assets/).

## Assets and minimums

| Asset | id | Decimals | Minimum | Native minimum | Contract |
| --- | --- | ---: | ---: | --- | --- |
| BTC | `btc.btc` | 8 | 0.0004 BTC | `40000` | — |

*Snapshot captured on 2026-11-17 from the production [`/assets`](https://docs.chainflip-broker.io/features/view-assets/) endpoint. Minimums are Chainflip's current source (ingress) minimum deposit amounts; query `/assets` for live values. Destination-side egress minimums depend on gas and are not in `/assets`; see [Error Codes](https://docs.chainflip-broker.io/features/error-codes/) for `egress_below_minimum` and `egress_fee_not_covered`. `minimalAmountNative` is in the asset's smallest unit (satoshis for BTC). Assets disabled upstream are omitted.*

## Addresses

BaaS checks Bitcoin addresses against the network of the environment you call:

* Production (mainnet) accepts the standard address types: P2PKH (`1…`), P2SH (`3…`), P2WPKH and P2WSH (`bc1q…`) and P2TR (`bc1p…`).
* The [Testing](https://docs.chainflip-broker.io/environments/testing/) environment accepts their testnet forms: `m…`/`n…`, `2…` and `tb1…`.

Each environment rejects the other network's addresses, so a testnet address answers `400` on production. Bitcoin addresses carry no memo or tag. A Bitcoin destination address is checked with the Bitcoin rules; a refund address is always checked against the source asset's chain, so a BTC `refundAddress` must be a Bitcoin address.

## Deposits and refunds

A [`/swap`](https://docs.chainflip-broker.io/features/start-swap/) call opens a deposit channel and returns the `address` the user sends BTC to.

* Deposit channels close after 24 hours. Open a new channel for every deposit-channel swap and send the deposit immediately ([Chainflip: closure of deposit channels](https://docs.chainflip.io/brokers/broker-deposit-channels-swaps#closure-of-deposit-channels)).
* `minimumPrice` and `refundAddress` are required.
* `retryDurationInBlocks` is optional: omitted or negative, it is the 150-block (15-minute) default, and a value above Chainflip's current runtime limit is lowered to that limit. Use the quote's `recommendedRetryDurationInBlocks`: Chainflip recommends 300 blocks when BTC is on either side.
* If the minimum price or live price protection is not met within the retry window, the BTC is refunded to `refundAddress`. For DCA, only unexecuted chunks are refunded; executed chunks still pay out to the destination.

See [Starting a Swap](https://docs.chainflip-broker.io/features/start-swap/#slippage-protection) and Chainflip's [Swapping Basics](https://docs.chainflip.io/protocol/swapping-basics#slippage-protection).

Bitcoin is the slowest chain to witness: Chainflip's [ingress table](https://docs.chainflip.io/protocol/ingress-witnessing-deposits#the-witness-process) lists a 2-block safety margin at about 10 minutes per block, and BaaS estimates about half an hour for a Bitcoin deposit without Boost. Expect tens of minutes, or minutes with [Boost](https://docs.chainflip-broker.io/chains/bitcoin/#boost). Show users the quote's `estimatedDurationSeconds` rather than a fixed number.

## Vault swaps

A Bitcoin vault swap needs no deposit channel. [`/tx-payload/bitcoin`](https://docs.chainflip-broker.io/features/tx-payload/) returns `network`, `nulldataPayload` and `depositAddress`, and your application builds and signs one Bitcoin transaction whose first three outputs are, exactly and in this order:

1. The swap amount, sent to `depositAddress`.
2. An OP_RETURN output carrying `nulldataPayload`.
3. A change output. Its address is the refund address, and its amount must be above Bitcoin's dust threshold.

Bitcoin vault swaps differ from the other chains:

* Instead of `sourceAmount`, `minimumPrice` and `refundAddress`, the endpoint takes `destinationMinimumAmount`: the minimum output in the smallest unit of the destination asset. The change output is the refund address.
* `boostFee` is accepted, as on `/swap`.
* The payload stores the live price tolerance in one byte, so `livePriceSlippageTolerancePercent` above `2.54` is lowered to `2.54`.
* A payload expires after two Chainflip epoch rotations, between 3 and 6 days at the time of writing. Build and broadcast a fresh one rather than storing it.
* Cross-chain messages (CCM) are not supported on Bitcoin vault swaps.

See Chainflip's [Bitcoin Vault Swaps](https://docs.chainflip.io/brokers/vault-swaps-api/bitcoin) for the protocol details.

## Boost

Boost gets a Bitcoin deposit credited after one block instead of waiting for the full safety margin, in return for a small fee.

* `boostFee` on [`/swap`](https://docs.chainflip-broker.io/features/start-swap/#boost) is the maximum accepted Boost fee in basis points, from `0` to `100` (0–1%). BaaS advises `30`: the user only pays the lowest fee that was enough to boost the deposit.
* When Boost liquidity is available, Chainflip pre-witnesses the deposit after one block. When it is not, the deposit is witnessed with the regular confirmations and no Boost fee is charged.
* A second deposit is only boosted after the first one has been finalised.
* If a boosted swap is refunded, the Boost fee is not refunded.

The [Boost quote](https://docs.chainflip-broker.io/features/ask-quote/#boost) shows the boosted fee and duration before you commit. Protocol details: Chainflip's [Boost](https://docs.chainflip.io/protocol/boost).

## Known pitfalls

* **Slow confirmations.** Without Boost a swap waits for Bitcoin blocks; set `retryDurationInBlocks` from the quote and show the quote's duration.
* **Vault payload expiry.** An old `nulldataPayload` stops working after two epoch rotations; request a new one per transaction.
* **Dust change.** The change output is mandatory and must be above the dust threshold, because it is where a refund goes.
* **Output order.** The deposit, OP_RETURN and change outputs must be the first three outputs, in that order.
* **No CCM.** Bitcoin vault swaps cannot carry a cross-chain message.
* **Network mismatch.** Production takes mainnet addresses only; testnet addresses belong on the [Testing](https://docs.chainflip-broker.io/environments/testing/) environment.

## Related

* [Starting a Swap](https://docs.chainflip-broker.io/features/start-swap/)
* [Vault Swap Transaction Payloads](https://docs.chainflip-broker.io/features/tx-payload/)
* [View Available Assets](https://docs.chainflip-broker.io/features/view-assets/)
* [View Available Networks](https://docs.chainflip-broker.io/features/view-networks/)
* [Error Codes](https://docs.chainflip-broker.io/features/error-codes/)
* [Testing Environment](https://docs.chainflip-broker.io/environments/testing/)
* [Bitcoin Hackathon](https://docs.chainflip-broker.io/guides/bitcoin-hackathon/)
