Menu
API reference / Bitcoin transfers
Initiate withdrawal
Initiates a bitcoin withdrawal. The transaction is not completed until it is confirmed by the network it is sent onto. A success response from this endpoint means the transaction was successfully initiated, but does not guarantee completion. Supply an idempotency_key to prevent duplicate withdrawals after a timeout. Reusing a key returns HTTP 409 (AlreadyExists), with the existing withdrawal ID in the error message. Requests can still fail validation before duplicate detection. Without a key, check your withdrawals before retrying.
POST https://api.bb.no/v1/withdrawals/bitcoin
Authentication
Signed API key
Send x-bb-api-key. Also send x-bb-api-nonce and x-bb-api-hmac.
API-key permission: bitcoin withdrawals.
Parameters
No path or query parameters.
Request body
A request body is required.
application/json
Show fields
destinationstringThe bitcoin destination to send funds to. Supported formats: - Bitcoin address (bech32, legacy-segwit, legacy) - Lightning invoice (bolt11) - Lightning address - Lightning LNURL
Example: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
amountBtcnumber · doubleThe amount to send. This field is required for all destinations except Lightning invoices. If the destination is a Lightning invoice, the amount is derived from the invoice.
Example: 0.01
accountIdstringThe ID of the account to send from. If empty, the default account is used.
Example: "acc_01HQZX3V9KJ4M2P8R6T0W5Y7BC"
isPaymentbooleanMarks the transaction as a payment. This has consequences for how the transaction is exported for tax purposes. It has no effect on the bitcoin transaction itself.
Example: false
descriptionstringFree-form text description of the withdrawal. Can be used to correlate with your own systems.
Example: "Til hardware-lommebok"
tfrInfoInfoInformation about the recipient under the travel rule. Call GetBitcoinWithdrawalRequirements to check whether it is needed for this destination. full_name and postal address are always required when supplied, including for an organisation.
Show fields
fullNamestringFull name of the person, or registered name of the organisation, on the other side of the transfer. Required for both people and organisations.
countrystringCountry of that person or organisation, as an ISO-3166-1 alpha-2 code.
addressstringPostal address of that person or organisation. For a withdrawal, the bitcoin address or invoice goes in SendBitcoinRequest.destination instead.
ninstringNational identity number of the person, or 9-digit Norwegian organisasjonsnummer of the organisation. Supply it for self-custody withdrawals. It can be omitted for withdrawals to an exchange.
exchangestringName of the exchange holding the account. For withdrawals, choose a name from ListSupportedWithdrawalExchanges. Leave empty for self-custody.
selfCustodybooleanTrue when the destination is a wallet held outside an exchange. Otherwise set this to false and provide exchange.
ownWalletbooleanTrue when the wallet or exchange account belongs to the Bare Bitcoin customer. False when it belongs to another person or organisation.
idempotencyKeystringOptional, case-insensitive identifier of up to 128 characters for this withdrawal attempt. Unique per user across all accounts and API credentials. Omitted or empty disables duplicate protection. Use an opaque value such as a random UUID. Creating another withdrawal with a stored key returns HTTP 409 (AlreadyExists), even if the inputs differ. Validation errors can occur before duplicate detection. Keys do not expire and remain used if the withdrawal fails or is cancelled. A request that fails before storing a withdrawal does not consume its key. Retries still need a fresh API nonce and HMAC. The conflict message includes the existing withdrawal ID.
Maximum length: 128
Example: "0b943d76-3f66-4cb1-a088-95899d503402"
Responses
200 · OK
application/jsonShow fields
withdrawalIdstringThe ID of the initiated withdrawal.
Example: "wi_01JA2B3C4D5E6F7G8H9J0K1M2N"
networkstring · enumValues: NETWORK_BITCOIN, NETWORK_LIGHTNING
Example: "NETWORK_BITCOIN"
statusstring · enumThe status of the withdrawal. The withdrawal might immediately succeed, if sending to another user of the Bare Bitcoin platform.
Values: WITHDRAWAL_STATUS_PENDING, WITHDRAWAL_STATUS_COMPLETED, WITHDRAWAL_STATUS_FAILED
Example: "WITHDRAWAL_STATUS_COMPLETED"