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 The fee rate is a fixed constant of the adapter rather than a reading from the node's fee estimator, and a transaction already broadcast is not replaced by a higher-fee one. 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.

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, and a deployment can be pointed at a different one: bc1 on mainnet, tb1 on a public test network, bcrt1 on a private network run for integration. Check the address the platform gives you rather than assuming the prefix — a deployment running its own private network mines its own blocks, so funding there is immediate and a public faucet has nothing to do with it.

Capabilities in this area

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

  • Mock transfers — Bitcoin transfers go through the same Operation model as the other families, against a simulator that always returns the same result. The differences of the UTXO model stay inside the adapter.

  • Native adapter and private network node — A native adapter talks to a Bitcoin Core node running a private network. It chooses which UTXOs to spend, builds the transaction as a PSBT, sends it for signature and broadcasts it, including the change output that returns the remainder to the sender.

  • Private Bitcoin network for integration testing — A Partner can send and receive Bitcoin against a private network from the API, the SDK and the Sandbox, with no wait for confirmations and no need for coins with real value. It is the environment for building the integration before going to a public network.

  • Testnet4 — Bitcoin transfers on a public test network, where the fee changes with demand, a confirmation takes minutes and a transaction can sit waiting in the mempool. The adapter handles those conditions.

  • Mainnet — Bitcoin on the network where the funds are real. 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.