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

# List payouts

> Lists your payouts, newest first.



## OpenAPI

````yaml /api-collections/swagger/bitnob-api-v2.openapi.json get /api/payouts
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:
    get:
      tags:
        - Payouts
      summary: List payouts
      description: Lists your payouts, newest first.
      operationId: payoutsList
      parameters:
        - description: >-
            Page size; values above 50 are cut to 50, and values below 1 or not
            a number fall back to 20
          example: 20
          in: query
          name: limit
          schema:
            default: 20
            maximum: 50
            minimum: 1
            type: integer
        - description: Rows to skip
          example: 0
          in: query
          name: offset
          schema:
            default: 0
            minimum: 0
            type: integer
        - description: Filter by status, case-insensitive
          example: success
          in: query
          name: status
          schema:
            enum:
              - quote
              - initiated
              - pending
              - pending_address_deposit
              - processing
              - success
              - failed
              - expired
              - underpayment
            type: string
        - description: Filter by source asset, case-insensitive
          example: usdt
          in: query
          name: from_asset
          schema:
            enum:
              - btc
              - usdt
              - usdc
              - ngn
            type: string
        - description: Filter by settlement currency, case-insensitive
          example: ngn
          in: query
          name: to_currency
          schema:
            type: string
        - description: Filter by source, case-insensitive
          example: offchain
          in: query
          name: source
          schema:
            enum:
              - offchain
              - onchain
            type: string
        - description: Sort column
          example: created_at
          in: query
          name: sort_field
          schema:
            default: created_at
            enum:
              - created_at
              - updated_at
              - status
              - amount
              - settlement_amount
              - from_asset
              - to_currency
            type: string
        - description: Sort direction
          example: DESC
          in: query
          name: sort_direction
          schema:
            default: DESC
            enum:
              - ASC
              - DESC
            type: string
        - description: Created at or after (RFC 3339); ignored if it does not parse
          example: '2026-10-01T00:00:00Z'
          in: query
          name: from_date
          schema:
            format: date-time
            type: string
        - description: Created at or before (RFC 3339); ignored if it does not parse
          example: '2026-10-31T23:59:59Z'
          in: query
          name: to_date
          schema:
            format: date-time
            type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                empty:
                  summary: No payouts match the filters
                  value:
                    data:
                      has_more: false
                      items: []
                      limit: 20
                      offset: 0
                      total_count: 0
                    message: Payouts retrieved successfully
                    success: true
                    timestamp: '2026-10-30T09:15:02.481Z'
                first_page:
                  summary: First page of two, newest first
                  value:
                    data:
                      has_more: true
                      items:
                        - amount: '100'
                          beneficiary:
                            account_name: Adaeze Okafor
                            account_number: '0000000001'
                            bank_code: '000014'
                            country: NG
                            destination_type: bank
                          btc_amount: '0.00147059'
                          callback_url: https://example.com/webhooks/payouts
                          cent_amount: '14970000'
                          cent_fees: '500000'
                          company_id: 019a3b5c-1f0e-7d2c-8a9b-4c5d6e7f8a90
                          country: NG
                          created_at: '2026-10-30T09:15:02.481Z'
                          exchange_rate:
                            btc_rate: '68000'
                            currency: ngn
                            effective_rate: '1497'
                            rate: '1500'
                          expires_at: '2026-10-30T09:31:02.481Z'
                          fee_currency: USD
                          fees: '0.5'
                          from_asset: USDT
                          id: 019a3b5c-8e21-7a4c-9b3d-2f6e8a1c4d70
                          payment_reason: Supplier invoice 0042
                          quote_id: QT2_100482
                          reference: payout_ref_20261030_0007
                          sat_amount: '147059'
                          settlement_amount: '149700'
                          source: OFFCHAIN
                          source_fee: '0.5'
                          status: SUCCESS
                          to_currency: NGN
                          total_amount: '100.5'
                          trip:
                            completion_time: '2026-10-30T09:18:21.540Z'
                            initialized_at: '2026-10-30T09:16:40.127Z'
                            processing_start: '2026-10-30T09:17:06.311Z'
                            quote_at: '2026-10-30T09:15:02.481Z'
                          updated_at: '2026-10-30T09:18:21.540Z'
                        - amount: '0.0015'
                          beneficiary:
                            account_name: Adaeze Okafor
                            account_number: '0000000001'
                            bank_code: '000014'
                            country: NG
                            destination_type: bank
                          btc_amount: '0.0015'
                          cent_amount: '15269400'
                          cent_fees: '736'
                          company_id: 019a3b5c-1f0e-7d2c-8a9b-4c5d6e7f8a90
                          country: NG
                          created_at: '2026-10-29T14:02:11.004Z'
                          exchange_rate:
                            btc_rate: '68000'
                            currency: ngn
                            effective_rate: '101796000'
                            rate: '1500'
                          expires_at: '2026-10-29T14:08:11.004Z'
                          fee_currency: USD
                          fees: '0.5'
                          from_asset: BTC
                          id: 019a3a9f-6c12-7b40-9e21-0a1b2c3d4e5f
                          quote_id: QT2_100377
                          reference: payout_ref_20261029_0003
                          sat_amount: '150736'
                          settlement_amount: '152694'
                          source: OFFCHAIN
                          source_fee: '0.00000736'
                          status: FAILED
                          to_currency: NGN
                          total_amount: '0.00150736'
                          trip:
                            completion_time: '2026-10-29T14:05:48.117Z'
                            initialized_at: '2026-10-29T14:03:00.218Z'
                            processing_start: '2026-10-29T14:03:20.640Z'
                            quote_at: '2026-10-29T14:02:11.004Z'
                          updated_at: '2026-10-29T14:05:48.117Z'
                      limit: 2
                      offset: 0
                      total_count: 37
                    message: Payouts retrieved successfully
                    success: true
                    timestamp: '2026-10-30T09:15:02.481Z'
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/PayoutsPayoutList'
                    type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '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
    PayoutsPayoutList:
      properties:
        has_more:
          type: boolean
        items:
          items:
            $ref: '#/components/schemas/PayoutsPayout'
          type: array
        limit:
          type: integer
        offset:
          type: integer
        total_count:
          type: integer
      required:
        - items
        - total_count
        - limit
        - offset
        - has_more
      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
    PayoutsPayout:
      description: >-
        A payout or quote. 64-bit integers are sent as strings. Optional fields
        are absent when unset.
      properties:
        address:
          description: Deposit address (or Lightning invoice) for onchain payouts
          type: string
        amount:
          description: >-
            Source amount in major units of from_asset (decimal string),
            excluding fees
          type: string
        beneficiary:
          additionalProperties: true
          description: Beneficiary details as stored
          type: object
        beneficiary_id:
          description: >-
            Saved beneficiary this payout was made to. Older payouts only; new
            payouts carry the details in beneficiary
          format: uuid
          type: string
        btc_amount:
          description: Decimal BTC
          type: string
        callback_url:
          type: string
        cent_amount:
          description: Settlement amount in minor units of to_currency, as a string
          type: string
        cent_fees:
          description: Fee in base units of the source asset, as a string
          type: string
        chain:
          description: CHAIN_TYPE_ followed by the upper-case chain, e.g. CHAIN_TYPE_TRON
          type: string
        company_id:
          anyOf:
            - format: uuid
              type: string
            - const: ''
          description: Empty on the initialize response.
        country:
          description: >-
            ISO 3166-1 alpha-2 destination country; empty on the initialize
            response.
          type: string
        created_at:
          description: Null on the initialize response.
          format: date-time
          type:
            - string
            - 'null'
        customer_id:
          format: uuid
          type: string
        deposit_amount:
          description: Amount to deposit for an onchain payout (initialize response only)
          type: string
        exchange_rate:
          $ref: '#/components/schemas/PayoutsExchangeRate'
        expires_at:
          format: date-time
          type: string
        fee_currency:
          description: Denomination of fees
          type: string
        fees:
          description: Fee as a decimal string, in fee_currency
          type: string
        from_asset:
          enum:
            - BTC
            - USDT
            - USDC
            - NGN
            - UNSPECIFIED_ASSET
          type: string
        id:
          format: uuid
          type: string
        invoice_s3_key:
          type: string
        payment_reason:
          type: string
        quote_id:
          description: Quote identifier used by initialize and finalize
          type: string
        reference:
          type: string
        sat_amount:
          description: >-
            Satoshis, as a string. For BTC this is principal plus fee; for USDT
            and USDC, the BTC value of the principal, for reference
          type: string
        settlement_amount:
          description: Amount the beneficiary receives, in major units of to_currency
          type: string
        source:
          description: >-
            SOURCE_UNSET only on the initialize response, which does not carry
            the source
          enum:
            - OFFCHAIN
            - ONCHAIN
            - SOURCE_UNSET
          type: string
        source_fee:
          description: Fee in major units of from_asset
          type: string
        status:
          enum:
            - QUOTE
            - INITIATED
            - PENDING
            - PENDING_ADDRESS_DEPOSIT
            - PROCESSING
            - SUCCESS
            - FAILED
            - EXPIRED
            - UNDERPAYMENT
          type: string
        to_currency:
          description: Upper-case settlement currency, e.g. NGN
          type: string
        total_amount:
          description: amount plus source_fee, in major units of from_asset
          type: string
        trip:
          $ref: '#/components/schemas/PayoutsTrip'
        updated_at:
          description: Null on the initialize response.
          format: date-time
          type:
            - string
            - 'null'
      required:
        - id
        - quote_id
        - status
        - source
        - from_asset
        - to_currency
        - amount
        - settlement_amount
        - cent_fees
        - fees
        - fee_currency
        - source_fee
        - total_amount
        - company_id
        - country
        - created_at
        - updated_at
      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
    PayoutsExchangeRate:
      description: Rate snapshot on a payout. Values are decimal strings.
      properties:
        btc_rate:
          description: >-
            BTC to USD rate at quote time; 0 on a non-BTC quote taken while the
            rate was unavailable
          type: string
        currency:
          description: >-
            Settlement currency in lower case (for example "ngn"); empty on the
            initialize response.
          type: string
        effective_rate:
          description: settlement_amount divided by amount
          type: string
        rate:
          description: USD to to_currency rate
          type: string
      type: object
    PayoutsTrip:
      description: >-
        Milestones of the payout. Each is an RFC 3339 UTC timestamp, absent
        until reached.
      properties:
        asset_received:
          format: date-time
          type: string
        completion_time:
          format: date-time
          type: string
        initialized_at:
          format: date-time
          type: string
        processing_start:
          format: date-time
          type: string
        quote_at:
          format: date-time
          type: string
        submitted:
          format: date-time
          type: string
      type: object
  responses:
    BadRequest:
      content:
        application/json:
          examples:
            bad_request_field_validation:
              $ref: '#/components/examples/BadRequestFieldValidation'
            bad_request_malformed_json:
              $ref: '#/components/examples/BadRequestMalformedJSON'
            bad_request_wrong_type:
              $ref: '#/components/examples/BadRequestWrongType'
            invalid_auth_timestamp:
              $ref: '#/components/examples/InvalidAuthTimestamp'
            validation_error_field_violations:
              $ref: '#/components/examples/ValidationErrorFieldViolations'
            validation_error_problem:
              $ref: '#/components/examples/ValidationErrorProblem'
          schema:
            oneOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - $ref: '#/components/schemas/Problem'
      description: >-
        The request is invalid. Body and field checks in the handler answer with
        the envelope (BAD_REQUEST, details naming each field); checks in the
        service behind it answer with a Problem (VALIDATION_ERROR).
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
    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'
    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'
    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:
    BadRequestFieldValidation:
      description: >-
        The handler's field checks: details maps each failing field to a
        message.
      summary: A field failed validation
      value:
        error:
          code: BAD_REQUEST
          details:
            customer_type: 'Customer type must be one of: individual business'
            email: Email must be a valid email address
          message: Validation failed
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    BadRequestMalformedJSON:
      summary: The body is not valid JSON
      value:
        error:
          code: BAD_REQUEST
          message: 'Invalid request body: malformed JSON at byte 42'
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    BadRequestWrongType:
      summary: A field has the wrong JSON type
      value:
        error:
          code: BAD_REQUEST
          details:
            field: amount
          message: 'Invalid request body: amount must be a string, got number'
        request_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        success: false
        timestamp: '2026-10-30T09:15:02.481Z'
    InvalidAuthTimestamp:
      summary: X-Auth-Timestamp is not a number
      value:
        code: VALIDATION_ERROR
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: Invalid timestamp format
        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
    ValidationErrorFieldViolations:
      summary: A service rejected several fields
      value:
        code: VALIDATION_ERROR
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: invalid request
        extensions:
          field_violations:
            - description: must be greater than zero
              field: amount
            - description: unsupported chain
              field: chain
        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
    ValidationErrorProblem:
      summary: A service rejected a field
      value:
        code: VALIDATION_ERROR
        correlation_id: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
        detail: phone_number is not a valid phone number for NG
        extensions:
          field: phone_number
        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
    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
    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'
    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'
  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
  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.