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. Requests are not idempotent: after a timeout, check your withdrawals before retrying.

View Markdown

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.

Authentication guide →

Parameters

No path or query parameters.

Request body

A request body is required.

application/json

SendBitcoinRequest

Show fields

destinationstring

The bitcoin destination to send funds to. Supported formats: - Bitcoin address (bech32, legacy-segwit, legacy) - Lightning invoice (bolt11) - Lightning address - Lightning LNURL

Example: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"

amountBtcnumber · double

The 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

accountIdstring

The ID of the account to send from. If empty, the default account is used.

Example: "acc_01HQZX3V9KJ4M2P8R6T0W5Y7BC"

isPaymentboolean

Marks 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

descriptionstring

Free-form text description of the withdrawal. Can be used to correlate with your own systems.

Example: "Til hardware-lommebok"

tfrInfoInfo

The recipient of this transaction, per EU's travel rule. Required for all withdrawals to new destinations. full_name and address are always required, also when the recipient is an organisation.

Info

Show fields

fullNamestring

Recipient name. For an organisation this is its registered name. Required for a private individual; optional for an organisation, which is identified by the organisasjonsnummer in nin.

countrystring

ISO-3166-1 alpha-2 country code

addressstring

ninstring

The recipient's fødselsnummer, or a 9-digit organisasjonsnummer when the recipient is an organisation. Only required if the TFR config said so.

exchangestring

selfCustodyboolean

Responses

200 · OK

application/json

SendBitcoinResponse

Show fields

withdrawalIdstring

The ID of the initiated withdrawal.

Example: "wi_01JA2B3C4D5E6F7G8H9J0K1M2N"

networkstring · enum

Values: NETWORK_BITCOIN, NETWORK_LIGHTNING

Example: "NETWORK_BITCOIN"

statusstring · enum

The 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"

Request example

This request changes account data. Examples are not executed by this page.

POST/v1/withdrawals/bitcoinSigned API key

curl -X POST \
  https://api.bb.no/v1/withdrawals/bitcoin \
  -H "Content-Type: application/json" \
  -H "x-bb-api-key: $BB_API_KEY" \
  -H "x-bb-api-nonce: $BB_NONCE" \
  -H "x-bb-api-hmac: $BB_HMAC" \
  -d '{
    "amountBtc": 0.0001,
    "destination": "REPLACE_WITH_BITCOIN_ADDRESS_OR_INVOICE",
    "tfrInfo": {
      "fullName": "REPLACE_WITH_RECIPIENT_NAME",
      "country": "NO",
      "address": "REPLACE_WITH_RECIPIENT_ADDRESS",
      "selfCustody": true
    }
  }'

Complete signing helper and test fixture →

Replace example identifiers and set credentials in environment variables before running.

Response example

Response200

{
  "withdrawalId": "wi_01JA2B3C4D5E6F7G8H9J0K1M2N",
  "network": "NETWORK_BITCOIN",
  "status": "WITHDRAWAL_STATUS_COMPLETED"
}