> ## 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"}}`.

# Look up a bank or mobile money account

> Verifies a bank or mobile money account and returns the holder's name, so you can confirm it before initializing a payout. For mobile money, set type=mobile_money and pass the network as bank_code.



## OpenAPI

````yaml /api-collections/swagger/bitnob-api-v2.openapi.json get /api/payouts/account-lookup
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/payouts/account-lookup:
    get:
      tags:
        - Payouts
      summary: Look up a bank or mobile money account
      description: >-
        Verifies a bank or mobile money account and returns the holder's name,
        so you can confirm it before initializing a payout. For mobile money,
        set type=mobile_money and pass the network as bank_code.
      operationId: payoutsAccountLookup
      parameters:
        - description: ISO 3166-1 alpha-2 country, case-insensitive
          example: NG
          in: query
          name: country
          required: true
          schema:
            maxLength: 10
            pattern: ^[A-Za-z]+$
            type: string
        - description: Account or phone number, alphanumeric
          example: '0000000001'
          in: query
          name: account_number
          required: true
          schema:
            maxLength: 50
            pattern: ^[A-Za-z0-9]+$
            type: string
        - description: Bank code, or the network for mobile money
          examples:
            bank:
              summary: Bank code (Access Bank)
              value: '000014'
            mobile_money:
              summary: Mobile money network
              value: mtn
          in: query
          name: bank_code
          schema:
            type: string
        - description: bank (default) or mobile_money
          examples:
            bank:
              summary: Bank account (the default)
              value: bank
            mobile_money:
              summary: Mobile money number
              value: mobile_money
          in: query
          name: type
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                bank_account:
                  summary: A Nigerian bank account
                  value:
                    data:
                      account_name: ADAEZE OKAFOR
                      account_number: '0000000001'
                      bank_code: '000014'
                      bank_name: ACCESS BANK
                      country: NG
                      is_verified: true
                    message: Beneficiary lookup completed
                    success: true
                    timestamp: '2026-10-30T09:15:02.481Z'
                mobile_money:
                  summary: >-
                    A Ghana mobile money number (bank_code carries the network
                    and can be empty; bank_name usually is)
                  value:
                    data:
                      account_name: KWAME MENSAH
                      account_number: '0240000001'
                      bank_code: MTN
                      bank_name: ''
                      country: GH
                      is_verified: true
                    message: Beneficiary lookup completed
                    success: true
                    timestamp: '2026-10-30T09:15:02.481Z'
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/PayoutsAccountLookup'
                    type: object
          description: OK
        '400':
          content:
            application/json:
              examples:
                field_validation:
                  summary: account_number has characters other than letters and digits
                  value:
                    error:
                      code: BAD_REQUEST
                      details:
                        account_number: Account number must contain only letters and numbers
                      message: Validation failed
                    request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    success: false
                    timestamp: '2026-10-30T09:15:02.481Z'
                invalid_type:
                  summary: type is neither bank nor mobile_money
                  value:
                    code: VALIDATION_ERROR
                    correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    detail: >-
                      Invalid beneficiary type: must be bank or mobile_money,
                      got 'card'
                    extensions:
                      field: type
                      reason: must be bank or mobile_money, got 'card'
                    request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    status: 400
                    timestamp: '2026-10-30T09:15:02Z'
                    title: Validation Error
                    type: https://api.bitnob.com/errors/VALIDATION_ERROR
                lookup_failed:
                  summary: >-
                    Our partner could not resolve the account (or did not
                    answer)
                  value:
                    code: VALIDATION_ERROR
                    correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    detail: >-
                      Unable to verify account details. Please check the
                      information and try again.
                    extensions:
                      country: NG
                    request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    status: 400
                    timestamp: '2026-10-30T09:15:02Z'
                    title: Validation Error
                    type: https://api.bitnob.com/errors/VALIDATION_ERROR
                route_disabled:
                  summary: The corridor exists but is switched off for now
                  value:
                    code: VALIDATION_ERROR
                    correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    detail: Payouts to KE are temporarily unavailable.
                    extensions:
                      country: KE
                      reason: route_disabled
                    request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    status: 400
                    timestamp: '2026-10-30T09:15:02Z'
                    title: Validation Error
                    type: https://api.bitnob.com/errors/VALIDATION_ERROR
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - $ref: '#/components/schemas/Problem'
          description: >-
            The handler's checks failed (BAD_REQUEST envelope: country and
            account_number are required, country letters only, account_number
            letters and digits only), or the service refused (VALIDATION_ERROR):
            the corridor is switched off, type is not bank or mobile_money, or
            our partner could not verify the account.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          content:
            application/json:
              examples:
                country_not_supported:
                  summary: The country has no payout corridor
                  value:
                    code: NOT_FOUND
                    correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    detail: country with ID 'ZZ' was not found
                    extensions:
                      id: ZZ
                      resource: country
                    request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    status: 404
                    timestamp: '2026-10-30T09:15:02Z'
                    title: Resource Not Found
                    type: https://api.bitnob.com/errors/NOT_FOUND
              schema:
                $ref: '#/components/schemas/Problem'
          description: The country has no payout corridor.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '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
    PayoutsAccountLookup:
      properties:
        account_name:
          type: string
        account_number:
          type: string
        bank_code:
          description: >-
            Bank code, or the network for mobile money; can be empty for mobile
            money
          type: string
        bank_name:
          description: Bank name in upper case; can be empty, usually for mobile money
          type: string
        country:
          type: string
        is_verified:
          type: boolean
      required:
        - account_name
        - account_number
        - bank_code
        - bank_name
        - country
        - is_verified
      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.
    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
  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'
    Forbidden:
      content:
        application/json:
          examples:
            account_transactions_paused:
              $ref: '#/components/examples/AccountTransactionsPaused'
            client_inactive:
              $ref: '#/components/examples/ClientInactive'
            feature_not_enabled:
              $ref: '#/components/examples/FeatureNotEnabled'
            ip_not_whitelisted:
              $ref: '#/components/examples/IPNotWhitelisted'
            org_not_active:
              $ref: '#/components/examples/OrgNotActive'
            org_not_active_live:
              $ref: '#/components/examples/OrgNotActiveLive'
            tier_product_locked:
              $ref: '#/components/examples/TierProductLocked'
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/Problem'
      description: >-
        Not allowed: the request's IP is not on the key's allowlist, the client
        is inactive, a live key is used before the organisation is active
        (ORG_NOT_ACTIVE), a feature is off (FEATURE_NOT_ENABLED), or the
        organisation's tier does not include the product (TIER_PRODUCT_LOCKED).
      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'
    ServerError:
      content:
        application/json:
          examples:
            internal_error:
              $ref: '#/components/examples/InternalError'
            internal_error_envelope:
              $ref: '#/components/examples/InternalErrorEnvelope'
            internal_error_unhandled:
              $ref: '#/components/examples/InternalErrorUnhandled'
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/Problem'
      description: >-
        Something failed on our side; safe to retry idempotent requests
        (INTERNAL_ERROR).
      headers:
        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:
    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
    AccountTransactionsPaused:
      summary: Money movement is paused on this account
      value:
        code: FEATURE_NOT_ENABLED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: >-
          Transactions on this account are currently paused. Contact support if
          you did not request this.
        extensions:
          feature_key: send_fiat
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 403
        timestamp: '2026-10-30T09:15:02Z'
        title: Account Transactions Paused
        type: https://api.bitnob.com/errors/FEATURE_NOT_ENABLED
    ClientInactive:
      summary: The API key's client is deactivated
      value:
        code: FORBIDDEN
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Client account is inactive
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 403
        timestamp: '2026-10-30T09:15:02Z'
        title: Forbidden
        type: https://api.bitnob.com/errors/FORBIDDEN
    FeatureNotEnabled:
      description: feature_key names the feature that refused the call.
      summary: The feature is off for this organisation
      value:
        code: FEATURE_NOT_ENABLED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: The fiat payouts feature is currently not available.
        extensions:
          feature_key: send_fiat
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 403
        timestamp: '2026-10-30T09:15:02Z'
        title: Feature Not Enabled
        type: https://api.bitnob.com/errors/FEATURE_NOT_ENABLED
    IPNotWhitelisted:
      summary: The request came from an IP not on the key's allowlist
      value:
        code: FORBIDDEN
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: IP address not whitelisted
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 403
        timestamp: '2026-10-30T09:15:02Z'
        title: Forbidden
        type: https://api.bitnob.com/errors/FORBIDDEN
    OrgNotActive:
      description: Live keys only; sandbox requests pass.
      summary: A money-moving operation from an organisation that is not active
      value:
        error:
          code: ORG_NOT_ACTIVE
          message: >-
            Your organisation is not currently active. Please contact your
            administrator.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    OrgNotActiveLive:
      description: Sandbox keys are never refused this way.
      summary: A live key on an organisation that is not active yet
      value:
        error:
          code: ORG_NOT_ACTIVE
          message: >-
            Your business isn't active yet, so live isn't available. Use your
            sandbox keys until it's activated.
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    TierProductLocked:
      summary: The organisation's tier does not include the product
      value:
        code: TIER_PRODUCT_LOCKED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: >-
          Your account's tier 1 does not include USD wire transfers. Upgrade to
          tier 2 to unlock it.
        extensions:
          product: usd_wire
          required_tier: '2'
          tier: '1'
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 403
        timestamp: '2026-10-30T09:15:02Z'
        title: Not Available On Your Tier
        type: https://api.bitnob.com/errors/TIER_PRODUCT_LOCKED
    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'
    InternalError:
      summary: Something failed on our side
      value:
        code: INTERNAL_ERROR
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: An internal error occurred. Please try again later.
        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
    InternalErrorEnvelope:
      summary: A failure answered by the handler
      value:
        error:
          code: INTERNAL_ERROR
          message: Failed to list transactions
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    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
    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.