openapi: 3.0.3
info:
  title: Bitnob API v2
  version: 2.0.0
  description: "# Bitnob API v2\n\nA single, ready-to-use collection for the Bitnob Core API v2 — balances, payouts, cards,\
    \ trading, lightning, bulk transfers and more.\n\n## Quick start\n\n1. Set the collection variables:\n   - `base_url`\
    \ — e.g. `https://api.bitnob.com`\n   - `client_id` — your workspace client id\n   - `client_secret` — your workspace\
    \ client secret\n2. Run any request. The **collection-level pre-request script** automatically:\n   - generates a fresh\
    \ `timestamp` + `nonce`,\n   - canonicalises the JSON body (compact form),\n   - computes `HmacSHA256(client_id:timestamp:nonce:body,\
    \ client_secret)`, and\n   - injects `X-Auth-Client`, `X-Auth-Timestamp`, `X-Auth-Nonce`, `X-Auth-Signature`.\n\nYou never\
    \ modify headers manually — just edit the body and hit send.\n\n## Conventions\n\n- **Amounts** are in *base units* (whole\
    \ integers, no decimals). For USDT that's `1 USDT = 1_000_000` units. For BTC that's sats.\n- **`memo`** is only meaningful\
    \ for chains that require a destination tag (e.g. Stellar). Omit it for Tron/Ethereum.\n- **`reference`** is caller-supplied\
    \ and should be unique per action for safe retries / idempotency.\n- Most error responses follow RFC 7807 (`type`, `title`,\
    \ `status`, `detail`, `correlation_id`, `timestamp`).\n\n## Folders\n\nEvery resource lives in its own folder. Happy-path\
    \ requests come first, followed by list/filter endpoints, then action endpoints (`confirm`, `retry`, `cancel`, etc.)."
  contact:
    name: Bitnob
    url: https://bitnob.com
  license:
    name: Proprietary
    url: https://bitnob.com/terms
servers:
- url: https://api.bitnob.com
  description: Production
security:
- BitnobHmacAuth: []
tags:
- name: Identity
  description: Authentication probe for verifying workspace credentials.
- name: Balances
  description: Wallet balances per currency for the authenticated workspace.
- name: Addresses
  description: On-chain deposit addresses for receiving crypto.
- name: Withdrawals
  description: On-chain withdrawals from workspace balance to an external wallet address.
- name: Transactions
  description: Unified transaction history across all movement types.
- name: Exchange rates
  description: Point-in-time conversion rates between supported currencies.
- name: Trading
  description: 'Spot trading: quotes, orders, scheduled DCA, and target (limit-style) orders.'
- name: Bulk transfers
  description: Batched disbursements from CSV or inline items, with optional recurring schedules.
- name: Cards
  description: Virtual and physical card issuance, funding, controls, and transactions. Amounts are in base units of `currency`
    (e.g. USD cents × 100 for `USD` cards).
- name: Lightning
  description: Bitcoin Lightning invoices and payments.
- name: Customers
  description: Customer lifecycle + KYC geography helpers.
- name: Beneficiaries
  description: Saved crypto and fiat payout recipients.
- name: Payouts
  description: 'Fiat payouts to bank accounts and mobile money across supported countries. Flow: **quote → initialize → finalize**.'
paths:
  /api/whoami:
    get:
      tags:
      - Identity
      summary: Who am I
      description: Returns the workspace identity associated with the presented HMAC credentials. Useful as a first call to
        confirm keys, clock skew, and signature formula are all correct.
      operationId: get_api_whoami
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/balances:
    get:
      tags:
      - Balances
      summary: List balances
      description: Returns a paginated balance snapshot per currency. Use it to display wallet balances or reconcile holdings.
      operationId: get_api_balances
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/balances/{currency}:
    get:
      tags:
      - Balances
      summary: Get balance by currency
      description: Single-currency balance (e.g. `USDT`, `BTC`, `USDC`). 404 if the workspace holds no wallet for that currency.
      operationId: get_api_balances_currency
      parameters:
      - name: currency
        in: path
        required: true
        schema:
          type: string
        description: currency identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/addresses:
    post:
      tags:
      - Addresses
      summary: Generate address
      description: Provisions a deposit address for the given `chain`. Labels / references are caller metadata — they don't
        affect the wallet.
      operationId: post_api_addresses
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                chain:
                  type: string
                  example: ethereum
                customer_id:
                  type: string
                  example: cust_abc123
                customer_email:
                  type: string
                  example: john@example.com
                label:
                  type: string
                  example: USDT deposit address
                reference:
                  type: string
                  example: ref-addr-001
              required:
              - chain
              - customer_id
              - customer_email
              - label
              - reference
            example:
              chain: ethereum
              customer_id: cust_abc123
              customer_email: john@example.com
              label: USDT deposit address
              reference: ref-addr-001
    get:
      tags:
      - Addresses
      summary: List addresses
      description: Paginated list of all provisioned addresses across the workspace.
      operationId: get_api_addresses
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/addresses/{id}:
    get:
      tags:
      - Addresses
      summary: Get address by id
      description: Single address by internal id. Useful when reconciling deposits back to a specific address record.
      operationId: get_api_addresses_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/addresses/validate:
    post:
      tags:
      - Addresses
      summary: Validate address
      description: 'Structural validation for an external address + chain pair. Returns `{valid: true|false}`; does not verify
        on-chain existence.'
      operationId: post_api_addresses_validate
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  type: string
                  example: '0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b'
                chain:
                  type: string
                  example: ethereum
              required:
              - address
              - chain
            example:
              address: '0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b'
              chain: ethereum
  /api/addresses/supported-chains:
    get:
      tags:
      - Addresses
      summary: Supported chains
      description: Chains accepted by the address endpoints, including display names and precision.
      operationId: get_api_addresses_supported_chains
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/withdrawals:
    post:
      tags:
      - Withdrawals
      summary: Initiate withdrawal
      description: Debits the workspace balance and broadcasts a transfer. `amount` is in base units (whole integer). `memo`
        only applies to chains requiring a destination tag (e.g. Stellar).
      operationId: post_api_withdrawals
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                to_address:
                  type: string
                  example: '0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b'
                amount:
                  type: string
                  example: '150500000'
                currency:
                  type: string
                  example: USDT
                chain:
                  type: string
                  example: ethereum
                reference:
                  type: string
                  example: withdraw-ref-001
                description:
                  type: string
                  example: Vendor payment
              required:
              - to_address
              - amount
              - currency
              - chain
              - reference
              - description
            example:
              to_address: '0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b'
              amount: '150500000'
              currency: USDT
              chain: ethereum
              reference: withdraw-ref-001
              description: Vendor payment
  /api/transactions:
    get:
      tags:
      - Transactions
      summary: List transactions
      description: Retrieves a paginated list of transactions, with support for filtering via query parameters. Commonly used
        to list transaction histories, audit flows, or search for specific transactions across various dimensions.
      operationId: get_api_transactions
      parameters:
      - name: state
        in: query
        required: false
        schema:
          type: string
          example: completed
        description: ''
      - name: ascending
        in: query
        required: false
        schema:
          type: string
          example: 'true'
        description: ''
      - name: limit
        in: query
        required: false
        schema:
          type: string
          example: '50'
        description: ''
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/transactions/{id}:
    get:
      tags:
      - Transactions
      summary: Get transaction by id
      description: Single transaction envelope with full lifecycle metadata.
      operationId: get_api_transactions_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/exchange-rates:
    get:
      tags:
      - Exchange rates
      summary: Get single-pair rate
      description: Mid-market rate for `from`→`to`.
      operationId: get_api_exchange_rates
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          example: USDT
        description: ''
      - name: to
        in: query
        required: true
        schema:
          type: string
          example: NGN
        description: ''
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/exchange-rates/convert:
    get:
      tags:
      - Exchange rates
      summary: Convert amount
      description: Applies the current rate to `amount` (in `from` display units) and returns the converted value + effective
        rate.
      operationId: get_api_exchange_rates_convert
      parameters:
      - name: from
        in: query
        required: true
        schema:
          type: string
          example: USDT
        description: ''
      - name: to
        in: query
        required: true
        schema:
          type: string
          example: NGN
        description: ''
      - name: amount
        in: query
        required: true
        schema:
          type: string
          example: '100'
        description: ''
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading/prices:
    get:
      tags:
      - Trading
      summary: List all prices
      description: Returns every available pair with its current mid-price.
      operationId: get_api_trading_prices
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading/prices/{pair}:
    get:
      tags:
      - Trading
      summary: Get price by pair
      description: Spot price for a single pair (e.g. `BTCUSD`, `ETHUSD`).
      operationId: get_api_trading_prices_pair
      parameters:
      - name: pair
        in: path
        required: true
        schema:
          type: string
        description: pair identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading/quotes:
    post:
      tags:
      - Trading
      summary: Create quote
      description: Requests a locked quote for a BUY or SELL. The returned `quote_id` must be submitted with a matching order
        before it expires.
      operationId: post_api_trading_quotes
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                base_currency:
                  type: string
                  example: BTC
                quote_currency:
                  type: string
                  example: USDT
                side:
                  type: string
                  example: BUY
                quantity:
                  type: string
                  example: '0.05'
                quantity_in_base_units:
                  type: boolean
              required:
              - base_currency
              - quote_currency
              - side
              - quantity
            example:
              base_currency: BTC
              quote_currency: USDT
              side: BUY
              quantity: '0.05'
              quantity_in_base_units: false
  /api/trading/quotes/{id}:
    get:
      tags:
      - Trading
      summary: Get quote status
      description: Check remaining TTL and fulfilment state for an outstanding quote.
      operationId: get_api_trading_quotes_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading/orders:
    post:
      tags:
      - Trading
      summary: Submit order
      description: Execute a BUY or SELL. Supply the `quote_id` from a fresh quote for best pricing.
      operationId: post_api_trading_orders
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                base_currency:
                  type: string
                  example: BTC
                quote_currency:
                  type: string
                  example: USDT
                side:
                  type: string
                  example: BUY
                quantity:
                  type: string
                  example: '0.05'
                quote_id:
                  type: string
                  example: '{{quote_id}}'
                reference:
                  type: string
                  example: order-ref-001
              required:
              - base_currency
              - quote_currency
              - side
              - quantity
              - quote_id
              - reference
            example:
              base_currency: BTC
              quote_currency: USDT
              side: BUY
              quantity: '0.05'
              quote_id: '{{quote_id}}'
              reference: order-ref-001
    get:
      tags:
      - Trading
      summary: List orders
      description: Paginated order history with optional filters.
      operationId: get_api_trading_orders
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          example: filled
        description: ''
      - name: limit
        in: query
        required: false
        schema:
          type: string
          example: '50'
        description: ''
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading/orders/{id}:
    get:
      tags:
      - Trading
      summary: Get order by id or reference
      description: Fetch an individual order by its id or your supplied reference.
      operationId: get_api_trading_orders_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading/scheduled-orders:
    post:
      tags:
      - Trading
      summary: Create scheduled order
      description: Creates a recurring buy/sell on a `daily`, `weekly`, or `monthly` cadence.
      operationId: post_api_trading_scheduled_orders
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                currency:
                  type: string
                  example: BTC
                quote_currency:
                  type: string
                  example: USDT
                amount:
                  type: string
                  example: '50000000'
                frequency:
                  type: string
                  example: weekly
                day_of_week:
                  type: integer
                execution_time:
                  type: string
                  example: 09:00
                reference:
                  type: string
                  example: dca-ref-001
              required:
              - currency
              - quote_currency
              - amount
              - frequency
              - day_of_week
              - execution_time
              - reference
            example:
              currency: BTC
              quote_currency: USDT
              amount: '50000000'
              frequency: weekly
              day_of_week: 1
              execution_time: 09:00
              reference: dca-ref-001
    get:
      tags:
      - Trading
      summary: List scheduled orders
      description: All scheduled orders for the workspace.
      operationId: get_api_trading_scheduled_orders
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading/scheduled-orders/{id}:
    get:
      tags:
      - Trading
      summary: Get scheduled order
      description: Details for a single recurring order.
      operationId: get_api_trading_scheduled_orders_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Trading
      summary: Update scheduled order
      description: 'Mutate amount, cadence, or status. Pass `status: paused` to halt future executions without cancelling.'
      operationId: put_api_trading_scheduled_orders_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: string
                  example: '200000000'
                status:
                  type: string
                  example: paused
                execution_time:
                  type: string
                  example: '10:00'
              required:
              - amount
              - status
              - execution_time
            example:
              amount: '200000000'
              status: paused
              execution_time: '10:00'
  /api/trading/scheduled-orders/{id}/executions:
    get:
      tags:
      - Trading
      summary: List scheduled-order executions
      description: Execution log for a scheduled order.
      operationId: get_api_trading_scheduled_orders_id_executions
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading/target-orders:
    post:
      tags:
      - Trading
      summary: Create target order
      description: Creates a target order that fires when `target_price` is met. Optionally set `expires_at` to auto-cancel.
      operationId: post_api_trading_target_orders
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                base_currency:
                  type: string
                  example: BTC
                quote_currency:
                  type: string
                  example: USDT
                side:
                  type: string
                  example: BUY
                quantity:
                  type: string
                  example: '0.10'
                target_price:
                  type: string
                  example: '60000.00'
                expires_at:
                  type: string
                  example: ''
                reference:
                  type: string
                  example: target-ref-001
              required:
              - base_currency
              - quote_currency
              - side
              - quantity
              - target_price
              - reference
            example:
              base_currency: BTC
              quote_currency: USDT
              side: BUY
              quantity: '0.10'
              target_price: '60000.00'
              expires_at: ''
              reference: target-ref-001
    get:
      tags:
      - Trading
      summary: List target orders
      description: All target orders, filterable by status.
      operationId: get_api_trading_target_orders
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/trading/target-orders/{id}:
    get:
      tags:
      - Trading
      summary: Get target order
      description: Details for a single target order.
      operationId: get_api_trading_target_orders_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/bulk-transfers:
    post:
      tags:
      - Bulk transfers
      summary: Create draft batch
      description: Creates a draft with inline items. Amounts are in base units.
      operationId: post_api_bulk_transfers
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  example: March payroll batch
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      row_index:
                        type: integer
                      chain:
                        type: string
                        example: ethereum
                      currency:
                        type: string
                        example: USDT
                      address:
                        type: string
                        example: '0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b'
                      amount:
                        type: string
                        example: '100000000'
                      reference:
                        type: string
                        example: bulk-item-1
                    required:
                    - row_index
                    - chain
                    - currency
                    - address
                    - amount
                    - reference
              required:
              - description
              - items
            example:
              description: March payroll batch
              items:
              - row_index: 1
                chain: ethereum
                currency: USDT
                address: '0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b'
                amount: '100000000'
                reference: bulk-item-1
    get:
      tags:
      - Bulk transfers
      summary: List batches
      description: Paginated batch history.
      operationId: get_api_bulk_transfers
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/bulk-transfers/upload-urls:
    post:
      tags:
      - Bulk transfers
      summary: Get upload URL (S3 presigned)
      description: Returns a presigned PUT URL for uploading a CSV. Upload directly to S3, then call **Preview uploaded file**
        with the returned `upload_id`.
      operationId: post_api_bulk_transfers_upload_urls
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filename:
                  type: string
                  example: payroll.csv
              required:
              - filename
            example:
              filename: payroll.csv
  /api/bulk-transfers/previews:
    post:
      tags:
      - Bulk transfers
      summary: Preview uploaded file
      description: Parses and validates the uploaded CSV, returning row-level status before confirmation.
      operationId: post_api_bulk_transfers_previews
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                upload_id:
                  type: string
                  example: '{{upload_id}}'
              required:
              - upload_id
            example:
              upload_id: '{{upload_id}}'
  /api/bulk-transfers/{batchId}:
    get:
      tags:
      - Bulk transfers
      summary: Get batch
      description: Single batch with per-item status.
      operationId: get_api_bulk_transfers_batchId
      parameters:
      - name: batchId
        in: path
        required: true
        schema:
          type: string
        description: batchId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/bulk-transfers/{batchId}/confirm:
    post:
      tags:
      - Bulk transfers
      summary: Confirm batch
      description: Promotes a draft batch to execution. Irreversible — funds are debited.
      operationId: post_api_bulk_transfers_batchId_confirm
      parameters:
      - name: batchId
        in: path
        required: true
        schema:
          type: string
        description: batchId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
            example: {}
  /api/bulk-transfers/{batchId}/retry:
    post:
      tags:
      - Bulk transfers
      summary: Retry failed items
      description: Retries only the listed item ids within a partially-failed batch.
      operationId: post_api_bulk_transfers_batchId_retry
      parameters:
      - name: batchId
        in: path
        required: true
        schema:
          type: string
        description: batchId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                item_ids:
                  type: array
                  items:
                    type: string
                    example: item-uuid-1
              required:
              - item_ids
            example:
              item_ids:
              - item-uuid-1
              - item-uuid-2
  /api/bulk-transfers/schedules:
    post:
      tags:
      - Bulk transfers
      summary: Create schedule
      description: Clones `template_batch_id` on the given cadence. Leave `end_date` empty for open-ended.
      operationId: post_api_bulk_transfers_schedules
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                template_batch_id:
                  type: string
                  example: batch_template_1
                frequency:
                  type: string
                  example: weekly
                execution_time:
                  type: string
                  example: 09:00
                day_of_week:
                  type: integer
                day_of_month:
                  type: integer
                start_date:
                  type: string
                  format: date
                  example: '2026-05-01'
                end_date:
                  type: string
                  example: ''
              required:
              - template_batch_id
              - frequency
              - execution_time
              - day_of_week
              - start_date
            example:
              template_batch_id: batch_template_1
              frequency: weekly
              execution_time: 09:00
              day_of_week: 1
              day_of_month: 0
              start_date: '2026-05-01'
              end_date: ''
    get:
      tags:
      - Bulk transfers
      summary: List schedules
      description: All active and paused schedules.
      operationId: get_api_bulk_transfers_schedules
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/bulk-transfers/schedules/{scheduleId}:
    put:
      tags:
      - Bulk transfers
      summary: Update schedule
      description: Mutate cadence, execution window, or pause/resume via `status`.
      operationId: put_api_bulk_transfers_schedules_scheduleId
      parameters:
      - name: scheduleId
        in: path
        required: true
        schema:
          type: string
        description: scheduleId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  example: paused
                execution_time:
                  type: string
                  example: '10:00'
                day_of_week:
                  type: integer
                day_of_month:
                  type: integer
                end_date:
                  type: string
                  example: ''
              required:
              - status
              - execution_time
              - day_of_week
            example:
              status: paused
              execution_time: '10:00'
              day_of_week: 1
              day_of_month: 0
              end_date: ''
  /api/bulk-transfers/schedules/{scheduleId}/executions:
    get:
      tags:
      - Bulk transfers
      summary: List schedule executions
      description: Execution history for a schedule. Each execution resolves to a concrete batch id.
      operationId: get_api_bulk_transfers_schedules_scheduleId_executions
      parameters:
      - name: scheduleId
        in: path
        required: true
        schema:
          type: string
        description: scheduleId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/bulk-transfers/executions/{executionId}/retry:
    post:
      tags:
      - Bulk transfers
      summary: Retry failed execution
      description: Retries an execution that failed partway. No-op if already completed.
      operationId: post_api_bulk_transfers_executions_executionId_retry
      parameters:
      - name: executionId
        in: path
        required: true
        schema:
          type: string
        description: executionId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
            example: {}
  /api/cards:
    post:
      tags:
      - Cards
      summary: Create card (embedded customer)
      description: Issues a new card and creates the customer in the same call. For existing customers, pass `customer_id`
        instead of the nested `customer` block.
      operationId: post_api_cards
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                card_type:
                  type: string
                  example: virtual
                name:
                  type: string
                  example: Ifeoma Okafor
                currency:
                  type: string
                  example: USD
                amount:
                  type: integer
                webhook_url:
                  type: string
                  format: uri
                  example: https://example.com/webhooks/cards
                created_by:
                  type: string
                  format: uuid
                  example: 550e8400-e29b-41d4-a716-446655440000
                contactless_payment:
                  type: boolean
                customer:
                  type: object
                  properties:
                    customer_type:
                      type: string
                      example: individual
                    first_name:
                      type: string
                      example: Ifeoma
                    last_name:
                      type: string
                      example: Okafor
                    date_of_birth:
                      type: string
                      format: date
                      example: '1993-07-08'
                    id_type:
                      type: string
                      example: national_id
                    id_number:
                      type: string
                      example: NIN12345678901
                    email:
                      type: string
                      example: ifeoma.okafor@example.com
                    phone_number:
                      type: string
                      example: '8034567890'
                    dial_code:
                      type: string
                      example: '+234'
                    line1:
                      type: string
                      example: 18 Wuse Zone 4
                    city:
                      type: string
                      example: Abuja
                    state:
                      type: string
                      example: FCT
                    postal_code:
                      type: string
                      example: '900271'
                    country:
                      type: string
                      example: NGA
                  required:
                  - customer_type
                  - first_name
                  - last_name
                  - date_of_birth
                  - id_type
                  - id_number
                  - email
                  - phone_number
                  - dial_code
                  - line1
                  - city
                  - state
                  - postal_code
                  - country
                card_limits:
                  type: object
                  properties:
                    single_transaction:
                      type: string
                      example: '1000.00'
                    daily:
                      type: string
                      example: '5000.00'
                    weekly:
                      type: string
                      example: '20000.00'
                    monthly:
                      type: string
                      example: '50000.00'
                  required:
                  - single_transaction
                  - daily
                  - weekly
                  - monthly
              required:
              - card_type
              - name
              - currency
              - amount
              - webhook_url
              - created_by
              - contactless_payment
              - customer
              - card_limits
            example:
              card_type: virtual
              name: Ifeoma Okafor
              currency: USD
              amount: 5000000
              webhook_url: https://example.com/webhooks/cards
              created_by: 550e8400-e29b-41d4-a716-446655440000
              contactless_payment: true
              customer:
                customer_type: individual
                first_name: Ifeoma
                last_name: Okafor
                date_of_birth: '1993-07-08'
                id_type: national_id
                id_number: NIN12345678901
                email: ifeoma.okafor@example.com
                phone_number: '8034567890'
                dial_code: '+234'
                line1: 18 Wuse Zone 4
                city: Abuja
                state: FCT
                postal_code: '900271'
                country: NGA
              card_limits:
                single_transaction: '1000.00'
                daily: '5000.00'
                weekly: '20000.00'
                monthly: '50000.00'
    get:
      tags:
      - Cards
      summary: List cards
      description: Paginated card inventory for the workspace.
      operationId: get_api_cards
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/cards/encryption-key:
    post:
      tags:
      - Cards
      summary: Register encryption key
      description: Registers a workspace-wide public key. Secure-details endpoints return card PAN/CVV encrypted with this
        key.
      operationId: post_api_cards_encryption_key
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                public_key_pem:
                  type: string
                  example: '-----BEGIN PUBLIC KEY-----

                    ...

                    -----END PUBLIC KEY-----'
              required:
              - public_key_pem
            example:
              public_key_pem: '-----BEGIN PUBLIC KEY-----

                ...

                -----END PUBLIC KEY-----'
  /api/cards/team-members:
    get:
      tags:
      - Cards
      summary: List team-member cards
      description: Cards owned by workspace team members (distinct from customer-issued cards).
      operationId: get_api_cards_team_members
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/cards/transactions:
    get:
      tags:
      - Cards
      summary: List all card transactions
      description: Workspace-wide card transaction feed across every card.
      operationId: get_api_cards_transactions
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/cards/{cardId}:
    get:
      tags:
      - Cards
      summary: Get card
      description: Card metadata (masked PAN, status, balances, limits).
      operationId: get_api_cards_cardId
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          type: string
        description: cardId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Cards
      summary: Terminate card
      description: Permanently terminates the card. Remaining balance sweeps back to the workspace wallet.
      operationId: delete_api_cards_cardId
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          type: string
        description: cardId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  example: Card no longer needed
              required:
              - reason
            example:
              reason: Card no longer needed
  /api/cards/{cardId}/secure:
    get:
      tags:
      - Cards
      summary: Get secure card details
      description: Full PAN/CVV/expiry encrypted with the workspace public key registered via **Register encryption key**.
      operationId: get_api_cards_cardId_secure
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          type: string
        description: cardId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/cards/{cardId}/transactions:
    get:
      tags:
      - Cards
      summary: List card transactions (by card)
      description: Transactions scoped to one card.
      operationId: get_api_cards_cardId_transactions
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          type: string
        description: cardId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/cards/{cardId}/transactions/{transactionId}:
    get:
      tags:
      - Cards
      summary: Get single card transaction
      description: Single transaction with clearing, settlement, and dispute metadata.
      operationId: get_api_cards_cardId_transactions_transactionId
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          type: string
        description: cardId identifier
      - name: transactionId
        in: path
        required: true
        schema:
          type: string
        description: transactionId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/cards/{cardId}/balance:
    post:
      tags:
      - Cards
      summary: Fund or withdraw balance
      description: '`type: fund` debits the workspace balance and credits the card. `type: withdraw` reverses it. `amount`
        is in base units of the card currency.'
      operationId: post_api_cards_cardId_balance
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          type: string
        description: cardId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  example: fund
                amount:
                  type: integer
                reference:
                  type: string
                  example: fund-ref-001
              required:
              - type
              - amount
              - reference
            example:
              type: fund
              amount: 5000000
              reference: fund-ref-001
  /api/cards/{cardId}/status:
    post:
      tags:
      - Cards
      summary: Freeze or unfreeze
      description: 'Set `status: frozen` to block authorisations, `status: active` to resume.'
      operationId: post_api_cards_cardId_status
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          type: string
        description: cardId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  example: frozen
              required:
              - status
            example:
              status: frozen
  /api/cards/{cardId}/spend-limits:
    put:
      tags:
      - Cards
      summary: Update spend limits
      description: Mutate transaction/daily/weekly/monthly/yearly/all-time limits. Values in base units.
      operationId: put_api_cards_cardId_spend_limits
      parameters:
      - name: cardId
        in: path
        required: true
        schema:
          type: string
        description: cardId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spending_limits:
                  type: object
                  properties:
                    transaction_limit:
                      type: integer
                    daily_limit:
                      type: integer
                    weekly_limit:
                      type: integer
                    monthly_limit:
                      type: integer
                    yearly_limit:
                      type: integer
                    all_time_limit:
                      type: integer
                  required:
                  - transaction_limit
                  - daily_limit
                  - weekly_limit
                  - monthly_limit
                  - yearly_limit
              required:
              - spending_limits
            example:
              spending_limits:
                transaction_limit: 10000000
                daily_limit: 50000000
                weekly_limit: 200000000
                monthly_limit: 500000000
                yearly_limit: 6000000000
                all_time_limit: 0
  /api/lightning/invoices:
    post:
      tags:
      - Lightning
      summary: Create invoice
      description: Issues a BOLT11 invoice for the given customer. Amount is in satoshis.
      operationId: post_api_lightning_invoices
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                  example: cust_abc123
                amount:
                  type: integer
                description:
                  type: string
                  example: 'Payment for invoice #1234'
                expiry:
                  type: integer
                reference:
                  type: string
                  example: ln-inv-001
              required:
              - customer_id
              - amount
              - description
              - expiry
              - reference
            example:
              customer_id: cust_abc123
              amount: 50000
              description: 'Payment for invoice #1234'
              expiry: 3600
              reference: ln-inv-001
    get:
      tags:
      - Lightning
      summary: List invoices
      description: Invoice history with filters.
      operationId: get_api_lightning_invoices
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/lightning/invoices/{id}:
    get:
      tags:
      - Lightning
      summary: Get invoice
      description: Invoice by id, including payment status.
      operationId: get_api_lightning_invoices_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/lightning/decode:
    post:
      tags:
      - Lightning
      summary: Decode BOLT11
      description: Structurally decodes a BOLT11 string into amount, expiry, description, routing hints, etc. Does not initiate
        payment.
      operationId: post_api_lightning_decode
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request:
                  type: string
                  example: lnbc500u1pj9qk7pp5...
              required:
              - request
            example:
              request: lnbc500u1pj9qk7pp5...
  /api/lightning/preview:
    post:
      tags:
      - Lightning
      summary: Preview payment
      description: Simulates routing and fee discovery for a BOLT11 without actually paying. Returns estimated fees + path.
      operationId: post_api_lightning_preview
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request:
                  type: string
                  example: lnbc500u1pj9qk7pp5...
              required:
              - request
            example:
              request: lnbc500u1pj9qk7pp5...
  /api/lightning/pay:
    post:
      tags:
      - Lightning
      summary: Send payment
      description: Pays a BOLT11. Bounded by `max_fee` (sats). Idempotent on `reference`.
      operationId: post_api_lightning_pay
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                  example: cust_abc123
                request:
                  type: string
                  example: lnbc500u1pj9qk7pp5...
                reference:
                  type: string
                  example: ln-pay-001
                max_fee:
                  type: integer
              required:
              - customer_id
              - request
              - reference
              - max_fee
            example:
              customer_id: cust_abc123
              request: lnbc500u1pj9qk7pp5...
              reference: ln-pay-001
              max_fee: 1000
  /api/customers/countries:
    get:
      tags:
      - Customers
      summary: List countries
      description: Countries accepted for customer registration.
      operationId: get_api_customers_countries
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/customers/countries/{countryCode}/states:
    get:
      tags:
      - Customers
      summary: List states for country
      description: State / province list for a country. Used to populate KYC address forms.
      operationId: get_api_customers_countries_countryCode_states
      parameters:
      - name: countryCode
        in: path
        required: true
        schema:
          type: string
        description: countryCode identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/customers:
    post:
      tags:
      - Customers
      summary: Create customer
      description: Create a customer record. KYC fields (`id_type`, `id_number`) are required for card issuance in most regions.
      operationId: post_api_customers
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: alice@example.com
                customer_type:
                  type: string
                  example: individual
                first_name:
                  type: string
                  example: Alice
                last_name:
                  type: string
                  example: Johnson
                date_of_birth:
                  type: string
                  format: date
                  example: '1990-05-15'
                id_type:
                  type: string
                  example: passport
                id_number:
                  type: string
                  example: A12345678
                country:
                  type: string
                  example: USA
              required:
              - email
              - customer_type
              - first_name
              - last_name
              - date_of_birth
              - id_type
              - id_number
              - country
            example:
              email: alice@example.com
              customer_type: individual
              first_name: Alice
              last_name: Johnson
              date_of_birth: '1990-05-15'
              id_type: passport
              id_number: A12345678
              country: USA
    get:
      tags:
      - Customers
      summary: List customers
      description: Paginated customers.
      operationId: get_api_customers
      parameters:
      - name: first_name
        in: query
        required: false
        schema:
          type: string
          example: alice
        description: ''
      - name: email
        in: query
        required: false
        schema:
          type: string
        description: ''
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/customers/{customerId}:
    get:
      tags:
      - Customers
      summary: Get customer
      description: Single customer with KYC status.
      operationId: get_api_customers_customerId
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
        description: customerId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Customers
      summary: Update customer
      description: Mutate customer fields or toggle active status.
      operationId: put_api_customers_customerId
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
        description: customerId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  example: Alice
                last_name:
                  type: string
                  example: Smith
                is_active:
                  type: boolean
              required:
              - first_name
              - last_name
              - is_active
            example:
              first_name: Alice
              last_name: Smith
              is_active: true
  /api/beneficiaries:
    post:
      tags:
      - Beneficiaries
      summary: Create beneficiary
      description: Save a recipient for reuse. Crypto beneficiaries require `wallet_address`, `currency`, and `network`.
      operationId: post_api_beneficiaries
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Alice Ethereum Wallet
                type:
                  type: string
                  example: CRYPTO
                wallet_address:
                  type: string
                  example: '0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b'
                currency:
                  type: string
                  example: USDT
                network:
                  type: string
                  example: ethereum
              required:
              - name
              - type
              - wallet_address
              - currency
              - network
            example:
              name: Alice Ethereum Wallet
              type: CRYPTO
              wallet_address: '0xd0438C776d03df4FCfF69db78B97e2E6B5Cf033b'
              currency: USDT
              network: ethereum
    get:
      tags:
      - Beneficiaries
      summary: List beneficiaries
      description: Paginated list of saved recipients.
      operationId: get_api_beneficiaries
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/beneficiaries/{beneficiaryId}:
    get:
      tags:
      - Beneficiaries
      summary: Get beneficiary
      description: Single beneficiary.
      operationId: get_api_beneficiaries_beneficiaryId
      parameters:
      - name: beneficiaryId
        in: path
        required: true
        schema:
          type: string
        description: beneficiaryId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Beneficiaries
      summary: Update beneficiary
      description: Mutate name or active status.
      operationId: put_api_beneficiaries_beneficiaryId
      parameters:
      - name: beneficiaryId
        in: path
        required: true
        schema:
          type: string
        description: beneficiaryId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Updated Wallet
                is_active:
                  type: boolean
              required:
              - name
              - is_active
            example:
              name: Updated Wallet
              is_active: true
  /api/payouts/quotes:
    post:
      tags:
      - Payouts
      summary: Create quote
      description: Requests a rate + fee quote. Returns `quoteId` required by Initialize. Quotes expire quickly (seconds to
        minutes).
      operationId: post_api_payouts_quotes
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from_asset:
                  type: string
                  example: USDT
                to_currency:
                  type: string
                  example: NGN
                source:
                  type: string
                  example: offchain
                chain:
                  type: string
                  example: ''
                amount:
                  type: string
                  example: '100000000'
                payment_reason:
                  type: string
                  example: vendor_payment
                reference:
                  type: string
                  example: payout-ref-001
                country:
                  type: string
                  example: NG
              required:
              - from_asset
              - to_currency
              - source
              - amount
              - payment_reason
              - reference
              - country
            example:
              from_asset: USDT
              to_currency: NGN
              source: offchain
              chain: ''
              amount: '100000000'
              payment_reason: vendor_payment
              reference: payout-ref-001
              country: NG
  /api/payouts/{quoteId}/initialize:
    post:
      tags:
      - Payouts
      summary: Initialize payout
      description: Locks the quote and creates the payout intent with the beneficiary. The response includes an id used by
        Finalize.
      operationId: post_api_payouts_quoteId_initialize
      parameters:
      - name: quoteId
        in: path
        required: true
        schema:
          type: string
        description: quoteId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                  example: ''
                beneficiary:
                  type: object
                  properties:
                    type:
                      type: string
                      example: BANK
                    accountNumber:
                      type: string
                      example: '1421795566'
                    accountName:
                      type: string
                      example: CHIAMAKA JENNIFER EZEOBI
                    bankCode:
                      type: string
                      example: '000014'
                  required:
                  - type
                  - accountNumber
                  - accountName
                  - bankCode
                reference:
                  type: string
                  example: init-ref-001
                callback_url:
                  type: string
                  format: uri
                  example: https://example.com/webhooks/payouts
              required:
              - beneficiary
              - reference
              - callback_url
            example:
              customer_id: ''
              beneficiary:
                type: BANK
                accountNumber: '1421795566'
                accountName: CHIAMAKA JENNIFER EZEOBI
                bankCode: '000014'
              reference: init-ref-001
              callback_url: https://example.com/webhooks/payouts
  /api/payouts/{quoteId}/finalize:
    post:
      tags:
      - Payouts
      summary: Finalize payout
      description: Commits the debit and releases the payout to the rails. Irreversible.
      operationId: post_api_payouts_quoteId_finalize
      parameters:
      - name: quoteId
        in: path
        required: true
        schema:
          type: string
        description: quoteId identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
            example: {}
  /api/payouts/account-lookup:
    get:
      tags:
      - Payouts
      summary: Account lookup
      description: Name-resolves a bank account so the UI can show the account holder before the user confirms.
      operationId: get_api_payouts_account_lookup
      parameters:
      - name: country
        in: query
        required: true
        schema:
          type: string
          example: NG
        description: ''
      - name: bank_code
        in: query
        required: true
        schema:
          type: string
          example: '000014'
        description: ''
      - name: account_number
        in: query
        required: true
        schema:
          type: string
          example: '1421795566'
        description: ''
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/payouts/supported-countries:
    get:
      tags:
      - Payouts
      summary: Supported countries
      description: Countries with live payout rails, including display metadata.
      operationId: get_api_payouts_supported_countries
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/payouts/supported-countries/{country}:
    get:
      tags:
      - Payouts
      summary: Country requirements
      description: Per-country beneficiary-field requirements (which fields are required, their validation rules, etc.).
      operationId: get_api_payouts_supported_countries_country
      parameters:
      - name: country
        in: path
        required: true
        schema:
          type: string
        description: country identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/payouts/limits:
    get:
      tags:
      - Payouts
      summary: Payout limits
      description: Workspace-level min/max payout amounts per currency and per rail.
      operationId: get_api_payouts_limits
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/payouts/banks/{countryCode}:
    get:
      tags:
      - Payouts
      summary: Banks by country
      description: Bank / mobile-money directory for a country. Use the returned `code` in Initialize's `bankCode`.
      operationId: get_api_payouts_banks_countryCode
      parameters:
      - name: countryCode
        in: path
        required: true
        schema:
          type: string
        description: countryCode identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/payouts:
    get:
      tags:
      - Payouts
      summary: List payouts
      description: Payout history with filters.
      operationId: get_api_payouts
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: ''
      - name: limit
        in: query
        required: false
        schema:
          type: string
          example: '50'
        description: ''
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/payouts/{id}:
    get:
      tags:
      - Payouts
      summary: Get payout
      description: Single payout, including lifecycle events and rail-specific metadata.
      operationId: get_api_payouts_id
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: id identifier
      responses:
        '200':
          description: Successful response
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (bad HMAC signature or client id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Semantic validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    BitnobHmacAuth:
      type: apiKey
      in: header
      name: X-Auth-Signature
      description: "HMAC-SHA256 authentication. All calls must include four headers:\n- `X-Auth-Client`   — your workspace\
        \ client id\n- `X-Auth-Timestamp` — Unix seconds\n- `X-Auth-Nonce`    — 16-byte random hex\n- `X-Auth-Signature` —\
        \ hex(HMAC-SHA256(\n  `{client_id}:{timestamp}:{nonce}:{compact_json_body}`,\n  client_secret))\n"
  schemas:
    Error:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        code:
          type: string
        correlation_id:
          type: string
        timestamp:
          type: string
          format: date-time
      example:
        type: https://api.bitnob.com/errors/UNAUTHORIZED
        title: Unauthorized
        status: 401
        detail: Invalid HMAC signature
        code: UNAUTHORIZED
        correlation_id: req_019d9b7e-9e76-711e-afbe-aba9b9455412
        timestamp: '2026-04-17T12:50:59.850532036Z'