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

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

# Get an upload URL for a document

> Presigns a PUT for a SWIFT payout invoice (invoice_s3_key on initialize) or a customer's sender document (document_s3_key on PUT /api/customers/{customerId}). PUT the bytes to upload_url with exactly one header, Content-Type set to content_type, and a body of exactly size_bytes bytes, then pass s3_key. Not gated by swift_payouts_enabled. Needs an active organisation on live. Nothing is written until the key is attached; an unattached upload is deleted after a day.



## OpenAPI

````yaml /api-collections/swagger/bitnob-api-v2.openapi.json post /api/payouts/upload-url
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/upload-url:
    post:
      tags:
        - Payouts
      summary: Get an upload URL for a document
      description: >-
        Presigns a PUT for a SWIFT payout invoice (invoice_s3_key on initialize)
        or a customer's sender document (document_s3_key on PUT
        /api/customers/{customerId}). PUT the bytes to upload_url with exactly
        one header, Content-Type set to content_type, and a body of exactly
        size_bytes bytes, then pass s3_key. Not gated by swift_payouts_enabled.
        Needs an active organisation on live. Nothing is written until the key
        is attached; an unattached upload is deleted after a day.
      operationId: payoutsUploadURL
      requestBody:
        content:
          application/json:
            examples:
              passport:
                summary: A sender's passport scan
                value:
                  filename: passport.pdf
                  size_bytes: 241233
            schema:
              properties:
                filename:
                  description: Ends in .pdf, .jpg, .jpeg or .png; no path characters.
                  maxLength: 255
                  type: string
                size_bytes:
                  maximum: 3670016
                  minimum: 1
                  type: integer
              required:
                - filename
                - size_bytes
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                created:
                  summary: Upload URL for a PDF
                  value:
                    data:
                      content_type: application/pdf
                      expires_at: '2026-11-05T09:20:02Z'
                      max_upload_size: 3670016
                      s3_key: >-
                        tmp/019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01/6d2e8f1a-4b3c-4a7d-9e5f-0c1b2a3d4e5f.pdf
                      upload_url: >-
                        https://bitnob-payout-docs.s3.eu-west-2.amazonaws.com/tmp/019a3b5c-1a2b-7c3d-8e4f-5a6b7c8d9e01/6d2e8f1a-4b3c-4a7d-9e5f-0c1b2a3d4e5f.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=8b1f
                    message: Upload URL created
                    success: true
                    timestamp: '2026-11-05T09:15:02.481Z'
              schema:
                allOf:
                  - $ref: '#/components/schemas/Envelope'
                  - properties:
                      data:
                        properties:
                          content_type:
                            type: string
                          expires_at:
                            format: date-time
                            type: string
                          max_upload_size:
                            type: integer
                          s3_key:
                            description: tmp/{your company id}/{uuid}.{ext}
                            type: string
                          upload_url:
                            description: Presigned S3 PUT URL.
                            type: string
                        type: object
                    type: object
          description: OK
        '400':
          content:
            application/json:
              examples:
                invalid_body:
                  summary: The body is not valid JSON
                  value:
                    error:
                      code: BAD_REQUEST
                      message: Invalid request body
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    success: false
                    timestamp: '2026-11-05T09:15:02.481Z'
                invalid_filename:
                  summary: Unsupported file type
                  value:
                    code: VALIDATION_ERROR
                    correlation_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    detail: >-
                      Document filename is not allowed: unsupported file type.
                      Use a .pdf, .jpg, .jpeg or .png file.
                    extensions:
                      error_code: DOCUMENT_INVALID_FILENAME
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    status: 400
                    timestamp: '2026-11-05T09:15:02.481Z'
                    title: Invalid Document Filename
                    type: https://api.bitnob.com/errors/VALIDATION_ERROR
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - $ref: '#/components/schemas/Problem'
          description: >-
            The body is not JSON (BAD_REQUEST), or the filename or size is not
            allowed (VALIDATION_ERROR, DOCUMENT_INVALID_FILENAME in extensions).
          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'
                org_not_active_live:
                  $ref: '#/components/examples/OrgNotActiveLive'
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorEnvelope'
                  - $ref: '#/components/schemas/Problem'
          description: >-
            Not allowed: the organisation is not active on live
            (ORG_NOT_ACTIVE), or the key's IP allowlist or client status refused
            it.
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '422':
          content:
            application/json:
              examples:
                document_too_large:
                  summary: The uploaded object is above 3,670,016 bytes
                  value:
                    code: VALIDATION_FAILED
                    correlation_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    detail: Document exceeds the maximum size of 3.5 MB.
                    extensions:
                      error_code: DOCUMENT_TOO_LARGE
                      max_size_bytes: 3670016
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    status: 422
                    timestamp: '2026-11-05T09:15:02.481Z'
                    title: Document Too Large
                    type: https://api.bitnob.com/errors/VALIDATION_FAILED
              schema:
                $ref: '#/components/schemas/Problem'
          description: size_bytes is above 3,670,016 (DOCUMENT_TOO_LARGE in extensions).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          content:
            application/json:
              examples:
                document_uploads_unavailable:
                  summary: Document storage is not available
                  value:
                    code: VALIDATION_ERROR
                    correlation_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    detail: >-
                      Document uploads are temporarily unavailable. Please try
                      again later.
                    extensions:
                      error_code: DOCUMENT_UPLOADS_UNAVAILABLE
                    request_id: req_019a3e21-4b6c-7d8e-9fa0-b1c2d3e4f5a6
                    status: 503
                    timestamp: '2026-11-05T09:15:02.481Z'
                    title: Document Uploads Unavailable
                    type: https://api.bitnob.com/errors/VALIDATION_ERROR
              schema:
                $ref: '#/components/schemas/Problem'
          description: >-
            Document storage is not configured or presigning failed
            (DOCUMENT_UPLOADS_UNAVAILABLE in extensions).
          headers:
            X-Correlation-ID:
              $ref: '#/components/headers/X-Correlation-ID'
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
    ErrorEnvelope:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - properties:
            success:
              const: false
          required:
            - error
          type: object
      description: >-
        The envelope as an error: success is false, error is set, data is
        absent.
    Problem:
      description: >-
        RFC 7807 problem. Returned when authentication fails and for errors
        raised by the services behind a handler (validation, domain refusals
        such as FEATURE_NOT_ENABLED or PRECONDITION_FAILED, partner outages);
        branch on code.
      properties:
        code:
          description: >-
            Machine-readable; branch on this, not on the status or the wording.
            For example VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN,
            FEATURE_NOT_ENABLED, PERSONAL_WORKSPACE_CUSTOMERS,
            TIER_PRODUCT_LOCKED, NOT_FOUND, DUPLICATE_KEY_ERROR, ALREADY_EXISTS,
            PRECONDITION_FAILED, INSUFFICIENT_FUNDS, TIER_LIMIT_REACHED,
            RATE_LIMIT_EXCEEDED, TIMEOUT, SERVICE_UNAVAILABLE,
            LIMITS_UNAVAILABLE, PLATFORM_PAUSED, INTERNAL_ERROR.
          type: string
        correlation_id:
          description: >-
            The request's correlation id, the same value as the X-Correlation-ID
            response header.
          type: string
        detail:
          description: >-
            What went wrong for this request, safe to show; internal and partner
            failures carry a generic sentence.
          type: string
        extensions:
          additionalProperties: true
          description: >-
            Code-specific facts, for example feature_key (FEATURE_NOT_ENABLED),
            field or field_violations (VALIDATION_ERROR), rail, window, limit,
            used, requested and remaining (TIER_LIMIT_REACHED), scope
            (PLATFORM_PAUSED).
          type: object
        instance:
          type: string
        request_id:
          description: Equal to correlation_id.
          type: string
        status:
          description: The HTTP status, repeated.
          type: integer
        timestamp:
          format: date-time
          type: string
        title:
          description: >-
            Short summary of the code, for example Validation Error or Feature
            Not Enabled.
          type: string
        type:
          description: https://api.bitnob.com/errors/{code}
          format: uri
          type: string
      required:
        - type
        - title
        - status
        - code
        - timestamp
      type: object
    ErrorInfo:
      properties:
        code:
          description: >-
            Machine-readable, for example BAD_REQUEST, NOT_FOUND, CONFLICT,
            ORG_NOT_ACTIVE, RATE_LIMIT_EXCEEDED, SERVICE_UNAVAILABLE,
            INTERNAL_ERROR.
          type: string
        details:
          additionalProperties: true
          description: >-
            For field validation, a map of field name to message ("email":
            "Email must be a valid email address"); for a body that does not
            decode, the offending field.
          type: object
        message:
          type: string
      required:
        - message
      type: object
  headers:
    X-Correlation-ID:
      description: >-
        Generated for every request (any value the client sends is ignored);
        quote it to support. Errors repeat it as request_id and correlation_id.
      example: req_019a3b5c-7d1e-7f20-8a4b-3c5d6e7f8091
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      example: 1
      schema:
        minimum: 0
        type: integer
  responses:
    Unauthorized:
      content:
        application/json:
          examples:
            unauthorized_auth_failed:
              $ref: '#/components/examples/UnauthorizedAuthFailed'
            unauthorized_invalid_secret:
              $ref: '#/components/examples/UnauthorizedInvalidSecret'
            unauthorized_invalid_signature:
              $ref: '#/components/examples/UnauthorizedInvalidSignature'
            unauthorized_locked_out:
              $ref: '#/components/examples/UnauthorizedLockedOut'
          schema:
            $ref: '#/components/schemas/Problem'
      description: >-
        Authentication failed: a signing header is missing or malformed, the
        timestamp is more than 5 minutes off, the signature or secret is wrong,
        or the client is locked out after failed checks (UNAUTHORIZED).
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
    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'
  examples:
    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
    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'
    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
  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.