Developer guide

Bitcoin

5 min read

Supported networks

Bitcoin is supported as a native, direct UTXO adapter, independent of the EVM execution stack. See the Roadmap for which Bitcoin networks are currently available.

How it differs from EVM

Bitcoin does not use Solidity contracts, EIP-7702, ERC-4337 or LI.FI. There is no account with a balance: a wallet owns unspent outputs, and a transfer is built by choosing which of them to spend. Four consequences reach the surfaces:

  • The address is native segwit (P2WPKH) and is derived from the public key alone, so it can be shown and funded before any transaction exists — the same order as EVM, for a different reason.
  • Only confirmed outputs are spendable. Coins that arrived but are still in the mempool are not part of what a transfer can select.
  • The network fee comes out of the sender's own inputs. No third party can pay it without taking part in the transaction, so on Bitcoin the operation reports paidBy: "user" and nothing is posted as sponsorship. See Costs and platform accounts.
  • Change returns to the sender, as an output of the same transaction. Change too small to be worth spending later is left to the fee rather than written as an output nobody will ever use.

The asset is native BTC. Tokens on Bitcoin are not part of this capability.

How a transfer is built

  1. Read the confirmed outputs of the sender's address.
  2. Select outputs until they cover the amount plus the fee. A send that the confirmed outputs cannot cover is refused by name, before anything is signed.
  3. Compute the fee from the size of the transaction being built — inputs, outputs and witnesses — so the figure reported afterwards is exact rather than estimated: it is the difference between what went in and what came out, and it is what the miner collects.
  4. Sign each input at the Partner Signer Gateway. One round trip per input, over the sighash. The API assembles and broadcasts the transaction; it never holds the key that authorizes the spend.
  5. Broadcast, and reconcile against what the chain shows rather than against what the submission returned.

Declared limitation A transaction already broadcast is not replaced by a higher-fee one. The fee rate itself is read from the node's own estimator, or from the indexer where there is no node, and clamped between a declared floor and ceiling. Replace-by-fee, locking the outputs already committed to an operation, a dust policy and reorganization handling are on the Roadmap for the network where the funds are real.

Confirmation and reconciliation

The observed result comes from UTXOs, confirmation state and paid network fee. It is reconciled independently of a worker's prior belief. Bitcoin transfers settle natively; cross-chain routing is not part of this adapter.

Because the chain holds facts the platform did not produce, the comparison that matters runs in one direction: the balance the platform reports is what it observed and accounted, and an address can hold coins that arrived without any operation of ours ever seeing them.

Accounts issued under a retired derivation

A deployment can retire the key derivation it used to issue Bitcoin addresses. An account issued under a retired derivation keeps its address and its history, and deposits to it are still observed and credited. It moves no funds: quotes, transfers, account provisioning and recipient creation on that network answer 409 ACCOUNT_DERIVATION_DEPRECATED, while resolving a recipient still answers its address. The deployment's operator reprovisions the account, which gives the wallet a new address on that network; until then the refusal stands, and retrying does not change it.

Availability

Bitcoin is enabled per Partner deployment through the capability manifest. Confirm enabled assets and operation types for your deployment before integrating against it.

Test funds

Test BTC is asked for, never minted. Unlike this platform's own test asset representations on EVM, which a faucet of the deployment issues on request, coins on a public Bitcoin test network come from a public faucet and no part of this platform can create them: https://coinfaucet.eu/en/btc-testnet4/ is the one used for Testnet4. Send them to the address the platform reports for your wallet, and expect the first confirmation to take a few minutes.

The address prefix tells you which network you are on: bc1 on mainnet and tb1 on a public test network. Check the address the platform gives you rather than assuming the prefix.

Capabilities in this area

This area covers the capabilities below. The Roadmap states the current availability of each one.

  • Transfers — Bitcoin transfers. The platform chooses which UTXOs to spend, has the transaction signed at the gateway, broadcasts it and returns the change to the sender, and a transfer ends in a transaction id that a public explorer shows. Following it to the end, with its confirmation observed and the transfer reconciled, is what is still being completed.

  • Bitcoin Testnet4 via API, SDK and Sandbox — Bitcoin Testnet4 is reachable from the API, the SDK and the Sandbox, with no funds at risk. This row states that the network is integrated; the row of each operation states whether it is complete.

  • Mainnet for production deployments — Bitcoin on the network where the funds are real, for a Partner's production deployment: its manifest enables the network and the assets, after the security review and with limits, reconciliation, pause and rollback in place. It requires replace-by-fee to raise the fee of a stuck transaction, locking the UTXOs already committed to an operation, a dust policy and handling of chain reorganizations. Switching it on for a given Partner is a step of that Partner's onboarding.