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

# Preview the SWIFT sender

> Who the sender of a SWIFT payout will be, and whether it can send, by the same rules as initialize. Writes nothing; a preview never submits a profile. The org's KYB comes first on both paths: not verified (and swift_sender_kyb_exempt off) answers eligible false with reason_code KYB_REQUIRED. With customer_id only the KYB status counts, not whether your organisation's own sender details are complete. Without customer_id it previews your organisation (idp's payout sender); a personal account previews its owner. With customer_id it previews that customer by its sender profile state: approved is eligible, also while a newer version is pending or rejected; not_submitted is SENDER_PROFILE_INCOMPLETE with missing_fields, or SENDER_NOT_VERIFIED when complete; pending or rejected with no approved version is SENDER_NOT_VERIFIED; expired is SENDER_EXPIRED; an approved version that lacks a field our partner requires (the customer's email or phone number, for example) is SENDER_PROFILE_INCOMPLETE with missing_fields. An inactive customer (is_active false) is CUSTOMER_INACTIVE whatever its profile state, checked before any of these. Without customer_id the organisation's sender details go through the same completeness check as initialize: a missing account_name, country, city, state, address, post_code or registration_number, which only your verified KYB record supplies, is eligible false with SENDER_PROFILE_INCOMPLETE and missing_fields; when only phone_number, email, business_type, registration_type or registration_issue_date are missing the preview stays eligible and lists them in missing_fields, and initialize needs them in beneficiary.sender. Not behind the active-org check.



## OpenAPI

````yaml /api-collections/swagger/bitnob-api-v2.openapi.json get /api/payouts/sender
openapi: 3.1.0
info:
  description: >-
    The Bitnob API for businesses: customers, virtual accounts, mobile money
    collections, 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.
    name: Virtual accounts
  - description: >-
      One mobile money payment (KES, UGX) requested from a payer's phone and
      credited to your balance. Webhooks for a collection name it
      virtual_account_id; that is the collection id.
    name: Collections
  - 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` is the default when `card_program` is omitted.
      `prepaid_platinum` and `prepaid_premium` must be named.

      - 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: >-
      The company's Card wallet, the USD balance cards are funded from; move
      USDT or USDC into and out of it.
    name: Card wallet
  - 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/sender:
    get:
      tags:
        - Payouts
      summary: Preview the SWIFT sender
      description: >-
        Who the sender of a SWIFT payout will be, and whether it can send, by
        the same rules as initialize. Writes nothing; a preview never submits a
        profile. The org's KYB comes first on both paths: not verified (and
        swift_sender_kyb_exempt off) answers eligible false with reason_code
        KYB_REQUIRED. With customer_id only the KYB status counts, not whether
        your organisation's own sender details are complete. Without customer_id
        it previews your organisation (idp's payout sender); a personal account
        previews its owner. With customer_id it previews that customer by its
        sender profile state: approved is eligible, also while a newer version
        is pending or rejected; not_submitted is SENDER_PROFILE_INCOMPLETE with
        missing_fields, or SENDER_NOT_VERIFIED when complete; pending or
        rejected with no approved version is SENDER_NOT_VERIFIED; expired is
        SENDER_EXPIRED; an approved version that lacks a field our partner
        requires (the customer's email or phone number, for example) is
        SENDER_PROFILE_INCOMPLETE with missing_fields. An inactive customer
        (is_active false) is CUSTOMER_INACTIVE whatever its profile state,
        checked before any of these. Without customer_id the organisation's
        sender details go through the same completeness check as initialize: a
        missing account_name, country, city, state, address, post_code or
        registration_number, which only your verified KYB record supplies, is
        eligible false with SENDER_PROFILE_INCOMPLETE and missing_fields; when
        only phone_number, email, business_type, registration_type or
        registration_issue_date are missing the preview stays eligible and lists
        them in missing_fields, and initialize needs them in beneficiary.sender.
        Not behind the active-org check.
      operationId: payoutsSenderPreview
      parameters:
        - description: Preview this customer of your organisation as the sender
          example: 7c1e4b2a-5f3d-4e8a-b9c6-2d0f1a3e5b78
          in: query
          name: customer_id
          required: false
          schema:
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                customer_approved:
                  summary: An approved customer sender
                  value:
                    data:
                      country: NGA
                      display_name: Adeyemi Foods Limited
                      eligible: true
                      expires_at: '2030-06-01'
                      missing_fields: []
                      reason_code: ''
                      sender_type: business
                      state: approved
                      version: 2
                    message: Sender preview
                    success: true
                    timestamp: '2026-11-05T12:10:00.481Z'
                customer_incomplete:
                  summary: A customer whose profile lacks fields
                  value:
                    data:
                      country: NGA
                      display_name: Chinedu Okafor
                      eligible: false
                      missing_fields:
                        - gender
                        - id_issue_date
                        - document
                      reason_code: SENDER_PROFILE_INCOMPLETE
                      sender_type: individual
                      state: not_submitted
                      version: 1
                    message: Sender preview
                    success: true
                    timestamp: '2026-11-05T12:10:00.481Z'
                customer_newer_version_pending:
                  summary: Approved version 1 sends while version 2 is pending review
                  value:
                    data:
                      country: NGA
                      display_name: Chinedu Okafor
                      eligible: true
                      expires_at: '2032-03-13'
                      missing_fields: []
                      reason_code: ''
                      sender_type: individual
                      state: pending
                      version: 1
                    message: Sender preview
                    success: true
                    timestamp: '2026-11-05T12:10:00.481Z'
                kyb_required:
                  summary: Your organisation's KYB is not verified
                  value:
                    data:
                      country: ''
                      display_name: ''
                      eligible: false
                      reason_code: KYB_REQUIRED
                      sender_type: business
                    message: Sender preview
                    success: true
                    timestamp: '2026-11-05T12:10:00.481Z'
                organization:
                  summary: Your organisation sends
                  value:
                    data:
                      country: NG
                      display_name: Lagoon Payments Limited
                      eligible: true
                      reason_code: ''
                      sender_type: business
                    message: Sender preview
                    success: true
                    timestamp: '2026-11-05T12:10:00.481Z'
                organization_incomplete:
                  summary: >-
                    Your organisation's verified details lack a field only KYB
                    can supply
                  value:
                    data:
                      country: GB
                      display_name: Lagoon Payments Limited
                      eligible: false
                      missing_fields:
                        - state
                        - phone_number
                      reason_code: SENDER_PROFILE_INCOMPLETE
                      sender_type: business
                    message: Sender preview
                    success: true
                    timestamp: '2026-11-05T12:10:00.481Z'
                organization_request_supplies:
                  summary: >-
                    Your organisation sends once the initialize request carries
                    the listed fields
                  value:
                    data:
                      country: NG
                      display_name: Lagoon Payments Limited
                      eligible: true
                      missing_fields:
                        - phone_number
                        - business_type
                      reason_code: ''
                      sender_type: business
                    message: Sender preview
                    success: true
                    timestamp: '2026-11-05T12:10:00.481Z'
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/PayoutsSenderPreview'
                    type: object
          description: OK
        '400':
          content:
            application/json:
              examples:
                customer_id_invalid:
                  $ref: '#/components/examples/SenderCustomerIDInvalid'
              schema:
                $ref: '#/components/schemas/Problem'
          description: customer_id is not a UUID (VALIDATION_ERROR).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          content:
            application/json:
              examples:
                client_inactive:
                  $ref: '#/components/examples/ClientInactive'
                ip_not_whitelisted:
                  $ref: '#/components/examples/IPNotWhitelisted'
                swift_not_enabled:
                  summary: SWIFT is not enabled for this organisation
                  value:
                    code: FEATURE_NOT_ENABLED
                    correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    detail: The SWIFT payouts feature is currently not available.
                    extensions:
                      company_id: 019a3b5c-1f0e-7d2c-8a9b-4c5d6e7f8a90
                      feature_key: swift_payouts_enabled
                    request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
                    status: 403
                    timestamp: '2026-11-05T12:10:00Z'
                    title: Feature Not Enabled
                    type: https://api.bitnob.com/errors/FEATURE_NOT_ENABLED
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - $ref: '#/components/schemas/Problem'
          description: >-
            swift_payouts_enabled is off for your organisation
            (FEATURE_NOT_ENABLED, feature_key in extensions), or the key's IP
            allowlist or client status refused it.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '404':
          content:
            application/json:
              examples:
                customer_not_found:
                  $ref: '#/components/examples/SenderCustomerNotFound'
              schema:
                $ref: '#/components/schemas/Problem'
          description: customer_id is not a customer of your organisation.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '422':
          content:
            application/json:
              examples:
                customer_type_ambiguous:
                  $ref: '#/components/examples/CustomerTypeAmbiguous'
                sender_self_row:
                  $ref: '#/components/examples/SenderSelfRow'
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            The customer's customer_type is not exactly individual or business
            (VALIDATION_FAILED, CUSTOMER_TYPE_AMBIGUOUS in extensions), or
            customer_id names the personal account owner's own record
            (VALIDATION_FAILED, SENDER_SELF_ROW in extensions).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
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
    PayoutsSenderPreview:
      description: >-
        Who the SWIFT sender will be. state and version are on the customer path
        only, as is expires_at; missing_fields is always present on the customer
        path and on the organisation path only when a field is missing.
      properties:
        country:
          description: >-
            The sender's country (alpha-2 on the org path, the profile's alpha-3
            on the customer path)
          type: string
        display_name:
          type: string
        eligible:
          type: boolean
        expires_at:
          description: >-
            When the approved version expires; absent without an approved
            version.
          format: date
          type: string
        missing_fields:
          description: >-
            What the sender lacks, by the names initialize reports in its
            SENDER_PROFILE_INCOMPLETE missing_fields. Customer path: empty
            unless reason_code is SENDER_PROFILE_INCOMPLETE. Organisation path:
            with SENDER_PROFILE_INCOMPLETE, the required keys your
            organisation's sender details lack; while eligible, the keys among
            phone_number, email, business_type, registration_type and
            registration_issue_date that your organisation's details lack, which
            the initialize request must then carry in beneficiary.sender.
          items:
            type: string
          type: array
        reason_code:
          description: Empty when eligible
          enum:
            - ''
            - KYB_REQUIRED
            - SENDER_NOT_VERIFIED
            - SENDER_PROFILE_INCOMPLETE
            - SENDER_EXPIRED
            - CUSTOMER_INACTIVE
          type: string
        sender_type:
          enum:
            - individual
            - business
          type: string
        state:
          description: >-
            The working version's state. It can be pending or rejected while the
            sender is eligible as an earlier approved version.
          enum:
            - not_submitted
            - pending
            - approved
            - rejected
            - expired
          type: string
        version:
          description: >-
            The approved version a payout sends as, when there is one; otherwise
            the working version.
          type: integer
      required:
        - eligible
        - reason_code
        - sender_type
        - display_name
        - country
      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
    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.
    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
  examples:
    SenderCustomerIDInvalid:
      summary: customer_id is not a UUID
      value:
        code: VALIDATION_ERROR
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: customer_id must be a UUID
        extensions:
          field: customer_id
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 400
        timestamp: '2026-11-05T13:01:22Z'
        title: Validation Error
        type: https://api.bitnob.com/errors/VALIDATION_ERROR
    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
    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
    SenderCustomerNotFound:
      summary: customer_id is not a customer of your organisation
      value:
        code: NOT_FOUND
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: customer with ID '7c1e4b2a-5f3d-4e8a-b9c6-2d0f1a3e5b78' was not found
        extensions:
          id: 7c1e4b2a-5f3d-4e8a-b9c6-2d0f1a3e5b78
          resource: customer
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 404
        timestamp: '2026-11-05T13:01:22Z'
        title: Resource Not Found
        type: https://api.bitnob.com/errors/NOT_FOUND
    CustomerTypeAmbiguous:
      summary: customer_type is not exactly individual or business
      value:
        code: VALIDATION_FAILED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: >-
          Only a customer whose type is exactly individual or business can be a
          sender.
        extensions:
          customer_type: individual,cardholder
          error_code: CUSTOMER_TYPE_AMBIGUOUS
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 422
        timestamp: '2026-11-05T13:01:22Z'
        title: Customer Type Ambiguous
        type: https://api.bitnob.com/errors/VALIDATION_FAILED
    SenderSelfRow:
      summary: customer_id names the workspace owner's own record
      value:
        code: VALIDATION_FAILED
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: >-
          The workspace owner's own record cannot be used as a payout sender.
          Leave out customer_id to send as the owner.
        extensions:
          customer_id: 7c1e4b2a-5f3d-4e8a-b9c6-2d0f1a3e5b78
          error_code: SENDER_SELF_ROW
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        status: 422
        timestamp: '2026-11-05T13:01:22Z'
        title: Not a Payout Sender
        type: https://api.bitnob.com/errors/VALIDATION_FAILED
    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
    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
  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'
    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'
  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.