Bitcoin bridging on Cross-Chain API

0x Cross-Chain API now supports swaps to and from the Bitcoin network. Wallets, exchanges, and other DeFi apps can now easily offer a Bitcoin bridge alongside their existing cross-chain swaps.

Let your users swap part of their Bitcoin holdings into other networks, or convert tokens back to native BTC held at a Bitcoin address. Bridge the gap between your app and your users’ Bitcoin holdings, and let your users put their capital to work in DeFi.

How Bitcoin bridging works on 0x

Request a quote from /cross-chain/quotes. Set originChain to bitcoin when selling BTC, or destinationChain to bitcoin when buying it. Use the native BTC token identifier shown below, and express BTC sell amounts in satoshis.

The quote-only example below shows a BTC-to-USDC request, with Base as the destination chain. Set ZEROX_API_KEY, USER_BITCOIN_ADDRESS, and USER_EVM_ADDRESS in your environment, then run it as a Node.js ES module.

const { ZEROX_API_KEY, USER_BITCOIN_ADDRESS, USER_EVM_ADDRESS } = process.env;
if (!ZEROX_API_KEY || !USER_BITCOIN_ADDRESS || !USER_EVM_ADDRESS) {
    throw new Error('Set ZEROX_API_KEY, USER_BITCOIN_ADDRESS, and USER_EVM_ADDRESS');
}

const quotesParams = new URLSearchParams({
    originChain: 'bitcoin', // Bitcoin mainnet
    destinationChain: 'base', // Base mainnet
    sellToken: 'bc1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmql8k8', // native BTC
    buyToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
    sellAmount: '1000000', // 0.01 BTC (8 decimals)
    originAddress: USER_BITCOIN_ADDRESS, // Bitcoin address that holds the BTC
    destinationAddress: USER_EVM_ADDRESS, // Base address that receives the USDC
    sortQuotesBy: 'price',
    maxNumQuotes: '3',
});

const headers = { '0x-api-key': ZEROX_API_KEY };
const response = await fetch('https://api.0x.org/cross-chain/quotes?' + quotesParams.toString(), { headers });
if (!response.ok) {
    throw new Error(`Quote request failed: ${response.status}`);
}
const quoteResponse = await response.json();

For a Bitcoin-origin swap, the quote returns a partially signed Bitcoin transaction (PSBT) to sign and broadcast. Track execution through /cross-chain/status with originChain, originTxHash, and quoteId. The bridge_filled status confirms delivery.

What to know

• Funded Bitcoin address: Selling BTC requires a confirmed UTXO covering the sell amount and miner fee. Bitcoin-origin quotes have no token approval or wrap step.
• Bitcoin recipient: Buying BTC requires a Bitcoin destinationAddress. Omitting it returns HTTP 400. EVM-origin swaps may also require an ERC-20 approval.
• Integrator fees: Bitcoin-origin requests do not support feeBps, feeRecipient, or feeToken. Including these fields returns HTTP 400.
• Settlement: Bitcoin confirmation times vary. Show progress using the status endpoint rather than assuming the swap completes when the origin transaction is sent.

Bitcoin cross-chain bridge use cases

Bitcoin to stablecoins: Bitcoin holders may swap part of their BTC into USDC during volatile periods to preserve capital as a stablecoin balance.

Fund DeFi activity: DeFi apps can allow Bitcoin holders to earn on their Bitcoin by directly swapping BTC into another token and depositing it into a vault or liquidity pool contract.

Return to native BTC: Let traders convert their token balance into native Bitcoin as a store of value, delivered directly to their chosen Bitcoin address.

See the documentaion for the full API reference & examples. Start building for free by signing up through the 0x dashboard.