> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob has two APIs. The Business API (payouts, cards, trading, virtual accounts, stablecoin and bitcoin transfers) is at https://api.bitnob.com. The Enterprise API (non-custodial wallets) is at https://api.platform.bitnob.com.
> Business API auth: sign every request with HMAC-SHA256 and send four headers: `X-Auth-Client` (your client ID), `X-Auth-Timestamp` (Unix seconds), `X-Auth-Nonce` (16 random bytes, hex), and `X-Auth-Signature`, the hex HMAC-SHA256 of `CLIENT_ID:TIMESTAMP:NONCE:BODY` keyed with your client secret. BODY is the exact request body string you send, or an empty string. A missing header, a bad signature, or a timestamp more than about 5 minutes off returns `401`.
> Enterprise API auth: send your key in the `X-API-Key` header. Write requests such as creating a transaction also need an `Idempotency-Key` header, or they fail with `idempotency_key_required` before anything happens.
> Sandbox and production share the Business API base URL. The credentials you sign with select the environment, and `GET /api/whoami` returns it in `data.environment`. Use sandbox credentials in sample code and tests, and never put live credentials in code.
> Amounts are strings unless stated otherwise. Never parse them into floats. Balances, transactions, withdrawals (`POST /api/withdrawals`) and virtual accounts use integer strings in the smallest unit: satoshis for BTC, 6 decimals for USDT and USDC, kobo for NGN, and cents for KES and UGX (100 is 1 KES or 1 UGX). A mobile money collection takes `amount` as a JSON integer in cents.
> Payouts and trading use decimal strings in major units: a payout quote `amount` of `"1"` is 1 USDT, and a trading `quantity` of `"0.0001"` is 0.0001 BTC. Payout responses also carry `cent_amount`, the settlement amount in minor units.
> Card amounts are micro-units (1 USD = 1,000,000). Send them as JSON integers. Card responses return them as integer strings, and card webhooks as integers.
> Generate a unique `reference` for each money movement before the first attempt, and reuse it on retries. A reused reference returns `409` on payout quotes (`ALREADY_EXISTS`), withdrawals (`DUPLICATE_KEY_ERROR`) and card creation (`ALREADY_EXISTS`). It returns the existing record on NGN-pair trading orders, NGN virtual accounts and active mobile money collections. On a mobile money collection that has closed or failed it returns `409` `DUPLICATE_REFERENCE`. It isn't checked on crypto-pair trading orders, so look the order up with `GET /api/trading/orders/{reference}` before resending.
> Quotes expire at `expires_at`; read it from the response instead of assuming a window. An expired trading quote returns `422` `PRECONDITION_FAILED`, and an expired payout quote returns `400` `VALIDATION_ERROR`. Create a new quote rather than retrying. A payout quote can be initialized once, and a trading quote is consumed by the order that fills it.
> Webhooks: verify the `x-bitnob-signature` header, the hex HMAC-SHA512 of the raw request body keyed with your webhook secret, before parsing JSON. Compare in constant time and de-duplicate on `event_id`. A successful API response means accepted: confirm the outcome from the webhook, such as `payouts.withdrawal.success`.
> Errors return `status`, `code` and `detail`. Branch on `code`, never on `detail`. Since the November 5, 2026 response format change, each company gets either the current or the new error codes until its cutoff date, so handle both: `PROVIDER_ERROR` or `PROCESSING_ERROR`, and `BVN_PROVIDER_UNAVAILABLE` or `BVN_VERIFICATION_UNAVAILABLE`. A body that fails to parse returns `{"error": {"code": "BAD_REQUEST"}}`.

# Get an account statement

> The statement of your account in one currency over [start, end): the opening balance, every booked transaction (settled, or failed and refunded) dated by when it was booked, the balance after each, and the closing balance. Pending holds are not rows; closing_available subtracts the ones still pending at end. Cursor-paginated, oldest first: pass next_cursor from the previous page as cursor.



## OpenAPI

````yaml /api-collections/swagger/bitnob-api-v2.openapi.json get /api/statements
openapi: 3.1.0
info:
  description: >-
    The Bitnob API for businesses: customers, virtual accounts, cards, payouts,
    crypto addresses and transfers, Lightning, trading and exchange rates.


    ## Authentication

    Every request is signed with your API key's client id and secret.


    **Signed requests (recommended).** Send:

    - `X-Auth-Client`: your client id

    - `X-Auth-Timestamp`: the current Unix time in seconds; requests more than 5
    minutes off are refused

    - `X-Auth-Nonce`: a unique random string of 8 to 128 characters for this
    request

    - `X-Auth-Signature`: hex HMAC-SHA256 of
    `{client_id}:{timestamp}:{nonce}:{body}` using your secret, where body is
    the raw request body (empty for GET)


    **Secret mode.** Send `X-Auth-Client` and `X-Auth-Secret` instead. Simpler,
    but the secret travels with every request.


    Live keys work only for an active organisation; sandbox keys work at any
    time. `ANY /api/whoami` echoes the authenticated client and is the quickest
    way to check your signing.


    ## Responses

    Successful responses are wrapped in an envelope with `success`, `message`,
    `data` and `timestamp`; on lists the paging fields sit inside `data`. Errors
    come either as the envelope with `success: false` and an `error` object, or
    as an RFC 7807 problem with a machine-readable `code`; branch on the code.


    Every response carries an `X-Correlation-ID` header; errors repeat it as
    `request_id`. Quote it to support.



    Every request passes a per-IP rate limit of 500 requests a minute (429 with
    `Retry-After`).



    This document is maintained by hand and checked against the route table on
    every build: every /api route is listed here.
  title: Bitnob API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.bitnob.com
security:
  - BitnobClientId: []
    BitnobClientSecret: []
tags:
  - description: Check that your requests are signed correctly.
    name: Authentication
  - description: >-
      The people and businesses you serve. Creating and editing them needs the
      customers feature.
    name: Customers
  - description: >-
      Naira accounts that receive bank transfers, for your company or for a
      customer, and temporary KES and UGX accounts that collect one mobile money
      payment.
    name: Virtual accounts
  - description: Crypto deposit addresses, for your company or for a customer.
    name: Addresses
  - description: >-
      Virtual cards: issue, fund, withdraw, freeze, terminate, and the card KYC
      and corporate onboarding behind them.


      ## Card programs


      Every card belongs to one card program, named by `card_program` on card
      KYC, card creation and the card object. A

      program must be enabled for your company before you can use it; otherwise
      the request returns 400.


      | Program | What it is | Funding | Card KYC |

      |---|---|---|---|

      | `prepaid` | Virtual prepaid card. | From your company balance at
      creation, 2 to 2,500 USD. | `POST /api/cards/kyc` with `card_program:
      prepaid`. |

      | `collateral` | A cardholder's own card, backed by a deposit. | No
      initial funding; spending power comes from the deposit. | `POST
      /api/cards/kyc` with `card_program: collateral`; the cardholder finishes
      on the hosted page (`completion_link`). |

      | `collateral_business` | Business cards that draw on one shared company
      pool. | The company pool. | `POST /api/cards/kyc/corporate`. |

      | `prepaid_platinum` | Virtual prepaid USD Visa card. | From your company
      balance at creation, $5 to $2,500; $1 always stays on the card. | `POST
      /api/cards/kyc` with an identity document and `id_front_image`. |

      | `prepaid_premium` | Virtual prepaid USD Visa card, premium range. | As
      `prepaid_platinum`. | As `prepaid_platinum`. |


      For `prepaid_platinum` and `prepaid_premium`:


      - **Register your card encryption key first.** Send your RSA public key
      (2048 bits or more) to
        `POST /api/cards/encryption-key`. These programs only ever return card details encrypted to that key, so until it is
        registered, `GET /api/cards/{cardId}/secure` returns 422 for their cards. Card creation itself does not check for the
        key, so register it before you issue cards. To open the encrypted details, see
        [Decrypt card details](/docs/card-issuing/decrypt-card-details).
      - One card KYC covers both: a customer approved for either can be issued
      cards in both.

      - Create the card with a `customer_id` that has passed card KYC; an inline
      customer is refused.

      - `prepaid_premium` must always be named. When `card_program` is omitted
      you get the platform's default prepaid program.

      - Card details from `GET /api/cards/{cardId}/secure` are always encrypted
      to your registered key, and are shown through
        `secure_view_url`, a link usable for about one minute.
    name: Cards
  - description: 'Pay out to bank accounts and mobile money: quote, initialize, finalize.'
    name: Payouts
  - description: Saved payout recipients.
    name: Beneficiaries
  - description: Banks and account lookups for payouts.
    name: Banks
  - description: Balance transfers between Bitnob organisations.
    name: Transfers
  - description: Crypto withdrawals.
    name: Withdrawals
  - description: Lightning invoices and payments.
    name: Lightning
  - description: Lightning addresses, LNURL withdraw links and LNURL payments.
    name: LNURL
  - description: Blockchain node access.
    name: Nodes
  - description: Quotes and orders for buying and selling.
    name: Trading
  - description: Rates and conversions.
    name: Exchange rates
  - description: Your transaction history.
    name: Transactions
  - description: Wallet balances.
    name: Balances
paths:
  /api/statements:
    get:
      tags:
        - Transactions
      summary: Get an account statement
      description: >-
        The statement of your account in one currency over [start, end): the
        opening balance, every booked transaction (settled, or failed and
        refunded) dated by when it was booked, the balance after each, and the
        closing balance. Pending holds are not rows; closing_available subtracts
        the ones still pending at end. Cursor-paginated, oldest first: pass
        next_cursor from the previous page as cursor.
      operationId: statementsGet
      parameters:
        - description: The wallet currency.
          example: USDT
          in: query
          name: currency
          required: true
          schema:
            type: string
        - description: Inclusive, RFC 3339.
          example: '2026-10-01T00:00:00Z'
          in: query
          name: start
          required: true
          schema:
            type: string
        - description: Exclusive, RFC 3339.
          example: '2026-11-01T00:00:00Z'
          in: query
          name: end
          required: true
          schema:
            type: string
        - description: next_cursor from the previous page.
          example: eyJiIjoiMjAyNi0xMC0wOVQxNTo1MjozMSswMDowMCIsImlkIjoiMDE5YTNkMDIifQ
          in: query
          name: cursor
          required: false
          schema:
            type: string
        - description: >-
            Rows per page. 0 or absent uses the maximum page size, and larger
            values are capped to it.
          example: 500
          in: query
          name: limit
          required: false
          schema:
            minimum: 0
            type: integer
      responses:
        '200':
          content:
            application/json:
              examples:
                october:
                  summary: A USDT statement for October, one page
                  value:
                    data:
                      account_number: '3000000002'
                      closing_available: '1198000000'
                      closing_available_formatted: '1198'
                      closing_balance: '1298000000'
                      closing_balance_formatted: '1298'
                      currency: USDT
                      end: '2026-11-01T00:00:00+00:00'
                      opening_balance: '1000000000'
                      opening_balance_formatted: '1000'
                      rows:
                        - balance_after: '1500000000'
                          balance_after_formatted: '1500'
                          booked_at: '2026-10-03T09:14:02+00:00'
                          net_change: '500000000'
                          net_change_formatted: '500'
                          transaction:
                            account_number: '3000000002'
                            amount: '500000000'
                            amount_formatted: '500'
                            created_at: '2026-10-03T09:14:02Z'
                            currency: USDT
                            fee: '0'
                            fee_formatted: '0'
                            reference: dep_sbx_8c21f0a4
                            side: Credit
                            state: SETTLED
                            transaction_id: 019a3d02-6b7c-7d8e-9f01-2a3b4c5d6e71
                            type: DEPOSIT_CONFIRMED
                            updated_at: '2026-10-03T09:14:02Z'
                            value_date: '2026-10-03'
                        - balance_after: '1298000000'
                          balance_after_formatted: '1298'
                          booked_at: '2026-10-09T15:52:31+00:00'
                          net_change: '-202000000'
                          net_change_formatted: '-202'
                          transaction:
                            account_number: '3000000002'
                            amount: '-200000000'
                            amount_formatted: '-200'
                            created_at: '2026-10-09T15:50:12Z'
                            currency: USDT
                            fee: '2000000'
                            fee_formatted: '2'
                            reference: payout_ref_20261009_0001
                            side: Debit
                            state: SETTLED
                            transaction_id: 019a3d05-1c2d-7e3f-8a40-5b6c7d8e9f02
                            type: WITHDRAWAL
                            updated_at: '2026-10-09T15:52:31Z'
                            value_date: '2026-10-09'
                      start: '2026-10-01T00:00:00+00:00'
                    message: Account statement retrieved successfully
                    success: true
                    timestamp: '2026-11-11T09:15:02.481Z'
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/AccountStatement'
                    type: object
          description: OK
        '400':
          content:
            application/json:
              examples:
                bad_window:
                  summary: start is not before end
                  value:
                    code: VALIDATION_ERROR
                    correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    detail: start must be before end
                    request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    status: 400
                    timestamp: '2026-11-11T09:15:02Z'
                    title: Validation Error
                    type: https://api.bitnob.com/errors/VALIDATION_ERROR
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            currency, start or end is missing or malformed, start is not before
            end, the cursor is invalid, or you have no wallet in the currency
            (VALIDATION_ERROR).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          content:
            application/json:
              examples:
                internal_error_unhandled:
                  $ref: '#/components/examples/InternalErrorUnhandled'
              schema:
                $ref: '#/components/schemas/Problem'
          description: Something failed on our side; safe to retry (INTERNAL_ERROR).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    Envelope:
      description: >-
        Successful responses are wrapped in this envelope, and so are errors a
        handler answers itself (request body and field validation, some
        not-found and conflict cases, ORG_NOT_ACTIVE): success is false and
        error carries a code and message. Errors raised by authentication and by
        the services behind a handler are a Problem instead.
      properties:
        data:
          description: >-
            The payload; its shape is given per operation. Omitted when there is
            none.
        error:
          $ref: '#/components/schemas/ErrorInfo'
        message:
          description: Human-readable summary; omitted when empty.
          type: string
        request_id:
          description: >-
            Set on error envelopes: the request's correlation id (req_ followed
            by a UUID), the same value as the X-Correlation-ID response header.
            Quote it to support.
          type: string
        success:
          description: true on success
          type: boolean
        timestamp:
          description: When the response was written.
          format: date-time
          type: string
      required:
        - success
        - timestamp
      type: object
    AccountStatement:
      description: >-
        One page of an account statement. Opening and closing figures repeat on
        every page.
      properties:
        account_number:
          type: string
        closing_available:
          description: closing_balance minus holds still pending at end.
          type: string
        closing_available_formatted:
          type: string
        closing_balance:
          description: Booked balance at end.
          type: string
        closing_balance_formatted:
          type: string
        currency:
          type: string
        end:
          description: Exclusive.
          type: string
        next_cursor:
          description: Absent on the last page.
          type: string
        opening_balance:
          description: Booked balance at start.
          type: string
        opening_balance_formatted:
          type: string
        rows:
          description: Oldest first.
          items:
            $ref: '#/components/schemas/AccountStatementRow'
          type: array
        start:
          description: Inclusive.
          type: string
      type: object
    Problem:
      description: >-
        RFC 7807 problem. Returned when authentication fails and for errors
        raised by the services behind a handler (validation, domain refusals
        such as FEATURE_NOT_ENABLED or PRECONDITION_FAILED, partner outages);
        branch on code.
      properties:
        code:
          description: >-
            Machine-readable; branch on this, not on the status or the wording.
            For example VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN,
            FEATURE_NOT_ENABLED, PERSONAL_WORKSPACE_CUSTOMERS,
            TIER_PRODUCT_LOCKED, NOT_FOUND, DUPLICATE_KEY_ERROR, ALREADY_EXISTS,
            PRECONDITION_FAILED, INSUFFICIENT_FUNDS, TIER_LIMIT_REACHED,
            RATE_LIMIT_EXCEEDED, TIMEOUT, SERVICE_UNAVAILABLE,
            LIMITS_UNAVAILABLE, PLATFORM_PAUSED, INTERNAL_ERROR.
          type: string
        correlation_id:
          description: >-
            The request's correlation id, the same value as the X-Correlation-ID
            response header.
          type: string
        detail:
          description: >-
            What went wrong for this request, safe to show; internal and partner
            failures carry a generic sentence.
          type: string
        extensions:
          additionalProperties: true
          description: >-
            Code-specific facts, for example feature_key (FEATURE_NOT_ENABLED),
            field or field_violations (VALIDATION_ERROR), rail, window, limit,
            used, requested and remaining (TIER_LIMIT_REACHED), scope
            (PLATFORM_PAUSED).
          type: object
        instance:
          type: string
        request_id:
          description: Equal to correlation_id.
          type: string
        status:
          description: The HTTP status, repeated.
          type: integer
        timestamp:
          format: date-time
          type: string
        title:
          description: >-
            Short summary of the code, for example Validation Error or Feature
            Not Enabled.
          type: string
        type:
          description: https://api.bitnob.com/errors/{code}
          format: uri
          type: string
      required:
        - type
        - title
        - status
        - code
        - timestamp
      type: object
    ErrorInfo:
      properties:
        code:
          description: >-
            Machine-readable, for example BAD_REQUEST, NOT_FOUND, CONFLICT,
            ORG_NOT_ACTIVE, RATE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE,
            INTERNAL_ERROR.
          type: string
        details:
          additionalProperties: true
          description: >-
            For field validation, a map of field name to message ("email":
            "Email must be a valid email address"); for a body that does not
            decode, the offending field.
          type: object
        message:
          type: string
      required:
        - message
      type: object
    AccountStatementRow:
      description: >-
        One booked transaction with the balance after it. Amounts are integer
        strings in base units.
      properties:
        balance_after:
          description: >-
            Booked balance after this row. It continues across pages; the last
            row of the last page equals closing_balance.
          type: string
        balance_after_formatted:
          type: string
        booked_at:
          description: >-
            RFC 3339 time the transaction was booked (settled or failed); rows
            are dated and ordered by it.
          type: string
        net_change:
          description: amount minus fee, signed.
          type: string
        net_change_formatted:
          type: string
        transaction:
          $ref: '#/components/schemas/TransactionsTransaction'
      type: object
    ErrorEnvelope:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - properties:
            success:
              const: false
          required:
            - error
          type: object
      description: >-
        The envelope as an error: success is false, error is set, data is
        absent.
    TransactionsTransaction:
      description: >-
        Empty fields are omitted. A transaction found by reference carries only
        transaction_id, account_number, currency, type, state, amount and
        reference.
      properties:
        account_number:
          type: string
        amount:
          description: Net amount in the currency's base units
          type: string
        amount_formatted:
          description: Human-readable amount
          type: string
        created_at:
          format: date-time
          type: string
        currency:
          type: string
        fee:
          description: Fee in the currency's base units
          type: string
        fee_formatted:
          type: string
        metadata:
          additionalProperties:
            type: string
          type: object
        reference:
          type: string
        side:
          enum:
            - Credit
            - Debit
          type: string
        state:
          description: For example PENDING, SETTLED
          type: string
        trade_id:
          description: Only on list items
          type: string
        transaction_id:
          type: string
        type:
          description: For example DEPOSIT_CONFIRMED, P2P_TRANSFER
          type: string
        updated_at:
          format: date-time
          type: string
        value_date:
          format: date
          type: string
      type: object
  headers:
    X-Correlation-ID:
      description: >-
        Generated for every request (any value the client sends is ignored);
        quote it to support. Errors repeat it as request_id and correlation_id.
      example: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      example: 1
      schema:
        minimum: 0
        type: integer
  responses:
    Unauthorized:
      content:
        application/json:
          examples:
            unauthorized_auth_failed:
              $ref: '#/components/examples/UnauthorizedAuthFailed'
            unauthorized_invalid_secret:
              $ref: '#/components/examples/UnauthorizedInvalidSecret'
            unauthorized_invalid_signature:
              $ref: '#/components/examples/UnauthorizedInvalidSignature'
            unauthorized_locked_out:
              $ref: '#/components/examples/UnauthorizedLockedOut'
          schema:
            $ref: '#/components/schemas/Problem'
      description: >-
        Authentication failed: a signing header is missing or malformed, the
        timestamp is more than 5 minutes off, the signature or secret is wrong,
        or the client is locked out after failed checks (UNAUTHORIZED).
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
    RequestTimeout:
      content:
        application/json:
          examples:
            request_timeout:
              $ref: '#/components/examples/RequestTimeout'
          schema:
            $ref: '#/components/schemas/Problem'
      description: >-
        The request ran past its deadline (TIMEOUT); retry, with the same
        reference for writes.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
    TooManyRequests:
      content:
        application/json:
          examples:
            rate_limited:
              $ref: '#/components/examples/RateLimited'
            rate_limited_envelope:
              $ref: '#/components/examples/RateLimitedEnvelope'
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/Problem'
      description: >-
        Rate limited. The per-IP limiter (500 requests a minute) answers with a
        Problem and Retry-After; operation-specific throttles answer with the
        envelope.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
    ServiceUnavailable:
      content:
        application/json:
          examples:
            auth_service_busy:
              $ref: '#/components/examples/AuthServiceBusy'
            auth_service_unavailable:
              $ref: '#/components/examples/AuthServiceUnavailable'
            limits_unavailable:
              $ref: '#/components/examples/LimitsUnavailable'
            partner_unavailable:
              $ref: '#/components/examples/PartnerUnavailable'
            platform_paused:
              $ref: '#/components/examples/PlatformPaused'
            service_unavailable_envelope:
              $ref: '#/components/examples/ServiceUnavailableEnvelope'
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/Problem'
      description: >-
        Temporarily unavailable; retry later. The identity service could not
        check the credentials (sent with Retry-After), a partner is down
        (SERVICE_UNAVAILABLE), the limits check could not run
        (LIMITS_UNAVAILABLE), or a platform control paused money movement
        (PLATFORM_PAUSED).
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
  examples:
    InternalErrorUnhandled:
      summary: An unexpected failure
      value:
        code: INTERNAL_ERROR
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: An internal server error occurred
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 500
        timestamp: '2026-10-30T09:15:02Z'
        title: Internal Server Error
        type: https://api.bitnob.com/errors/INTERNAL_ERROR
    UnauthorizedAuthFailed:
      description: >-
        Returned when X-Auth-Client, X-Auth-Timestamp, X-Auth-Nonce or
        X-Auth-Signature is missing, the nonce is not 8 to 128 characters, the
        signature is not hex, or the timestamp is more than 5 minutes from the
        server's clock. The detail does not say which; check each.
      summary: A signing header is missing or malformed, or the timestamp is stale
      value:
        code: UNAUTHORIZED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Authentication failed
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 401
        timestamp: '2026-10-30T09:15:02Z'
        title: Unauthorized
        type: https://api.bitnob.com/errors/UNAUTHORIZED
    UnauthorizedInvalidSecret:
      summary: 'Secret mode: the client id or secret is wrong'
      value:
        code: UNAUTHORIZED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Invalid credentials
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 401
        timestamp: '2026-10-30T09:15:02Z'
        title: Unauthorized
        type: https://api.bitnob.com/errors/UNAUTHORIZED
    UnauthorizedInvalidSignature:
      description: >-
        The detail is the identity service's reason when it gives one (an
        unknown client or a reused nonce reads differently); Invalid signature
        otherwise.
      summary: The signature does not match
      value:
        code: UNAUTHORIZED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Invalid signature
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 401
        timestamp: '2026-10-30T09:15:02Z'
        title: Unauthorized
        type: https://api.bitnob.com/errors/UNAUTHORIZED
    UnauthorizedLockedOut:
      summary: Too many failed credential checks
      value:
        code: UNAUTHORIZED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Too many failed credential checks; retry later
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 401
        timestamp: '2026-10-30T09:15:02Z'
        title: Unauthorized
        type: https://api.bitnob.com/errors/UNAUTHORIZED
    RequestTimeout:
      summary: The request ran past its deadline
      value:
        code: TIMEOUT
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: The request took too long to complete. Please try again.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 408
        timestamp: '2026-10-30T09:15:02Z'
        title: Request Timeout
        type: https://api.bitnob.com/errors/TIMEOUT
    RateLimited:
      summary: The per-IP limit (500 requests a minute) is reached
      value:
        code: RATE_LIMIT_EXCEEDED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Too many requests. Please try again later.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 429
        timestamp: '2026-10-30T09:15:02Z'
        title: Rate Limit Exceeded
        type: https://api.bitnob.com/errors/RATE_LIMIT_EXCEEDED
    RateLimitedEnvelope:
      summary: An operation-specific throttle (answered by the handler)
      value:
        error:
          code: RATE_LIMIT_EXCEEDED
          message: >-
            a verification link was sent to this customer in the last minute;
            try again shortly
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    AuthServiceBusy:
      description: 'Sent with Retry-After: 1.'
      summary: Too many large signed bodies are being checked at once
      value:
        code: SERVICE_UNAVAILABLE
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Authentication service is busy, retry shortly
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Service Unavailable
        type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE
    AuthServiceUnavailable:
      description: 'Sent with Retry-After: 1. The detail is worded exactly like this today.'
      summary: The identity service could not be reached to check the credentials
      value:
        code: SERVICE_UNAVAILABLE
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Service Authentication service unavailable is currently unavailable
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Service Unavailable
        type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE
    LimitsUnavailable:
      summary: The tier limit check could not run
      value:
        code: LIMITS_UNAVAILABLE
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: >-
          We could not verify your account limits right now. Please try again
          shortly.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Limits Unavailable
        type: https://api.bitnob.com/errors/LIMITS_UNAVAILABLE
    PartnerUnavailable:
      summary: A partner or internal service is unavailable
      value:
        code: SERVICE_UNAVAILABLE
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Service is temporarily unavailable. Please try again later.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Service Unavailable
        type: https://api.bitnob.com/errors/SERVICE_UNAVAILABLE
    PlatformPaused:
      summary: Money movement is paused by a platform control
      value:
        code: PLATFORM_PAUSED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: >-
          Money movement is temporarily paused. Nothing is lost — requests can
          be retried once the pause lifts.
        extensions:
          scope: asset:BTC
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 503
        timestamp: '2026-10-30T09:15:02Z'
        title: Money Movement Paused
        type: https://api.bitnob.com/errors/PLATFORM_PAUSED
    ServiceUnavailableEnvelope:
      summary: Unavailable (answered by the handler)
      value:
        error:
          code: SERVICE_UNAVAILABLE
          message: LNURL payments are temporarily disabled
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
  securitySchemes:
    BitnobClientId:
      type: apiKey
      in: header
      name: X-Auth-Client
      description: |
        Your workspace client id.
    BitnobClientSecret:
      type: apiKey
      in: header
      name: X-Auth-Secret
      description: >
        Your sandbox client secret. The playground accepts sandbox keys only,
        sends the secret straight from your browser to the API, and needs your
        IP on the key's whitelist. In your own integration, sign requests with
        HMAC instead of sending the secret.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.