API reference / Tax

Tax transactions

Lists tax-relevant transactions done by the user within the Bare Bitcoin platform. Note that this does NOT include any of the third party transactions imported into the platform tax calculator.

View Markdown

GET https://api.bb.no/v1/tax/transactions

Authentication

API key

Send x-bb-api-key. No nonce or signature is required.

OAuth

Send an access token in Authorization: Bearer.

Required scopes:

api:tax:transactions:read

Authentication guide →

Parameters

pageSizequery · integer

Items per page (max 200). When set to 0, all matching transactions are returned.

afterquery · string

Transactions are listed oldest first (required to compute running_balance_btc correctly), so pagination walks forward in time. Only return transactions created after this time. Can be used standalone to filter down to a start date; pass next_after from the previous response (together with next_after_id) to fetch the next page.

afterIdquery · string

Pagination cursor tiebreaker: when multiple transactions share the same create_time, this ID breaks the tie. Pass next_after_id from the previous response. Requires 'after'; supplying 'after_id' alone is rejected.

beforequery · string

Only return transactions created strictly before this time. Filter only, does not affect pagination direction.

Responses

200 · OK

application/json

ListTaxTransactionsResponse

Show fields

transactionsarray of TaxTransaction

Items:

TaxTransaction

Show fields

idstring

ID of the underlying transaction; its format depends on the type. Trades use the trade ID (tr_), bitcoin deposits de_, bonuses gb_, fiat withdrawals fpu_ and adjustments abj_ or apj_. Bitcoin withdrawals and card deposits use a UUID, which is not the withdrawal_id returned by the transfer endpoints. Bank deposits use the bank's reference.

Example: "tr_01HVXHG9PMDKR3YQV4Z8W5T2BN"

accountIdstring

The bitcoin account the transaction belongs to. Empty for fiat deposits and fiat withdrawals, which are not tied to an account.

Example: "acc_01HQZX3V9KJ4M2P8R6T0W5Y7BC"

typestring · enum

Values: TAX_TRANSACTION_TYPE_BTC_BUY, TAX_TRANSACTION_TYPE_BTC_SELL, TAX_TRANSACTION_TYPE_BTC_WITHDRAWAL, TAX_TRANSACTION_TYPE_BTC_DEPOSIT, TAX_TRANSACTION_TYPE_BTC_BONUS, TAX_TRANSACTION_TYPE_FIAT_DEPOSIT, TAX_TRANSACTION_TYPE_FIAT_WITHDRAWAL, TAX_TRANSACTION_TYPE_BTC_ADJUSTMENT, TAX_TRANSACTION_TYPE_FIAT_ADJUSTMENT

subTypestring

Sub-type of the transaction. Which values apply depends on the type: trades carry the order type, bitcoin transfers the network, fiat deposits the payment method and adjustments the reason. Empty when the transaction has no sub-type.

Values: , market, limit, manual, onchain, lightning, internal, internal-external, lightning-payment-request, lightning-address, lightning-lnurl, bank, card, write_off, correction, unspecified

Example: "market"

createTimestring · date-time

Example: "2024-02-01T10:22:36Z"

finalizeTimestring · date-time

Unset while the transaction is still pending, e.g. a bitcoin deposit that is not yet confirmed.

Example: "2024-02-01T10:41:05Z"

inAmountstring

Stringified decimal number

Example: "0.1"

inCurrencystring

Example: "BTC"

outAmountstring

Stringified decimal number. Includes trade fees; withdrawal fees are additional.

Example: "65000"

outCurrencystring

Example: "NOK"

feeAmountstring

Stringified decimal number. When the fee is zero, fee_currency may be empty.

Example: "455"

feeCurrencystring

Example: "NOK"

rateMarketstring

Stringified decimal number: the market rate in NOK per BTC at the time of the transaction.

Example: "645450"

isPaymentboolean

Whether the transaction was a payment to a third party, as declared by the user. Only ever set for bitcoin withdrawals.

Example: false

paymentInfostring

For bitcoin transfers: `<network ID>:<destination address>`. For bank fiat transfers: the counterparty bank account number. Empty for card deposits, trades and bonuses.

Example: "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16:bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"

notestring

Free-form user-supplied description.

Example: "Første kjøp"

usdnokstring

Stringified decimal number: the USD/NOK exchange rate at the time of the transaction, when known.

Example: "10.45"

runningBalanceBtcstring

Stringified decimal number: the user's total BTC balance across all accounts after this transaction.

Example: "1.8997585"

hasMoreboolean

True if there are more transactions available after the last one returned.

nextAfterstring · date-time

Cursor for the next page: pass this as 'after' in the next request.

Example: "2024-02-01T10:22:36Z"

nextAfterIdstring

Tiebreaker for the cursor: pass this as 'after_id' in the next request.

Example: "tr_01HVXHG9PMDKR3YQV4Z8W5T2BN"

Request example

GET/v1/tax/transactionsAPI key

curl -X GET \
  https://api.bb.no/v1/tax/transactions \
  -H "x-bb-api-key: $BB_API_KEY"

GET/v1/tax/transactionsOAuth

curl -X GET \
  https://api.bb.no/v1/tax/transactions \
  -H "Authorization: Bearer $BB_TOKEN"

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

Response example

Response200

{
  "transactions": [
    {
      "id": "tr_01HVXHG9PMDKR3YQV4Z8W5T2BN",
      "accountId": "acc_01HQZX3V9KJ4M2P8R6T0W5Y7BC",
      "type": "TAX_TRANSACTION_TYPE_BTC_BUY",
      "subType": "market",
      "createTime": "2024-02-01T10:22:36Z",
      "finalizeTime": "2024-02-01T10:41:05Z",
      "inAmount": "0.1",
      "inCurrency": "BTC",
      "outAmount": "65000",
      "outCurrency": "NOK",
      "feeAmount": "455",
      "feeCurrency": "NOK",
      "rateMarket": "645450",
      "isPayment": false,
      "paymentInfo": "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16:bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
      "note": "Første kjøp",
      "usdnok": "10.45",
      "runningBalanceBtc": "1.8997585"
    }
  ],
  "hasMore": true,
  "nextAfter": "2024-02-01T10:22:36Z",
  "nextAfterId": "tr_01HVXHG9PMDKR3YQV4Z8W5T2BN"
}