Skip to main content

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. 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 and View Available Assets.

Assets and minimums​

AssetidDecimalsMinimumNative minimumContract
BTCbtc.btc80.0004 BTC40000—

Snapshot captured on 2026-11-17 from the production /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 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 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 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).
  • 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 and Chainflip's Swapping Basics.

Bitcoin is the slowest chain to witness: Chainflip's ingress table 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. Show users the quote's estimatedDurationSeconds rather than a fixed number.

Vault swaps​

A Bitcoin vault swap needs no deposit channel. /tx-payload/bitcoin 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 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 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 shows the boosted fee and duration before you commit. Protocol details: Chainflip's 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 environment.