openapi: 3.0.0
info:
  title: Busha API
  contact:
    email: developers@busha.co
  description: |
    ## Introduction
    The **Busha API** is designed to provide businesses with tools for borderless financial transactions and operations, enabling modern, global money management. It serves as the backbone for facilitating:
    - Creation and management of multi-currency balances
    - Retrieval of real-time cryptocurrency rates
    - Substantial data insights for business owners

    Whether you’re a product-driven fintech or a developer building integrations, this API significantly accelerates implementation while reducing financial complexities.
    For detailed guides on API integration, visit our [official documentation]().


    ## Authentication
    All API requests require a **Bearer Token** for authentication, passed in the `Authorization` header.
    Your authorization value is a base64 encoded value of your api key and your secret key.
    You can obtain API tokens via your Busha user or business account. Authentication is mandatory to ensure secure and authorized interactions with the API.
    The API keys from the dashboard provides a base64 encoding of the your authorization tokens.

    Your generated Key should look like this:
    `VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=`

    Example Header:
    ``` curl
    Authorization: Bearer VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=
    ```

    ## Error Handling
    #Standardized error responses ensure predictable interactions. Errors are detailed for easy debugging and understanding:
    | **Error Code** | **HTTP Status Code** | **Description** |
    | --- | --- | --- |
    | `bad_request` | 400 | Invalid input or malformed request |
    | `unauthorized` | 401 | Invalid or missing authentication |
    | `not_found` | 404 | Resource not found |
    | `service_unavailable` | 503 | Server error |

    Basic Error Example:
    ``` json
    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      }
    }
    ```

    Schema Error Body Example:
    ``` json
    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      },
      "schema": {
        "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
        "fix": "Ensure that the object being submitted, matches the schema correctly"
      }
    }
    ```

    Field Error Body Example:
    ``` json
    {
      "error": {
        "name": "bad_request",
        "message": "Invalid input data"
      },
      "fields": {
        "field1": [
          {
            "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
          },
        ],
        "field2": [
          {
            "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
          }
        ],
      }
    }
    ```

    ## Pagination
    Pagination uses cursors provided as:
    The API supports **cursor-based pagination** for endpoints with large datasets. Pagination uses a `next_cursor` and `previous_cursor` returned in the response.
    Example Response Format:
    ``` json
    {
      "current_entries_size": 10,
      "next_cursor": "base64_cursor_value",
      "previous_cursor": "base64_previous_cursor_value"
    }
    ```

    ## Rate Limiting
    Rate limits determine how many API calls can be made in a rolling minute. This ensures fair and optimized use of system resources.

    The rate limits allowed by each resource will be provided with the header:
    ```curl
    x-rate-limit 100
    ```
    If this header does not exist, then the rate limit is set at a default 100 req/min

    Requests exceeding the allocated quota will receive a `429 Too Many Requests` response.

    ##  Common Parameters
    Common parameters enhance consistency across endpoints:
      | **Parameter Name** | **Location** | **Description** | **Example** |
      | --- | --- | --- | --- |
      | `X-BU-PROFILE-ID` | Header | User profile identifier | `BUS_qwejinoiuiqw93ejjw` |
      | `id` | Path | Unique NanoID identifier | `dpt_jweqafajsndiun34fd` |
      | `cursor` | Query | Pagination cursor | `base64_cursor_string` |

    #### Paginated Response Example
      ``` json
      {
        "status": "success",
        "message": "Data retrieved",
        "pagination": {
          "next_cursor": "value_for_next_page",
          "current_entries_size": 20
        },
        "data": [...]
      }
      ```
  version: 1.0.0
servers:
  - url: https://api.sandbox.busha.so
    description: Sandbox Environment
  - url: https://api.busha.io
    description: Production Environment
tags:
  - name: Balances
    description: Handles account balances across different currencies.
    x-displayName: Balances
  - name: Bills
    description: Lorem Ipsum
    x-displayName: Bills
  - name: Cards
    description: Lorem Ipsum
    x-displayName: Cards
  - name: Cashback
    description: Main tag for cashback service endpoints
    x-displayName: Cashback
  - name: Currencies
    description: |
      Endpoints to manage supported currencies, their properties, and network details.
    x-displayName: Currencies
  - name: Customers
    x-internal: false
    description: Handle customer requests and responses
    x-displayName: Customers
  - name: Files
    description: Provides APIs to handle files upload
    x-displayName: Files
  - name: Futures
    description: Futures account management
    x-displayName: Futures
  - name: Insights
    description: Business analytics insights endpoints
    x-displayName: Insights
  - name: Mandate
    x-displayName: Mandate
  - name: Miscellaneous
    description: Provides auxiliary APIs to complement and enhance other services.
    x-displayName: Miscellaneous
  - name: News
    description: News article endpoints
    x-displayName: News
  - name: Pairs
    description: Access trading pair information and rates
    x-displayName: Pairs
  - name: PaymentLinks
    description: Payment Links
    x-displayName: PaymentLinks
  - name: PaymentRequests
    description: Payment request
    x-displayName: PaymentRequests
  - name: Pledges
    description: Customer-authorized pledge lifecycle APIs
    x-displayName: Pledges
  - name: PriceAlerts
    description: Price alert management endpoints
    x-displayName: PriceAlerts
  - name: Quotes
    description: Handle quotes requests and responses
    x-displayName: Quotes
  - name: Recipients
    x-displayName: Recipients
  - name: Stocks
    x-displayName: Stocks
  - name: Transactions
    x-displayName: Transactions
  - name: Transfers
    x-displayName: Transfers
  - name: Widget
    description: Widget operations
    x-displayName: Widget
paths:
  /v1/balances:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - balances:write
            - api:write
      tags:
        - Balances
      operationId: createBalance
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      summary: Create currency balance
      description: Creates a new balance for managing funds in a specific currency.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBalanceRequest'
      responses:
        '201':
          description: Balance created successfully
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Balance'
        4XX:
          $ref: '#/components/responses/BalanceError4XX'
        5XX:
          $ref: '#/components/responses/BalanceError5XX'
    get:
      security:
        - Auth:
            - balances:read
            - api:read
      tags:
        - Balances
      operationId: listBalances
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: currency
          in: query
          schema:
            $ref: '#/components/schemas/Currency'
      summary: List all balances
      description: Retrieves all account balances with their current status.
      responses:
        '200':
          description: List of account balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceListResponse'
        4XX:
          $ref: '#/components/responses/BalanceError4XX'
        5XX:
          $ref: '#/components/responses/BalanceError5XX'
  /v1/balances/{id_or_code}:
    get:
      security:
        - Auth:
            - balances:read
            - api:read
      tags:
        - Balances
      operationId: getBalance
      summary: Get balance details
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: id_or_code
          in: path
          required: true
          schema:
            type: string
          description: Balance ID or currency code
      responses:
        '200':
          description: Balance details retrieved successfully
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Balance'
        4XX:
          $ref: '#/components/responses/BalanceError4XX'
        5XX:
          $ref: '#/components/responses/BalanceError5XX'
  /v1/currencies:
    get:
      security:
        - AuthOptional: []
      tags:
        - Currencies
      summary: Retrieve supported currencies
      description: |
        Retrieves a list of all supported currencies along with their basic details. This endpoint can be used to display available currencies in wallets or APIs requiring currency data.
      operationId: listCurrencies
      parameters:
        - $ref: '#/components/parameters/XBuPublicKey'
        - $ref: '#/components/parameters/CurrencyType'
        - $ref: '#/components/parameters/SortQueryParam'
        - name: payments_request
          in: query
          required: false
          schema:
            type: boolean
        - name: ramp
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: A list of supported currencies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrenciesListResponse'
        4XX:
          $ref: '#/components/responses/CurrenciesError4XX'
        5XX:
          $ref: '#/components/responses/CurrenciesError5XX'
  /v1/currencies/{code}:
    get:
      security:
        - AuthOptional: []
      tags:
        - Currencies
      summary: Retrieve details of a specific currency
      description: |
        Fetches detailed information about a specific currency using its unique code. This includes details such as network support, decimal precision, and transaction limits.
      parameters:
        - $ref: '#/components/parameters/CurrencyCodePathParam'
        - $ref: '#/components/parameters/ProfileHeader'
      operationId: getCurrency
      responses:
        '200':
          description: Details of the requested currency.
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Currencies'
        4XX:
          $ref: '#/components/responses/CurrenciesError4XX'
        5XX:
          $ref: '#/components/responses/CurrenciesError5XX'
  /v1/customers:
    post:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Create a new customer
      description: Creates a new customer entry in the system. The required fields depend on the `type` of customer being created ('individual' or 'business').
      operationId: createCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Customer details needed to create a new customer.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
            examples:
              individual_customer:
                summary: Individual Customer
                description: An example of a request payload to create an **individual** customer profile.
                value:
                  email: johninu@busha.co
                  has_accepted_terms: true
                  type: individual
                  country_id: NG
                  phone: '+2348012345678'
                  birth_date: 24-12-1990
                  first_name: John
                  last_name: Doe
                  address:
                    street: 123 Main Street
                    city: Lagos
                    state: Lagos
                    postal_code: '100211'
                    country: NG
              business_customer:
                summary: Business Customer
                description: An example of a request payload to create a **business** customer profile. Note the additional `business_*` fields.
                value:
                  email: johninu@busha.co
                  has_accepted_terms: true
                  type: business
                  country_id: NG
                  phone: '+2348098765432'
                  address:
                    street: 456 Corporate Avenue
                    city: Abuja
                    state: FCT
                    postal_code: '900288'
                    country: NG
                  business_name: ABC Corporation
                  business_industry: BIN_C4UvTYR5V8jsOx5LmwQ
                  business_incorporation_date: '2015-06-15'
      responses:
        '201':
          $ref: '#/components/responses/CustomerResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
    get:
      security:
        - Auth:
            - customers:read
            - api:read
      x-internal: false
      summary: List Customers
      description: List all customers in created for the business
      operationId: listCustomers
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - name: q
          in: query
          x-internal: false
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:100
          schema:
            type: string
            maxLength: 100
            minLength: 3
            example: kay@busha.co
      responses:
        '200':
          $ref: '#/components/responses/CustomerListResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/customers/export:
    get:
      security:
        - Auth:
            - customers:read
            - api:read
      x-internal: false
      summary: Export Customers
      description: Export customers to a csv file
      operationId: exportCustomers
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/SortQueryParam'
        - name: q
          in: query
          x-internal: false
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:100
          schema:
            type: string
            maxLength: 100
            minLength: 3
            example: kay@busha.co
      responses:
        '200':
          description: Successful response
          content:
            text/csv:
              schema:
                type: string
                format: binary
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/customers/{id}:
    get:
      security:
        - Auth:
            - customers:read
            - api:read
      x-internal: false
      summary: Get a customer by ID
      description: Retrieve a specific customer by their unique ID
      operationId: getCustomerByID
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          $ref: '#/components/responses/CustomerResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
    put:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Update a customer
      description: Update the details of an existing customer
      operationId: updateCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Customer details to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
      responses:
        '200':
          $ref: '#/components/responses/CustomerResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
    delete:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Delete a customer
      description: Delete a customer by their unique ID
      operationId: deleteCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '204':
          description: Successfully deleted the customer (No Content)
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/customers/{id}/verify:
    post:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Verify a customer
      description: Verify the identity and information provided by a customer
      operationId: verifyCustomer
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          $ref: '#/components/responses/GeneralResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/customers/{id}/token-share:
    post:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Share customer token
      description: Token sharing.
      operationId: customerTokenShare
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        required: true
        description: JWT token to be shared for the customer
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerTokenShareRequest'
            examples:
              default:
                summary: Token share request
                value:
                  token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      responses:
        '200':
          $ref: '#/components/responses/GeneralResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/customers/{id}/kyc-link:
    post:
      x-rate-limit: 20
      x-internal: false
      security:
        - Auth:
            - customers:write
            - api:write
      summary: Generate KYC link for a customer
      description: Generate a KYC verification link for an individual customer
      operationId: generateCustomerKYCLink
      tags:
        - Customers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          $ref: '#/components/responses/CustomerKYCLinkResponse'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/customers/industries:
    get:
      security:
        - Auth:
            - customers:read
            - api:read
      x-internal: false
      summary: List Business Industries
      description: List all business industries
      operationId: listIndustries
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      tags:
        - Customers
      responses:
        '200':
          $ref: '#/components/responses/CustomerBusinessIndustries'
        4XX:
          $ref: '#/components/responses/CustomerError4XX'
        5XX:
          $ref: '#/components/responses/CustomerError5XX'
  /v1/files:
    post:
      x-rate-limit: 10
      security:
        - Auth:
            - presign_url:write
            - api:write
      tags:
        - Files
      summary: Generate presigned upload URL
      description: Generates a presigned URL for uploading files directly to storage
      operationId: generatePresignedURL
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Request parameters for presigned URL
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PresignedUrlRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresignedUrlResponse'
        4XX:
          $ref: '#/components/responses/FilesError4XX'
        5XX:
          $ref: '#/components/responses/FilesError5XX'
  /v1/insights/transactions/trends:
    get:
      tags:
        - Insights
      summary: Get transaction trends
      description: |
        Returns an inflow/outflow/net cash flow time series for completed transactions in the requested currency, bucketed by the requested interval (UTC). Buckets with no activity are zero-filled.
      operationId: getTransactionTrends
      security:
        - Auth:
            - insights:read
            - api:read
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/InsightsCurrencyQueryParam'
        - $ref: '#/components/parameters/InsightsStartDateQueryParam'
        - $ref: '#/components/parameters/InsightsEndDateQueryParam'
        - $ref: '#/components/parameters/InsightsIntervalQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/TransactionTrends'
        4XX:
          $ref: '#/components/responses/InsightsError4XX'
        5XX:
          $ref: '#/components/responses/InsightsError5XX'
  /v1/insights/transactions/breakdown:
    get:
      tags:
        - Insights
      summary: Get transaction breakdown
      description: |
        Returns transaction counts within the requested date range grouped by the requested dimension, with percentage shares. Currency is optional; when omitted, all currencies are counted.
      operationId: getTransactionBreakdown
      security:
        - Auth:
            - insights:read
            - api:read
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: currency
          in: query
          required: false
          description: Restrict the breakdown to a single currency. Counts all currencies when omitted.
          schema:
            type: string
            example: NGN
            x-oapi-codegen-extra-tags:
              validate: min_len:3|max_len:10
              filter: trim|upper
        - $ref: '#/components/parameters/InsightsStartDateQueryParam'
        - $ref: '#/components/parameters/InsightsEndDateQueryParam'
        - name: group_by
          in: query
          required: false
          description: Dimension to group transactions by. Defaults to status.
          schema:
            $ref: '#/components/schemas/TransactionBreakdownGroupBy'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/TransactionBreakdown'
        4XX:
          $ref: '#/components/responses/InsightsError4XX'
        5XX:
          $ref: '#/components/responses/InsightsError5XX'
  /v1/insights/customers/growth:
    get:
      tags:
        - Insights
      summary: Get customer growth
      description: |
        Returns the business customer growth trend: new and cumulative customer counts per interval bucket (UTC), plus a summary with the growth rate versus the immediately preceding period of equal length.
      operationId: getCustomerGrowth
      security:
        - Auth:
            - insights:read
            - api:read
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/InsightsStartDateQueryParam'
        - $ref: '#/components/parameters/InsightsEndDateQueryParam'
        - $ref: '#/components/parameters/InsightsIntervalQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/CustomerGrowth'
        4XX:
          $ref: '#/components/responses/InsightsError4XX'
        5XX:
          $ref: '#/components/responses/InsightsError5XX'
  /v1/validate:
    post:
      security: []
      x-rate-limit: 5
      tags:
        - Miscellaneous
      summary: Validate payment destination
      description: validates a payment destination is valid
      operationId: validatePaymentDestination
      requestBody:
        description: validate a payment destination
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateDestinationRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateDestinationResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/banks:
    get:
      security: []
      x-rate-limit: 20
      tags:
        - Miscellaneous
      summary: List banks resource
      description: Returns a list of all banks and their bank codes
      operationId: listBanks
      parameters:
        - $ref: '#/components/parameters/CurrencyQueryParam'
        - $ref: '#/components/parameters/CountryQueryParam'
        - name: direct_debit
          in: query
          required: false
          description: Filter by direct debit support
          schema:
            type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBankResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/countries:
    get:
      security: []
      tags:
        - Miscellaneous
      summary: Returns a list of countries
      description: Returns a list of countries and their supported payment channels
      operationId: listCountries
      parameters:
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/CountryQueryParam'
        - $ref: '#/components/parameters/CurrencyQueryParam'
        - $ref: '#/components/parameters/ProfileHeader'
        - name: withdrawal
          in: query
          required: false
          description: Filter countries by withdrawal support
          schema:
            type: boolean
        - name: deposit
          in: query
          required: false
          description: Filter countries by deposit support
          schema:
            type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountriesListResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/pay/{username}:
    get:
      x-rate-limit: 5
      security:
        - Auth: []
      tags:
        - Miscellaneous
      summary: Look up users addresses
      description: Returns a user's addresses based on currency and network
      operationId: lookupUserAddresses
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
          description: Username to lookup addresses for
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:50|ends_with:busha
            filter: trim|lower
        - name: currency
          in: query
          required: true
          description: Filter by currency
          x-oapi-codegen-extra-tags:
            validate: required|min_len:3|max_len:10
          schema:
            type: string
            example: USDT
        - name: networks
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Currency'
          description: Filter addresses by network
          style: form
          explode: false
          x-oapi-codegen-extra-tags:
            filter: slice_upper|slice_trim
        - name: auto_convert_to
          in: query
          required: false
          description: Currency to convert the deposit to
          schema:
            type: string
            example: NGN
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:10
            filter: upper|trim
      responses:
        '200':
          $ref: '#/components/responses/LookupResponses'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/merchants:
    get:
      security: []
      x-internal: false
      tags:
        - Miscellaneous
      summary: Get a merchant by public key
      description: Get a merchant
      operationId: getMerchant
      parameters:
        - $ref: '#/components/parameters/XBuPublicKey'
      responses:
        '200':
          $ref: '#/components/responses/MerchantResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/addresses/{code}:
    get:
      x-rate-limit: 5
      security:
        - Auth:
            - addresses:write
            - api:write
      tags:
        - Miscellaneous
      summary: Get deposit address
      description: Get an address for a currency
      operationId: getDepositAddress
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CurrencyCodePathParam'
      responses:
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/addresses/regenerate:
    post:
      x-rate-limit: 5
      security:
        - Auth:
            - addresses:write
            - api:write
      tags:
        - Miscellaneous
      summary: Regenerate deposit address
      description: Regenerate an address for a network
      operationId: regenerateDepositAddress
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Regenerate deposit address request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegenerateDepositAddressReq'
      responses:
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/virtual_bank_accounts/{code}:
    get:
      x-rate-limit: 30
      security:
        - Auth:
            - virtual_bank_accounts:read
            - api:read
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CurrencyCodePathParam'
        - name: amount
          in: query
          required: false
          description: The amount to calculate fees for
          schema:
            type: string
            example: '100'
      tags:
        - Miscellaneous
      operationId: getVirtualBankAccount
      summary: Get virtual bank account
      description: Get a virtual bank account for a currency
      responses:
        '200':
          $ref: '#/components/responses/VirtualBankAccountResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/virtual_bank_accounts/{code}/terms:
    get:
      x-rate-limit: 10
      security:
        - Auth:
            - virtual_bank_accounts:read
            - api:read
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CurrencyCodePathParam'
      tags:
        - Miscellaneous
      operationId: getVirtualBankAccountTerms
      summary: Get virtual bank account terms
      description: Get the terms and conditions for a virtual bank account by currency code
      responses:
        '200':
          $ref: '#/components/responses/VirtualBankAccountTermsResponse'
        4XX:
          $ref: '#/components/responses/MiscellaneousError4XX'
        5XX:
          $ref: '#/components/responses/MiscellaneousError5XX'
  /v1/pairs:
    get:
      tags:
        - Pairs
      security:
        - AuthOptional: []
      summary: List trading pairs
      description: Retrieves all available trading pairs with their current rates.
      operationId: listPairs
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: id
          in: query
          x-oapi-codegen-extra-tags:
            validate: min_len:4|max_len:20
            filter: trim|upper
          schema:
            type: string
        - name: type
          in: query
          style: form
          explode: false
          description: |
            This filter pairs based on the type. Multiple types can be passed as a comma separated list e.g ?type=fiat,crypto. When multiple types are provided, pairs matching any of them are returned. fiat filter return pairs where the counter currency-type is a fiat crypto filter return pairs where the counter currency type is digital stablecoin filter return pairs where the base or counter currency is a stablecoin base_crypto filter return pairs where the base currency is digital base_fiat filter return pairs where the base currency is a fiat stock filter returns stock pairs
          schema:
            type: array
            items:
              type: string
              enum:
                - fiat
                - stablecoin
                - crypto
                - base_crypto
                - base_fiat
                - stock
        - name: is_business
          in: query
          schema:
            type: boolean
        - name: base
          in: query
          x-oapi-codegen-extra-tags:
            validate: min_len:1|max_len:10
            filter: trim|upper
          schema:
            $ref: '#/components/schemas/Currency'
        - name: counter
          in: query
          x-oapi-codegen-extra-tags:
            validate: min_len:1|max_len:10
            filter: trim|upper
          schema:
            $ref: '#/components/schemas/Currency'
        - name: sort_by
          in: query
          schema:
            type: string
            enum:
              - alphabetical
              - date_added
              - market_cap
              - current_price
              - price_change
              - most_bought
              - most_sold
        - name: price_change_direction
          in: query
          schema:
            type: string
            enum:
              - positive
              - negative
              - absolute
        - $ref: '#/components/parameters/SortQueryParam'
      responses:
        '200':
          description: List of trading pairs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PairsListResponse'
        4XX:
          $ref: '#/components/responses/PairError4XX'
        5XX:
          $ref: '#/components/responses/PairError5XX'
  /v1/payments/links:
    post:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      summary: Create a payment link
      description: Create a payment link
      operationId: createPaymentLink
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentLinkReq'
            examples:
              invoice:
                summary: Create an invoice
                value:
                  type: invoice
                  fixed: true
                  one_time: true
                  name: Invoice for Consulting Services
                  title: Consulting Services - March 2024
                  description: Payment for consulting services rendered
                  target_currency: USDC
                  target_amount: '500.00'
                  customer_email: client@example.com
                  customer_name: John Doe
                  due_date: '2024-04-15T00:00:00Z'
                  note: Thank you for your business!
                  items:
                    - item: Consulting Hours
                      quantity: 10
                      amount: '40.00'
                    - item: Documentation Fee
                      quantity: 1
                      amount: '100.00'
              payment_link:
                summary: Create a payment link
                value:
                  fixed: true
                  one_time: false
                  name: Product Purchase
                  title: Buy Our Product
                  description: Payment for product purchase
                  target_currency: BTC
                  target_amount: '0.01'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
              examples:
                invoice:
                  summary: Invoice created successfully
                  value:
                    status: success
                    message: Payment link created successfully
                    data:
                      id: PAYL_abc123xyz
                      profile_id: PROF_user123
                      type: invoice
                      fixed: true
                      one_time: true
                      link: https://pay.busha.io/charges/PAYL_abc123xyz
                      name: Invoice for Consulting Services
                      title: Consulting Services - March 2024
                      description: Payment for consulting services rendered
                      target_currency: USDC
                      target_amount: '500.00'
                      meta:
                        customer_email: client@example.com
                        customer_name: John Doe
                        due_date: '2024-04-15T00:00:00Z'
                        note: Thank you for your business!
                        items:
                          - item: Consulting Hours
                            quantity: 10
                            amount: '40.00'
                          - item: Documentation Fee
                            quantity: 1
                            amount: '100.00'
                      status: active
                      created_at: '2024-03-10T12:00:00Z'
                      updated_at: '2024-03-10T12:00:00Z'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
    get:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - api:get
            - transfers:get
      summary: List payment links
      description: List payment links
      operationId: listPaymentLink
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - name: q
          in: query
          required: false
          description: Search query for payment links
          schema:
            type: string
        - name: status
          in: query
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PaymentLinkStatus'
        - $ref: '#/components/parameters/PaymentLinkTypeQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaymentLinkListResponse'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
  /v1/payments/links/{id}:
    get:
      tags:
        - PaymentLinks
      security:
        - AuthOptional:
            - api:get
            - transfers:get
      summary: Retrieve a payment link
      description: Retrieve a payment link
      operationId: getPaymentLink
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
    patch:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      operationId: updatePaymentLink
      summary: Update a payment link
      description: Update a payment link
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentLinkReq'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
    delete:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      operationId: deletePaymentLink
      summary: Delete a payment link
      description: Delete a payment link
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
  /v1/payments/links/{id}/requests:
    get:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      operationId: listPaymentLinkRequests
      summary: List payment requests for payment link
      description: List payment requests for payment link
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - name: status
          in: query
          description: Filter by status
          required: false
          schema:
            $ref: '#/components/schemas/PaymentRequestStatus'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CursorPagination'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/PaymentRequest'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
    post:
      tags:
        - PaymentLinks
      security:
        - AuthOptional:
            - transfers:write
            - api:write
      operationId: createPaymentLinkRequest
      summary: Create a payment request for payment link
      description: Create a payment request for payment link
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequestForLinkReq'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentRequest'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
  /v1/payments/links/{id}/activate:
    post:
      tags:
        - PaymentLinks
      security:
        - Auth:
            - transfers:write
            - api:write
      operationId: activateInvoice
      summary: Activate a draft invoice
      description: Transitions an invoice from draft status to active and sends email notification to customer
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Invoice activated successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentLink'
        4XX:
          $ref: '#/components/responses/PaymentLinkError4XX'
        5XX:
          $ref: '#/components/responses/PaymentLinkError5XX'
  /v1/payments/requests:
    post:
      tags:
        - PaymentRequests
      security:
        - AuthOptional:
            - transfers:write
            - api:write
      summary: Create a payment request
      description: Create a payment request
      operationId: createPaymentRequest
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/XBuPublicKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/PaymentRequest'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError5XX'
    get:
      tags:
        - PaymentRequests
      security:
        - Auth:
            - transfers:read
            - api:read
      summary: List payment requests
      description: List payment requests
      operationId: listPaymentRequests
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/PlatformIDInQueryParam'
        - name: q
          in: query
          required: false
          description: Search query for payment requests
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: filter by status
          schema:
            type: string
            description: Payment Status
        - name: asset
          in: query
          required: false
          description: filter by asset
          schema:
            type: array
            description: Payment assets
            items:
              type: string
          style: form
          explode: false
        - name: start_time
          in: query
          required: false
          description: filter by date
          schema:
            type: string
            format: date
            description: Filter by date in ISO 8601 format
            example: '2023-10-01'
        - name: end_time
          in: query
          required: false
          description: filter by date
          schema:
            type: string
            format: date
            description: Filter by date in ISO 8601 format
            example: '2023-10-01'
        - name: type
          in: query
          required: false
          description: filter by type
          schema:
            type: string
            description: Payment Type
            enum:
              - donation
              - checkout
              - invoice
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestListResponse'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError5XX'
  /v1/payments/requests/{id}:
    get:
      security:
        - AuthOptional:
            - transfers:read
            - api:read
      tags:
        - PaymentRequests
      summary: Retrieve a payment request
      description: Retrieve a payment request
      operationId: getPaymentRequest
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/XBuPublicKey'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestResponse'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError5XX'
  /v1/payments/requests/{id}/finalize:
    post:
      tags:
        - PaymentRequests
      security:
        - Auth:
            - transfers:write
            - api:write
      summary: Finalize a payment request
      description: Finalize a payment request
      operationId: finalizePaymentRequest
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinalizePaymentRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequestResponse'
        4XX:
          $ref: '#/components/responses/PaymentRequestError4XX'
        5XX:
          $ref: '#/components/responses/PaymentRequestError5XX'
  /v1/pledges/quotes:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - api:write
            - pledges:write
      tags:
        - Pledges
      summary: Create pledge quote
      description: Preflight a multi-asset pledge lock without moving funds. Requires an OAuth pledge grant with beneficiary context.
      operationId: createPledgeQuote
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Pledge quote request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePledgeQuoteRequest'
      responses:
        '200':
          $ref: '#/components/responses/PledgeQuoteResponse'
        4XX:
          $ref: '#/components/responses/PledgeError4XX'
        5XX:
          $ref: '#/components/responses/PledgeError5XX'
  /v1/pledges:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - api:write
            - pledges:write
      tags:
        - Pledges
      summary: Create pledge
      description: Create a pledge from a valid quote and lock the quoted items. Requires an OAuth pledge grant with beneficiary context.
      operationId: createPledge
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Pledge creation request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePledgeRequest'
      responses:
        '201':
          $ref: '#/components/responses/PledgeResponse'
        4XX:
          $ref: '#/components/responses/PledgeError4XX'
        5XX:
          $ref: '#/components/responses/PledgeError5XX'
    get:
      security:
        - Auth:
            - api:read
            - pledges:read
      tags:
        - Pledges
      summary: List pledges
      description: List pledges visible to the selected profile, or to the authenticated OAuth pledge grant when beneficiary context is present.
      operationId: listPledges
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: status
          in: query
          description: Filter by pledge status
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/PledgeStatus'
        - name: asset
          in: query
          description: Filter by pledged asset
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Currency'
        - name: reference
          in: query
          description: Filter by beneficiary-supplied pledge reference
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
      responses:
        '200':
          $ref: '#/components/responses/PledgeListResponse'
        4XX:
          $ref: '#/components/responses/PledgeError4XX'
        5XX:
          $ref: '#/components/responses/PledgeError5XX'
  /v1/pledges/{id}:
    get:
      security:
        - Auth:
            - api:read
            - pledges:read
      tags:
        - Pledges
      summary: Get pledge
      description: Retrieve pledge state, items, and lifecycle events visible to the selected profile or OAuth pledge grant.
      operationId: getPledge
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/PledgeIDParam'
      responses:
        '200':
          $ref: '#/components/responses/PledgeResponse'
        4XX:
          $ref: '#/components/responses/PledgeError4XX'
        5XX:
          $ref: '#/components/responses/PledgeError5XX'
  /v1/pledges/{id}/activate:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - api:write
            - pledges:write
      tags:
        - Pledges
      summary: Activate pledge
      description: Confirm that the beneficiary credit agreement is active. Requires an OAuth pledge grant with beneficiary context.
      operationId: activatePledge
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/PledgeIDParam'
      requestBody:
        description: Pledge activation request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivatePledgeRequest'
      responses:
        '200':
          $ref: '#/components/responses/PledgeActionResponse'
        4XX:
          $ref: '#/components/responses/PledgeError4XX'
        5XX:
          $ref: '#/components/responses/PledgeError5XX'
  /v1/pledges/{id}/items:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - api:write
            - pledges:write
      tags:
        - Pledges
      summary: Add pledge items
      description: Add more customer-authorized assets to an active pledge. Requires an OAuth pledge grant with beneficiary context.
      operationId: addPledgeItems
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/PledgeIDParam'
      requestBody:
        description: Add pledge items request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddPledgeItemsRequest'
      responses:
        '200':
          $ref: '#/components/responses/AddPledgeItemsResponse'
        4XX:
          $ref: '#/components/responses/PledgeError4XX'
        5XX:
          $ref: '#/components/responses/PledgeError5XX'
  /v1/pledges/{id}/release:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - api:write
            - pledges:write
      tags:
        - Pledges
      summary: Release pledge items
      description: Release all or part of the pledged assets back to the customer. Requires an OAuth pledge grant with beneficiary context.
      operationId: releasePledge
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/PledgeIDParam'
      requestBody:
        description: Pledge release request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReleasePledgeRequest'
      responses:
        '200':
          $ref: '#/components/responses/ReleasePledgeResponse'
        4XX:
          $ref: '#/components/responses/PledgeError4XX'
        5XX:
          $ref: '#/components/responses/PledgeError5XX'
  /v1/pledges/{id}/liquidations:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - api:write
            - pledges:liquidate
      tags:
        - Pledges
      summary: Request pledge liquidation
      description: Request notice-period liquidation under the stored pledge mandate. Requires an OAuth pledge grant with beneficiary context.
      operationId: requestPledgeLiquidation
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/PledgeIDParam'
      requestBody:
        description: Pledge liquidation request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestPledgeLiquidationRequest'
      responses:
        '202':
          $ref: '#/components/responses/PledgeLiquidationResponse'
        4XX:
          $ref: '#/components/responses/PledgeError4XX'
        5XX:
          $ref: '#/components/responses/PledgeError5XX'
  /v1/pledges/{id}/liquidations/{liquidation_id}/cancel:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - api:write
            - pledges:liquidate
      tags:
        - Pledges
      summary: Cancel pledge liquidation
      description: Cancel a pending liquidation before processing starts. Requires an OAuth pledge grant with beneficiary context.
      operationId: cancelPledgeLiquidation
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/PledgeIDParam'
        - $ref: '#/components/parameters/LiquidationIDParam'
      requestBody:
        description: Pledge liquidation cancellation request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelPledgeLiquidationRequest'
      responses:
        '200':
          $ref: '#/components/responses/CancelPledgeLiquidationResponse'
        4XX:
          $ref: '#/components/responses/PledgeError4XX'
        5XX:
          $ref: '#/components/responses/PledgeError5XX'
  /v1/quotes:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - quotes:write
            - api:write
      summary: Create a new Quote
      description: Create Quote
      operationId: createQuote
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/XBuPublicKey'
      requestBody:
        description: Create a new Quote
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuoteRequest'
      responses:
        '201':
          $ref: '#/components/responses/QuoteResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
    get:
      security:
        - Auth:
            - quotes:read
            - api:read
      summary: List Quotes
      description: List Quotes
      operationId: listQuotes
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
      responses:
        '200':
          $ref: '#/components/responses/QuotesListResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
  /v1/quotes/{id}:
    get:
      security:
        - Auth:
            - quotes:read
            - api:read
      summary: Get Quote
      description: Returns a single quote by it's unique ID
      operationId: getQuote
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          $ref: '#/components/responses/QuoteResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
  /v1/quotes/unauthenticated:
    post:
      x-rate-limit: 20
      security: []
      summary: Create Unauthenticated Quotes
      description: Create Unauthenticated Quote
      operationId: unauthenticatedCreateQuote
      tags:
        - Quotes
      requestBody:
        description: Create a unauthenticated Quote
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnauthenticatedCreateQuote'
      responses:
        '201':
          $ref: '#/components/responses/QuoteResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
  /v1/quote/payment_options:
    get:
      security:
        - Auth:
            - quotes:read
            - api:read
      summary: List Payment Options
      description: List Fiat Payment Options
      operationId: listPaymentOptions
      tags:
        - Quotes
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: currency
          in: query
          required: false
          description: The currency to get payment options for.
          schema:
            type: string
            example: USD
        - name: support_conversion
          in: query
          required: false
          description: This shows if the payment options is supported for conversions
          schema:
            type: boolean
        - name: type
          in: query
          required: false
          description: The type of payment options to retrieve.
          schema:
            type: string
            example: withdraw
            enum:
              - withdraw
              - deposit
        - name: amount
          in: query
          required: false
          description: The amount to get payment options for.
          schema:
            type: number
            example: 1500
        - name: purpose
          in: query
          required: false
          description: Filter payment options by intended use case.
          schema:
            type: string
            enum:
              - wallet
              - auto_save
              - auto_buy
              - savings
              - loans
      responses:
        '200':
          $ref: '#/components/responses/PaymentOptionsListResponse'
        4XX:
          $ref: '#/components/responses/QuoteError4XX'
        5XX:
          $ref: '#/components/responses/QuoteError5XX'
  /v1/recipients:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - recipients:write
            - api:write
      tags:
        - Recipients
      operationId: createRecipient
      summary: Create a recipient
      description: Create a new recipient for transfers.
      parameters:
        - $ref: '#/components/parameters/X-BU-Version'
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRecipientRequest'
            examples:
              legacy_response:
                summary: Recipient creation - Legacy
                value:
                  currency_id: NGN
                  country_id: NG
                  type: ngn_bank_transfer
                  legal_entity_type: business
                  fields:
                    - name: bank_name
                      value: Access Bank Nigeria
                    - name: account_number
                      value: '1234567890'
                    - name: bank_code
                      value: '000014'
                    - name: account_name
                      value: John Doe
              ngn:
                summary: Recipient creation NGN (2025-07-11)
                value:
                  currency: NGN
                  country_code: NG
                  type: ngn_bank
                  bank_name: UNITED BANK FOR AFRICA
                  bank_code: '000004'
                  account_number: '2134211381'
                  account_name: John Doe
              usd_ach:
                summary: Recipient creation USD - ACH (2025-07-11)
                value:
                  type: usd_bank
                  entity_type: personal
                  transfer_type: ach
                  account_name: Jane Smith
                  bank_name: Chase Bank
                  routing_number: '021000021'
                  account_number: '9876543210'
              usd_wire:
                summary: Recipient creation USD - Wire (2025-07-11)
                value:
                  type: usd_bank
                  entity_type: business
                  transfer_type: wire
                  account_name: Tech Corp LLC
                  bank_name: Bank of America
                  routing_number: '026009593'
                  account_number: '1122334455'
              usd_swift:
                summary: Recipient creation USD - SWIFT (2025-07-11)
                value:
                  type: usd_bank
                  entity_type: business
                  transfer_type: swift
                  account_name: Global Corp Ltd
                  iban: GB29NWBK60161331926819
                  swift_code: CHASUS33XXX
                  bank_name: Bank of International Transfers
                  recipient_address: 123 Hauptstrasse, Berlin, 10115, Germany
                  intermediary_bank_name: Intermediary Global Bank
                  intermediary_bank_address: 456 Avenue of Banks, Zurich
                  intermediary_swift_code: CHASUS33XXX
              kes:
                summary: Recipient creation MPESA MOBILE MONEY (2025-07-11)
                value:
                  currency: KES
                  country_code: KE
                  type: mpesa_mobile_money
                  phone_number: +254 712345678
                  account_name: Business Account
              kes_business_mobile_money_till:
                summary: Recipient creation BUSINESS MOBILE MONEY - Till (2025-07-11)
                value:
                  currency: KES
                  country_code: KE
                  type: till
                  till_number: '20029'
                  account_name: Busines Name
              kes_business_mobile_money_paybill:
                summary: Recipient creation BUSINESS MOBILE MONEY - Paybill (2025-07-11)
                value:
                  currency: KES
                  country_code: KE
                  type: paybill
                  paybill: '254701548525'
                  account_number: '63902'
                  account_name: Business Account
              crypto_btc:
                summary: Recipient creation BTC (2025-07-11)
                value:
                  type: crypto
                  address_label: My Bitcoin Wallet
                  network: BTC
                  address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
              crypto_usdt_on_eth:
                summary: Recipient creation USDT ON ETH NETWORK (2025-07-11)
                value:
                  type: crypto
                  address_label: My Ethereum Wallet
                  network: ETH
                  address: '0x742d35Cc6543C4532f5D2b8d9a2b2A1234567890'
              crypto_stellar_lumens_with_memo:
                summary: Recipient creation STELLAR LUMENS (2025-07-11)
                value:
                  type: crypto
                  address_label: My Stellar Wallet
                  network: XLM
                  address: GAHK7EEG2WWHVKDNT4CEQFZGKF2LGDSW2IVM4S5DP42RBW3K6BTODB4A
                  memo: '123456789'
      responses:
        '201':
          description: Recipient created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
              examples:
                legacy_response:
                  summary: Recipient response - Legacy
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      object: recipient
                      id: 8014c2ee-c70f-4c72-8d9f-c8b9d708a688
                      user_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                      profile_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                      currency_id: NGN
                      country_id: NG
                      type: ngn_bank_transfer
                      legal_entity_type: business
                      owned_by_customer: true
                      active: true
                      created_at: '2024-05-16T13:06:31.409336+01:00'
                      updated_at: '2024-05-16T13:06:31.409336+01:00'
                      fields:
                        - value: Access Bank Nigeria
                          display_name: Bank Name
                          name: bank_name
                          is_copyable: false
                          is_visible: true
                          required: true
                        - value: '0013246052'
                          display_name: Account Number
                          name: account_number
                          is_copyable: false
                          is_visible: true
                          required: true
                ngn:
                  summary: Recipient response NGN (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 687560e1255ff9424db5e4c5
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: INU JOHN
                      account_number: '2134211381'
                      active: true
                      bank_code: '000004'
                      bank_name: 9 PAYMENT SOLUTIONS BANK
                      category: bank
                      country_code: NG
                      currency: NGN
                      object: recipients
                      owned_by_customer: true
                      type: ngn_bank
                usd_ach:
                  summary: Recipient response USD - ACH (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 687564c9255ff9424db5e4c6
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: Jane Smith
                      account_number: '9876543210'
                      active: true
                      bank_name: Chase Bank
                      category: bank
                      entity_type: personal
                      object: recipients
                      owned_by_customer: true
                      routing_number: '021000021'
                      transfer_type: ach
                      type: usd_bank
                usd_wire:
                  summary: Recipient response USD - WIRE (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 687564c9255ff9424db5e4c7
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: Tech Corp LLC
                      account_number: '1122334455'
                      active: true
                      bank_name: Bank of America
                      category: bank
                      entity_type: business
                      object: recipients
                      owned_by_customer: true
                      routing_number: '026009593'
                      transfer_type: wire
                      type: usd_bank
                usd_swift:
                  summary: Recipient response USD - SWIFT (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756991255ff9424db5e4e0
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: Global Corp Ltd
                      active: true
                      bank_name: Bank of International Transfers
                      category: bank
                      entity_type: business
                      iban: GB29NWBK60161331926819
                      intermediary_bank_address: 456 Avenue of Banks, Zurich
                      intermediary_bank_name: Intermediary Global Bank
                      intermediary_swift_code: CHASUS33XXX
                      object: recipients
                      owned_by_customer: true
                      recipient_address: 123 Hauptstrasse, Berlin, 10115, Germany
                      swift_code: CHASUS33XXX
                      transfer_type: swift
                      type: usd_bank
                kes:
                  summary: Recipient response MPESA MOBILE MONEY (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756bbc255ff9424db5e4e2
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: Samuel Kiprotich
                      active: true
                      category: mpesa_mobile_money
                      country_code: KE
                      currency: KES
                      object: recipients
                      owned_by_customer: true
                      phone_number: +254 712345678
                      type: mpesa_mobile_money
                kes_business_mobile_money_till:
                  summary: Recipient response BUSINESS MOBILE MONEY - Till (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 6984a536631abd8caf69cf45
                      profile_id: 01b044c7-dff6-464c-9792-f49b3c3c02c3
                      account_name: Account Name
                      active: true
                      category: mobile_money
                      country_code: KE
                      currency: KES
                      object: recipients
                      owned_by_customer: true
                      paybill: '20029'
                      type: paybill
                kes_business_mobile_money_paybill:
                  summary: Recipient response BUSINESS MOBILE MONEY - Paybill (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 6984a536631abd8caf69cf45
                      profile_id: 01b044c7-dff6-464c-9792-f49b3c3c02c3
                      account_name: Samuel Kiprotich
                      account_number: '63902'
                      active: true
                      category: mobile_money
                      country_code: KE
                      currency: KES
                      object: recipients
                      owned_by_customer: true
                      paybill: '254701548525'
                      type: paybill
                crypto_btc:
                  summary: Recipient response BTC (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756cd6255ff9424db5e4e3
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      active: true
                      address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
                      address_label: My Bitcoin Wallet
                      category: crypto
                      network: BTC
                      object: recipients
                      owned_by_customer: true
                      type: crypto
                crypto_usdt_on_eth:
                  summary: Recipient response USDT ON ETH NETWORK (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756df6255ff9424db5e4e5
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      active: true
                      address: '0x742d35Cc6543C4532f5D2b8d9a2b2A1234567890'
                      address_label: My Ethereum Wallet
                      category: crypto
                      network: ETH
                      object: recipients
                      owned_by_customer: true
                      type: crypto
                crypto_stellar_lumens_with_memo:
                  summary: Recipient response STELLAR LUMENS (2025-07-11)
                  value:
                    status: success
                    message: Recipient created successfully
                    data:
                      id: 68756eb4255ff9424db5e4e7
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      active: true
                      address: GAHK7EEG2WWHVKDNT4CEQFZGKF2LGDSW2IVM4S5DP42RBW3K6BTODB4A
                      address_label: My Stellar Wallet
                      category: crypto
                      memo: '123456789'
                      network: XLM
                      object: recipients
                      owned_by_customer: true
                      type: crypto
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
    get:
      security:
        - Auth:
            - recipients:read
            - api:read
      tags:
        - Recipients
      operationId: listRecipients
      summary: List recipients
      description: Retrieve a list of all recipients
      parameters:
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/CurrencyQueryParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/CountryQueryParam'
        - $ref: '#/components/parameters/X-BU-Version'
        - $ref: '#/components/parameters/ProfileHeader'
        - name: network
          in: query
          description: Filter by recipient network
          required: false
          schema:
            type: array
            items:
              type: string
          style: form
          explode: false
        - name: category
          in: query
          description: Filter by recipient category
          required: false
          schema:
            type: string
        - name: type
          in: query
          description: Filter recipient by the type
          required: false
          schema:
            type: array
            items:
              type: string
              x-oapi-codegen-extra-tags:
                validate: nanoid
          style: form
          explode: false
        - name: phone_number
          in: query
          description: Filter recipients by phone number
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: account_number
          in: query
          description: Filter recipients by account number
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: username
          in: query
          description: Filter recipients by username
          required: false
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Recipients retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientListResponse'
              examples:
                legacy_response:
                  summary: Recipient list response - Legacy
                  value:
                    status: success
                    message: Recipients retrieved successfully
                    data:
                      - object: recipient
                        id: 8014c2ee-c70f-4c72-8d9f-c8b9d708a688
                        user_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                        profile_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                        currency_id: NGN
                        country_id: NG
                        type: ngn_bank_transfer
                        legal_entity_type: business
                        owned_by_customer: true
                        active: true
                        created_at: '2024-05-16T13:06:31.409336+01:00'
                        updated_at: '2024-05-16T13:06:31.409336+01:00'
                        fields:
                          - value: Access Bank Nigeria
                            display_name: Bank Name
                            name: bank_name
                            is_copyable: false
                            is_visible: true
                            required: true
                          - value: '0013246052'
                            display_name: Account Number
                            name: account_number
                            is_copyable: false
                            is_visible: true
                            required: true
                response_2025_07_11:
                  summary: Recipient list response (2025-07-11)
                  value:
                    status: success
                    message: Recipients retrieved successfully
                    pagination:
                      next_cursor: MjAyNC0xMC0xNVQxMTowNTo1My45NTkxNDErMDE6MDA=
                      current_entries_size: 20
                      previous_cursor: MjAyNC0xMC0xNVQxMTowNTo1My45NTkxNDErMDE6MDA=
                    data:
                      - id: 68756eb4255ff9424db5e4e7
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        active: true
                        address: GAHK7EEG2WWHVKDNT4CEQFZGKF2LGDSW2IVM4S5DP42RBW3K6BTODB4A
                        category: crypto
                        memo: '123456789'
                        network: XLM
                        object: recipients
                        owned_by_customer: true
                        type: crypto
                      - id: 68756bbc255ff9424db5e4e2
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        account_name: Samuel Kiprotich
                        active: true
                        category: mpesa_mobile_money
                        country_code: KE
                        currency: KES
                        object: recipients
                        owned_by_customer: true
                        phone_number: +254 712345678
                        type: mpesa_mobile_money
                      - id: 68756991255ff9424db5e4e0
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        account_name: Global Corp Ltd
                        active: true
                        bank_name: Bank of International Transfers
                        category: bank
                        entity_type: business
                        iban: GB29NWBK60161331926819
                        intermediary_bank_address: 456 Avenue of Banks, Zurich
                        intermediary_bank_name: Intermediary Global Bank
                        intermediary_swift_code: CHASUS33XXX
                        object: recipients
                        owned_by_customer: true
                        recipient_address: 123 Hauptstrasse, Berlin, 10115, Germany
                        swift_code: CHASUS33XXX
                        transfer_type: swift
                        type: usd_bank
                      - id: 687564c9255ff9424db5e4c6
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        account_name: Jane Smith
                        account_number: '9876543210'
                        active: true
                        bank_name: Chase Bank
                        category: bank
                        entity_type: personal
                        object: recipients
                        owned_by_customer: true
                        routing_number: '021000021'
                        transfer_type: ach
                        type: usd_bank
                      - id: 687560e1255ff9424db5e4c5
                        profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                        account_name: INU JOHN OSHIOGIEMHE
                        account_number: '2134211381'
                        active: true
                        bank_code: '000004'
                        bank_name: 9 PAYMENT SOLUTIONS BANK
                        category: bank
                        country_code: NG
                        currency: NGN
                        object: recipients
                        owned_by_customer: true
                        type: ngn_bank
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
  /v1/recipients/{id}:
    get:
      security:
        - Auth:
            - recipients:read
            - api:read
      tags:
        - Recipients
      summary: Retrieve a recipient
      description: Get details of a specific recipient
      operationId: getRecipient
      parameters:
        - $ref: '#/components/parameters/PathParamUUID'
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/X-BU-Version'
      responses:
        '200':
          description: Recipient retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecipientResponse'
              examples:
                legacy_response:
                  summary: Recipient response - Legacy
                  value:
                    status: success
                    message: Recipient retrieved successfully
                    data:
                      object: recipient
                      id: 8014c2ee-c70f-4c72-8d9f-c8b9d708a688
                      user_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                      profile_id: b8277d1c-1bde-46ef-92ce-ebb4752eede5
                      currency_id: NGN
                      country_id: NG
                      type: ngn_bank
                      legal_entity_type: personal
                      owned_by_customer: true
                      active: true
                      created_at: '2024-05-16T13:06:31.409336+01:00'
                      updated_at: '2024-05-16T13:06:31.409336+01:00'
                      fields:
                        - value: Access Bank Nigeria
                          display_name: Bank Name
                          name: bank_name
                          is_copyable: false
                          is_visible: true
                          required: true
                        - value: '0013246052'
                          display_name: Account Number
                          name: account_number
                          is_copyable: false
                          is_visible: true
                          required: true
                response_2025_07_11:
                  summary: Recipient response (2025-07-11)
                  value:
                    status: success
                    message: Recipient retrieved successfully
                    data:
                      id: 687560e1255ff9424db5e4c5
                      profile_id: aa909417-099c-429a-9d74-89e9b5e8891c
                      account_name: INU JOHN OSHIOGIEMHE
                      account_number: '2134211381'
                      active: true
                      bank_code: '000004'
                      bank_name: 9 PAYMENT SOLUTIONS BANK
                      category: bank
                      country_code: NG
                      currency: NGN
                      object: recipients
                      owned_by_customer: true
                      type: ngn_bank
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
    delete:
      security:
        - Auth:
            - recipients:read
            - api:read
      tags:
        - Recipients
      summary: Delete a recipient
      description: Delete a specific recipient
      operationId: deleteRecipient
      parameters:
        - $ref: '#/components/parameters/PathParamUUID'
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/X-BU-Version'
      responses:
        '204':
          description: Recipient deleted successfully
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
  /v1/recipients/resolve-bank-account:
    post:
      security:
        - Auth:
            - recipients:write
            - api:write
      tags:
        - Recipients
      operationId: resolveBankAccount
      x-rate-limit: 5
      summary: Resolves a bank account
      description: Resolves a bank account for bank transfers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveBankAccountRequest'
      responses:
        '201':
          description: Recipient created successfully
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ResolveBankAccountResp'
        4XX:
          $ref: '#/components/responses/RecipientError4XX'
        5XX:
          $ref: '#/components/responses/RecipientError5XX'
  /v1/stocks:
    get:
      security:
        - AuthOptional: []
      tags:
        - Stocks
      summary: List stocks
      operationId: listStocks
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: q
          in: query
          schema:
            type: string
          x-oapi-codegen-extra-tags:
            filter: trim
        - name: sector
          in: query
          schema:
            type: string
        - name: type
          in: query
          schema:
            type: string
            enum:
              - stock
              - etf
        - name: weekend_enabled
          in: query
          schema:
            type: boolean
        - name: tradeable
          in: query
          description: Filter stocks by whether trading is enabled for the symbol.
          schema:
            type: boolean
        - name: following
          in: query
          description: |
            Restrict results to the authenticated profile's watchlist. Authed only: an unauthenticated request with following=true returns an empty list rather than an error.
          schema:
            type: boolean
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
      responses:
        '200':
          description: A list of stocks.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CursorPagination'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Stock'
        4XX:
          $ref: '#/components/responses/StocksError4XX'
        5XX:
          $ref: '#/components/responses/StocksError5XX'
  /v1/stocks/market-status:
    get:
      security:
        - AuthOptional: []
      tags:
        - Stocks
      summary: Market status
      operationId: getStocksMarketStatus
      responses:
        '200':
          description: Whether the US tokenized-equities venue is open.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/MarketStatus'
        4XX:
          $ref: '#/components/responses/StocksError4XX'
        5XX:
          $ref: '#/components/responses/StocksError5XX'
  /v1/stocks/movers:
    get:
      security:
        - AuthOptional: []
      tags:
        - Stocks
      summary: Top movers
      description: |
        Top gainers and losers by 24h percent change over listed symbols with a fresh enough price to rank.
      operationId: getStocksMovers
      parameters:
        - name: limit
          in: query
          description: Max entries per list (gainers and losers each). Default 6, max 20.
          schema:
            type: integer
            default: 6
            maximum: 20
      responses:
        '200':
          description: Top gainers and losers.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/StockMovers'
        4XX:
          $ref: '#/components/responses/StocksError4XX'
        5XX:
          $ref: '#/components/responses/StocksError5XX'
  /v1/stocks/portfolio:
    get:
      security:
        - Auth:
            - stocks:read
            - api:read
      tags:
        - Stocks
      summary: Stock holdings
      description: |
        Every open stock position for the authenticated profile, valued at the current display (mid) token price. The spread is what a trade costs, not part of what is owned, so it is not applied here.
      operationId: getStocksPortfolio
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Stock holdings and totals.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/StockPortfolio'
        4XX:
          $ref: '#/components/responses/StocksError4XX'
        5XX:
          $ref: '#/components/responses/StocksError5XX'
  /v1/stocks/portfolio/{symbol}:
    get:
      security:
        - Auth:
            - stocks:read
            - api:read
      tags:
        - Stocks
      summary: Stock position detail
      description: |
        One position for the authenticated profile plus a page of the fills behind it, newest first.
      operationId: getStocksPosition
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - $ref: '#/components/parameters/StockSymbolPathParam'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
      responses:
        '200':
          description: Position detail with recent activity.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CursorPagination'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/StockPositionDetail'
        4XX:
          $ref: '#/components/responses/StocksError4XX'
        5XX:
          $ref: '#/components/responses/StocksError5XX'
  /v1/stocks/activities:
    get:
      security:
        - Auth:
            - stocks:read
            - api:read
      tags:
        - Stocks
      summary: Stock activity
      description: |
        A page of the authenticated profile's stock fills (buys and sells) across every symbol, newest first. Optionally narrowed to one action and/or a set of symbols.
      operationId: getStocksActivities
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: action
          in: query
          description: Restrict the page to one action; omit for both.
          schema:
            type: string
            enum:
              - buy
              - sell
        - name: symbols
          in: query
          style: form
          explode: false
          description: Restrict the page to comma-separated display tickers (e.g. AAPL,TSLA).
          schema:
            type: array
            items:
              type: string
              example: AAPL
          x-oapi-codegen-extra-tags:
            filter: slice_trim|slice_upper
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
      responses:
        '200':
          description: A page of stock activity, newest first.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CursorPagination'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/StockActivity'
        4XX:
          $ref: '#/components/responses/StocksError4XX'
        5XX:
          $ref: '#/components/responses/StocksError5XX'
  /v1/stocks/{symbol}:
    get:
      security:
        - AuthOptional: []
      tags:
        - Stocks
      summary: Stock detail
      operationId: getStock
      parameters:
        - $ref: '#/components/parameters/StockSymbolPathParam'
      responses:
        '200':
          description: Stock detail.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/StockDetail'
        4XX:
          $ref: '#/components/responses/StocksError4XX'
        5XX:
          $ref: '#/components/responses/StocksError5XX'
  /v1/stocks/{symbol}/ohlc:
    get:
      security:
        - AuthOptional: []
      tags:
        - Stocks
      summary: Stock OHLC candles
      operationId: getStockOHLC
      parameters:
        - $ref: '#/components/parameters/StockSymbolPathParam'
        - name: period
          in: query
          required: false
          schema:
            type: string
            enum:
              - 1d
              - 1w
              - 1m
              - 1y
              - all
            default: 1d
      responses:
        '200':
          description: Candle series (token-price series).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/StockOHLC'
        4XX:
          $ref: '#/components/responses/StocksError4XX'
        5XX:
          $ref: '#/components/responses/StocksError5XX'
  /v1/transactions:
    get:
      security:
        - Auth:
            - transactions:read
            - api:read
      tags:
        - Transactions
      description: Returns a list of transactions
      operationId: listTransactions
      summary: List transactions
      parameters:
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/CurrencyQueryParam'
        - name: is_fiat
          in: query
          description: Filter by fiat currencies
          required: false
          schema:
            type: boolean
        - name: is_credit
          in: query
          description: Filter by transactions that are credit
          required: false
          schema:
            type: boolean
        - name: type
          in: query
          description: Filter transactions by type
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TransactionTypes'
          style: form
          explode: false
        - name: status
          in: query
          description: Filter transactions by status, comma-separated to match any of them.
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/TransactionStatus'
          style: form
          explode: false
          example: completed,pending
        - name: start_date
          in: query
          description: Filter transactions created on or after this date (inclusive, UTC)
          required: false
          schema:
            type: string
            format: date
          example: '2022-01-01'
        - name: end_date
          in: query
          description: Filter transactions created on or before this date (inclusive, UTC)
          required: false
          schema:
            type: string
            format: date
          example: '2022-01-31'
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/LimitQueryParam'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsListResponse'
        4XX:
          $ref: '#/components/responses/TransactionsError4XX'
        5XX:
          $ref: '#/components/responses/TransactionsError5XX'
  /v1/transactions/{id}:
    get:
      security:
        - Auth:
            - transactions:read
            - api:read
      tags:
        - Transactions
      description: Retrieves a transactions
      operationId: getTransaction
      summary: Get transaction
      parameters:
        - $ref: '#/components/parameters/PathParamUUID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                required:
                  - data
                allOf:
                  - $ref: '#/components/schemas/BaseSchema'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/Transaction'
        4XX:
          $ref: '#/components/responses/TransactionsError4XX'
        5XX:
          $ref: '#/components/responses/TransactionsError5XX'
  /v1/transfers:
    post:
      x-rate-limit: 20
      security:
        - Auth:
            - transfers:write
            - api:write
      summary: Create transfer
      description: Create a transfer object
      operationId: createTransfer
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
      requestBody:
        description: Transfer Request Body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTransferRequest'
      responses:
        '201':
          $ref: '#/components/responses/TransferResponse'
        4XX:
          $ref: '#/components/responses/TransferError4XX'
        5XX:
          $ref: '#/components/responses/TransferError5XX'
    get:
      security:
        - Auth:
            - transfers:read
            - api:read
      summary: List transfers
      description: Gets all transfers
      operationId: listTransfer
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/ProfileHeader'
        - name: id
          in: query
          description: Filter by ID
          required: false
          schema:
            type: string
        - name: quote_id
          in: query
          description: Filter by quote ID
          required: false
          schema:
            $ref: '#/components/schemas/NanoID'
        - name: reference
          in: query
          description: Filter transfers by one or more reference values
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: start_date
          in: query
          description: Filter by start date
          required: false
          schema:
            type: string
            format: date
          example: '2022-01-01'
        - name: end_date
          in: query
          description: Filter by end date
          required: false
          schema:
            type: string
            format: date
          example: '2022-01-01'
        - name: source_currency
          in: query
          description: Filter by source_currency code
          required: false
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:10
            filter: trim|upper
          schema:
            type: string
        - name: target_currency
          in: query
          description: Filter by target_currency code
          required: false
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:10
            filter: trim|upper
          schema:
            type: string
        - $ref: '#/components/parameters/StatusQueryParam'
        - name: referred
          in: query
          description: Specify whether to get referred transfers or not
          required: false
          schema:
            type: boolean
        - name: includes_step
          in: query
          description: Filter transfers that include a specific step in their flow.
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum:
                - deposit
                - withdrawal
                - conversion
                - no_deposit
                - no_withdrawal
                - no_conversion
        - $ref: '#/components/parameters/CursorQueryParams'
        - $ref: '#/components/parameters/SortQueryParam'
        - $ref: '#/components/parameters/LimitQueryParam'
      responses:
        '200':
          $ref: '#/components/responses/TransferListResponse'
        4XX:
          $ref: '#/components/responses/TransferError4XX'
        5XX:
          $ref: '#/components/responses/TransferError5XX'
  /v1/transfers/{id}:
    get:
      security:
        - Auth:
            - transfers:read
            - api:read
      summary: Get transfer
      description: Retrieves a transfer
      operationId: getTransfer
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/PathParamNanoID'
        - $ref: '#/components/parameters/ProfileHeader'
      responses:
        '200':
          $ref: '#/components/responses/TransferResponse'
        4XX:
          $ref: '#/components/responses/TransferError4XX'
        5XX:
          $ref: '#/components/responses/TransferError5XX'
components:
  securitySchemes:
    Auth:
      type: http
      scheme: bearer
      description: Bearer Authentication
    AuthOptional:
      type: http
      scheme: bearer
      description: Bearer Authentication
  schemas:
    Currency:
      type: string
      x-order: 20
      example: BTC
      format: string
      maxLength: 10
      minLength: 1
      description: A valid currency
      x-oapi-codegen-extra-tags:
        validate: required|min_len:1|max_len:10
        filter: trim|upper
    BaseSchema:
      description: General response Values
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          x-order: 1
          x-go-type: string
          enum:
            - success
            - error
          example: success
        message:
          type: string
          x-order: 2
          example: message for success
    CursorPagination:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - pagination
          properties:
            pagination:
              type: object
              required:
                - current_entries_size
              properties:
                next_cursor:
                  type: string
                  example: MjAyNC0xMC0xNVQxMTowNTo1My45NTkxNDErMDE6MDA=
                current_entries_size:
                  type: integer
                  example: 20
                previous_cursor:
                  type: string
                  example: MjAyNC0xMC0xNVQxMDowNTo1My45NTIxQjE3MDE6MDA=
    ResourceUUID:
      type: string
      x-order: 1
      example: 550e8400-e29b-41d4-a716-446655440000
      format: uuid
      description: A valid UUID
      x-oapi-codegen-extra-tags:
        validate: required|uuid
      x-go-type: uuid.UUID
      x-go-type-import:
        path: github.com/gofrs/uuid
        name: uuid
    ID:
      type: string
      x-order: 4
      example: platform_123456
      format: nanoid
      description: A valid id that supports uuid and nanoid
      x-oapi-codegen-extra-tags:
        validate: required|nanoid|string
    Decimal:
      type: string
      description: decimal value
      example: '100'
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
        name: decimal
    AmountWithCurrency:
      type: object
      description: Amount with currency
      required:
        - amount
        - currency
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        currency:
          $ref: '#/components/schemas/Currency'
    Amount:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        fiat:
          $ref: '#/components/schemas/AmountWithCurrency'
        crypto:
          $ref: '#/components/schemas/AmountWithCurrency'
        currency:
          $ref: '#/components/schemas/Currency'
    Balance:
      type: object
      required:
        - id
        - currency
        - name
        - type
        - pending
        - available
        - savings
        - investments
        - total
        - user_id
        - profile_id
      properties:
        id:
          $ref: '#/components/schemas/ResourceUUID'
        user_id:
          $ref: '#/components/schemas/ID'
        profile_id:
          $ref: '#/components/schemas/ID'
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 6
        name:
          type: string
          x-order: 7
          example: Bitcoin
        type:
          type: string
          x-order: 8
          enum:
            - fiat
            - crypto
          example: crypto
        pending:
          $ref: '#/components/schemas/Amount'
        available:
          $ref: '#/components/schemas/Amount'
        savings:
          $ref: '#/components/schemas/Amount'
        investments:
          $ref: '#/components/schemas/Amount'
        total:
          $ref: '#/components/schemas/Amount'
    BalanceListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Balance'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - name
            - message
          properties:
            name:
              type: string
              x-order: 40
              example: bad_request
            message:
              type: string
              example: Invalid Request
        fields:
          type: object
        schema:
          type: array
          items:
            type: object
      example:
        error:
          name: bad_request
          message: Invalid Request
    CreateBalanceRequest:
      type: object
      required:
        - currency
      properties:
        currency:
          $ref: '#/components/schemas/Currency'
    UrlField:
      type: string
      example: https://example.com
      format: url
      description: A valid url
      x-oapi-codegen-extra-tags:
        validate: required|url
    AddressRegexField:
      type: string
      example: ^0x[a-fA-F0-9]{40}$
      format: address
      x-oapi-codegen-extra-tags:
        validate: required|regex
    Network:
      type: object
      required:
        - id
        - name
        - status
        - deposit
        - withdrawal
      properties:
        id:
          type: string
          x-order: 1
          example: ethereum
          description: The unique identifier for the blockchain network.
        name:
          type: string
          example: Ethereum
          description: The descriptive name of the network.
        status:
          type: string
          example: active
          description: The current operational status of the network.
        withdrawal:
          type: boolean
          description: Indicates if withdrawals are supported for this network.
        deposit:
          type: boolean
          description: Indicates if deposits are supported for this network.
        transaction_link:
          $ref: '#/components/schemas/UrlField'
        address_link:
          $ref: '#/components/schemas/UrlField'
        max_withdrawal_amount:
          type: string
          example: '100.00'
          description: Maximum withdrawal amount for this network in the currency.
        min_withdrawal_amount:
          type: string
          example: '0.01'
          description: Minimum withdrawal amount for this network in the currency.
        min_deposit_amount:
          type: string
          example: '0.001'
          description: Minimum deposit amount for this network in the currency.
        confirmations_required:
          type: string
          example: '12'
          description: Number of confirmations required for deposits to be recognized.
        network:
          type: string
          example: ETH
          description: The blockchain network for the currency.
        withdrawal_fee:
          type: string
          example: '0.0001'
          description: The withdrawal fee for the network in the currency.
        address_regex:
          $ref: '#/components/schemas/AddressRegexField'
        testnet_address_regex:
          $ref: '#/components/schemas/AddressRegexField'
        contract_address:
          type: string
          example: '0xdac17f958d2ee523a2206206994597c13d831ec7'
          description: The contract address for tokens on this network.
        is_ramp_sell_supported:
          type: boolean
          description: Indicates if ramp sell is supported for this currency.
          example: true
        is_ramp_buy_supported:
          type: boolean
          description: Indicates if ramp buy is supported for this currency.
          example: true
    Currencies:
      type: object
      required:
        - name
        - code
        - decimals
        - display_name
        - type
        - is_ramp_buy_supported
        - is_ramp_sell_supported
        - precision
        - default_network
        - supported_networks
        - withdrawal
        - deposit
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 1
        description:
          type: string
          description: Extra information about the currency
        name:
          type: string
          x-order: 5
          example: Bitcoin
          description: The official name of the cryptocurrency.
        display_name:
          type: string
          x-order: 6
          example: Bitcoin (BTC)
          description: The formatted display name of the cryptocurrency.
        type:
          type: string
          x-order: 7
          enum:
            - fiat
            - crypto
            - stablecoin
          description: Indicates whether the cryptocurrency is a stablecoin.
        decimals:
          type: string
          x-order: 8
          example: '8'
          description: |
            The number of decimal places supported by the blockchain. Defines how the currency value is divided.
        default_network:
          type: string
          x-order: 9
          description: The identifier of the default network for this currency.
          example: ethereum
        deposit:
          type: boolean
          x-order: 10
          description: Indicates if deposits are supported for this currency.
        icon:
          allOf:
            - $ref: '#/components/schemas/UrlField'
          x-order: 11
        withdrawal:
          type: boolean
          x-order: 12
          description: Indicates if withdrawals are supported for this currency.
        precision:
          type: string
          x-order: 13
          example: '8'
          description: |
            The level of precision supported by this service. This may differ from blockchain-level precision in some cases.
        supported_networks:
          type: array
          x-order: 14
          description: A list of networks supported by the currency, including details for each.
          items:
            $ref: '#/components/schemas/Network'
        is_ramp_sell_supported:
          type: boolean
          x-order: 15
          description: Indicates if ramp sell is supported for this currency.
          example: true
        is_ramp_buy_supported:
          type: boolean
          x-order: 16
          description: Indicates if ramp buy is supported for this currency.
          example: true
        maximum_ramp_buy:
          type: string
          x-order: 17
          description: The maximum amount that can be purchased through the ramp process for this currency.
          example: '1000'
        maximum_ramp_sell:
          type: string
          x-order: 18
          description: The maximum amount that can be sold through the ramp process for this currency.
          example: '1000'
    CurrenciesListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Currencies'
    NameField:
      type: string
      example: John
      description: A valid name
    NullableNameField:
      type: string
      nullable: true
      description: A field representing a name that can be null or absent.
      example: Smith
    CustomerCreateIndividual:
      type: object
      x-order: 2
      required:
        - first_name
        - last_name
      description: Individual name requirements
      properties:
        first_name:
          $ref: '#/components/schemas/NameField'
        middle_name:
          $ref: '#/components/schemas/NullableNameField'
        last_name:
          $ref: '#/components/schemas/NameField'
    CustomerBusinessBase:
      type: object
      required:
        - business_name
        - business_industry
        - business_incorporation_date
      description: Business name requirements
      x-order: 2
      properties:
        business_name:
          type: string
          description: Name of the business
          maxLength: 100
          x-oapi-codegen-extra-tags:
            validate: required|maxlen:100
            filter: trim|lower|ucFirst
        business_industry:
          type: string
          minLength: 16
          maxLength: 24
          description: ID Industry or sector the business operates in
        business_incorporation_date:
          type: string
          format: date
          description: Business incorporation date
    NanoID:
      type: string
      x-order: 2
      example: bus_123456789
      format: nanoid
      description: A valid id
      x-oapi-codegen-extra-tags:
        validate: required|nanoid
    EmailField:
      type: string
      example: bCnW7@example.com
      format: email
      description: A valid email address
      x-oapi-codegen-extra-tags:
        validate: required|email|check_temp_email
        filter: trim|lower
      x-go-type: string
    CountryID:
      type: string
      example: NG
      format: alpha2
      description: A valid country id
      minLength: 2
      maxLength: 2
      x-oapi-codegen-extra-tags:
        validate: alpha2
    BusinessCustomerType:
      type: string
      enum:
        - individual
        - business
    PhoneField:
      type: string
      example: '+2348012345678'
      format: phone
      description: A valid phone number. format `{{calling_code}}{{number}}`
      x-oapi-codegen-extra-tags:
        validate: phone
        filter: phone
        mapstructure: phone_number,omitempty
    Address:
      type: object
      description: Address of the business.
      required:
        - address_line_1
        - country_id
      properties:
        city:
          type: string
          example: Lekki
          x-oapi-codegen-extra-tags:
            mapstructure: city
        state:
          type: string
          example: Lagos
          x-oapi-codegen-extra-tags:
            mapstructure: state
        county:
          type: string
          example: Mombasa
          x-oapi-codegen-extra-tags:
            mapstructure: county
        country_id:
          type: string
          example: NG
          format: alpha2
          description: A valid country id
          x-oapi-codegen-extra-tags:
            validate: alpha2
            mapstructure: country_id
        address_line_1:
          type: string
          example: RT Lawal
          x-oapi-codegen-extra-tags:
            mapstructure: address_line_1
        address_line_2:
          type: string
          example: ''
          x-oapi-codegen-extra-tags:
            mapstructure: address_line_2
        province:
          type: string
          example: province
          x-oapi-codegen-extra-tags:
            mapstructure: province
        postal_code:
          type: string
          example: '12345'
          x-oapi-codegen-extra-tags:
            mapstructure: postal_code
    Customer:
      allOf:
        - oneOf:
            - $ref: '#/components/schemas/CustomerCreateIndividual'
            - $ref: '#/components/schemas/CustomerBusinessBase'
        - type: object
          x-order: 1
          required:
            - id
            - status
            - type
            - email
            - country_id
            - business_id
            - has_accepted_terms_of_service
            - display_currency
            - deposit
            - payout
            - phone
            - address
            - level
            - created_at
            - updated_at
          properties:
            id:
              allOf:
                - $ref: '#/components/schemas/NanoID'
              x-order: 1
            business_id:
              allOf:
                - $ref: '#/components/schemas/NanoID'
              x-order: 2
            email:
              allOf:
                - $ref: '#/components/schemas/EmailField'
              x-order: 3
            status:
              type: string
              enum:
                - active
                - inactive
                - submitted
                - awaiting_review
                - in_review
                - rejected
                - archived
              x-order: 9
            kyc_status:
              type: string
              enum:
                - pending
                - unverified
                - verified
                - expiry_soon
                - expired
              x-order: 9
            country_id:
              $ref: '#/components/schemas/CountryID'
            type:
              allOf:
                - $ref: '#/components/schemas/BusinessCustomerType'
              x-order: 8
            phone:
              allOf:
                - $ref: '#/components/schemas/PhoneField'
              x-order: 8
            address:
              allOf:
                - $ref: '#/components/schemas/Address'
              x-order: 7
            display_currency:
              allOf:
                - $ref: '#/components/schemas/Currency'
              x-order: 7
            deposit:
              type: boolean
              description: User can deposit
              x-order: 8
            payout:
              type: boolean
              description: User can payout
              x-order: 8
            has_accepted_terms_of_service:
              type: boolean
              x-order: 10
            rejection_reasons:
              type: array
              items:
                type: string
              x-order: 11
            requirements_due:
              type: array
              items:
                type: string
              x-order: 12
            future_requirements_due:
              type: array
              items:
                type: string
              x-order: 13
            beneficial_owners:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    $ref: '#/components/schemas/EmailField'
              x-order: 14
            level:
              type: string
              x-order: 15
            created_at:
              type: string
              format: date-time
              x-order: 16
            updated_at:
              type: string
              format: date-time
              x-order: 17
    CustomerIdentifyingInformation:
      type: object
      required:
        - type
        - number
        - country
      description: Contains identification document details and related images for customer verification
      properties:
        type:
          type: string
          enum:
            - passport
            - national-id
            - drivers-license
            - selfie_video
            - selfie
            - bvn
          description: The category of identification document provided by the customer
        number:
          type: string
          maxLength: 50
          description: The unique identifier or serial number on the identification document
        country:
          $ref: '#/components/schemas/CountryID'
        expiry_date:
          type: string
          format: date
          description: The date when the identification document becomes invalid or expires
        image_front:
          type: string
          format: base64
          description: URL or Base64 encoded image of the front side of the identification document. The maximum file size is 4MB.
        image_back:
          type: string
          format: base64
          description: URL or Base64 encoded image of the reverse side of the identification document. The maximum file size is 4MB.
    CustomerDocument:
      type: object
      required:
        - purposes
        - file
      properties:
        purposes:
          type: array
          items:
            type: string
            enum:
              - certificate_of_incorporation
              - corporate_registry_extract
              - memart
              - corporate_structure_chart
              - board_resolution
              - aml_policy
              - regulatory_licenses
              - proof_of_funds
              - proof_of_wealth
              - proof_of_address
              - selfie_video
              - selfie
              - others
          description: Purposes for which the document is being submitted
        file:
          type: string
          description: URL or Document file content in base64 format. The maximum file size is 4MB.
    BaseCustomerRequest:
      allOf:
        - type: object
          properties:
            phone:
              $ref: '#/components/schemas/PhoneField'
            birth_date:
              type: string
              example: 24-12-2000
              description: date of birth of the user
            address:
              $ref: '#/components/schemas/Address'
            identifying_information:
              type: array
              description: List of identification documents provided by the customer
              minItems: 0
              maxItems: 5
              items:
                $ref: '#/components/schemas/CustomerIdentifyingInformation'
            documents:
              type: array
              description: Additional supporting documents provided by the customer
              minItems: 0
              maxItems: 10
              uniqueItems: true
              items:
                $ref: '#/components/schemas/CustomerDocument'
    BVNField:
      type: string
      description: Bank Verification Number (BVN)
      format: number
      example: '12345678901'
      minLength: 11
      maxLength: 11
      x-oapi-codegen-extra-tags:
        validate: num|len:11
    CustomerBusinessOwner:
      type: object
      required:
        - first_name
        - last_name
        - role
        - nationality
        - percentage_ownership
        - is_pep
      properties:
        first_name:
          type: string
          maxLength: 100
        last_name:
          type: string
          maxLength: 100
        role:
          type: array
          items:
            type: string
            enum:
              - director
              - owner
              - shareholder
        percentage_ownership:
          type: number
          minimum: 0
          maximum: 100
        is_pep:
          type: boolean
          default: false
        pep_type:
          type: string
        nationality:
          $ref: '#/components/schemas/CountryID'
        address:
          $ref: '#/components/schemas/Address'
        proof_of_address:
          type: string
          x-oapi-codegen-extra-tag: null
        bvn:
          $ref: '#/components/schemas/BVNField'
        proof_of_id:
          type: string
          x-oapi-codegen-extra-tag: null
    CustomerBusinessTransaction:
      type: object
      required:
        - purpose
        - monthly_transaction_value
        - monthly_transaction_count
        - client_transaction_status
        - api_access_needed
      properties:
        purpose:
          type: string
          minLength: 3
          maxLength: 100
          description: The purpose of the customer's transactions
        monthly_transaction_value:
          type: string
          enum:
            - 100_usd_or_less
            - 100_usd_to_500_usd
            - 500_usd_to_1m_usd
            - above_1m_usd
          description: Expected monthly value of transactions in USD
        monthly_transaction_count:
          type: string
          enum:
            - 10_or_less
            - 10_to_50
            - 50_to_100
            - 100_to_200
            - above_200
          description: Expected number of transactions per month
        client_transaction_status:
          type: string
          enum:
            - self-owned
            - on-behalf
          description: Whether transactions are self-owned or on behalf of clients
        api_access_needed:
          type: boolean
          description: Whether API access is required for transactions
        api_integration_url:
          type: string
          format: uri
          description: Required when api_access_needed is true. URL for API integration
    CustomerBusinessRegistration:
      type: object
      required:
        - business_type
        - business_structure
        - business_regulation_status
        - registration_number
        - tax_identification_number
        - corporate_group_status
        - exchange_listing_status
        - license_number
      properties:
        business_type:
          type: string
          enum:
            - type_registered_company
            - type_sole_proprietorship
          description: Type of business organization
        business_structure:
          type: string
          enum:
            - public_limited_company
            - registered_business_name
            - other
            - limited_liability_company
            - limited_liability_partnership
          description: Legal structure of the business
        business_regulation_status:
          type: string
          enum:
            - regulated
            - unregulated
          description: Whether business is regulated or not
        registration_number:
          type: string
          maxLength: 20
          description: Business registration number
        tax_identification_number:
          type: string
          maxLength: 20
          description: Tax ID number of business
        corporate_group_status:
          type: string
          enum:
            - standalone_company
            - subsidiary
            - holding_company
          description: Status within corporate group structure
        exchange_listing_status:
          type: string
          enum:
            - listed_on_exchange
            - not_listed_on_exchange
            - owned_by_listed_company
          description: Whether business is listed on stock exchange
        license_number:
          type: string
          maxLength: 30
          description: Business license number if applicable
    CustomerCreateBusiness:
      allOf:
        - $ref: '#/components/schemas/CustomerBusinessBase'
        - type: object
          required:
            - business_name
            - business_industry
          description: Business name requirements
          x-order: 2
          properties:
            business_owners:
              type: array
              items:
                $ref: '#/components/schemas/CustomerBusinessOwner'
            business_transaction:
              $ref: '#/components/schemas/CustomerBusinessTransaction'
            business_registration:
              $ref: '#/components/schemas/CustomerBusinessRegistration'
    CreateCustomerRequest:
      allOf:
        - type: object
          required:
            - email
            - has_accepted_terms
            - country_id
            - phone
            - address
            - birth_date
            - type
          properties:
            email:
              $ref: '#/components/schemas/EmailField'
            has_accepted_terms:
              type: boolean
              description: Indicates whether the customer has explicitly accepted the terms and conditions
            type:
              $ref: '#/components/schemas/BusinessCustomerType'
            country_id:
              $ref: '#/components/schemas/CountryID'
        - $ref: '#/components/schemas/BaseCustomerRequest'
        - oneOf:
            - $ref: '#/components/schemas/CustomerCreateIndividual'
            - $ref: '#/components/schemas/CustomerCreateBusiness'
    UpdateCustomerRequest:
      allOf:
        - $ref: '#/components/schemas/BaseCustomerRequest'
        - oneOf:
            - $ref: '#/components/schemas/CustomerCreateIndividual'
            - $ref: '#/components/schemas/CustomerCreateBusiness'
    CustomerTokenShareRequest:
      type: object
      required:
        - token
      properties:
        token:
          type: string
          description: JWT token
    CustomerKYCLinkResponse:
      description: Response containing the generated KYC verification link
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              type: object
              required:
                - url
              properties:
                url:
                  type: string
                  format: url
                  description: URL to the KYC verification link
    CustomerBusinessIndustry:
      type: object
      required:
        - id
        - name
        - description
        - category
        - sector
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/NanoID'
          x-order: 1
        name:
          type: string
          description: Name of the industry
          x-order: 2
        description:
          type: string
          description: Description of the industry
          x-order: 3
        category:
          type: string
          description: Category of the industry
          x-order: 4
        sector:
          type: string
          description: Sector of the industry
          x-order: 5
    PresignedUrlRequest:
      type: object
      required:
        - category
      properties:
        category:
          type: string
          enum:
            - generic
            - avatar
            - document
            - usd_payment_proof
            - checkout-logo
            - business-logo
            - compliance-docs
            - index
          default: generic
        file_type:
          type: string
          example: application/pdf
        file_name:
          type: string
          example: document.pdf
        document_id:
          type: string
          example: '123'
        key_only:
          type: boolean
          default: false
    PresignedUrlResponseObject:
      type: object
      required:
        - upload_url
        - public_link
        - expires_at
      properties:
        upload_url:
          type: string
          example: https://s3.amazonaws.com/bucket/key?signature=...
        public_link:
          type: string
          example: https://cdn.busha.co/generic/123/document.pdf
        expires_at:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'
    PresignedUrlResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/PresignedUrlResponseObject'
    InsightsInterval:
      type: string
      description: Time bucket size for insight series.
      enum:
        - day
        - week
        - month
      example: day
    TransactionTrendsSummary:
      type: object
      description: Totals for the whole reporting range.
      required:
        - total_inflow
        - total_outflow
        - net_cash_flow
      properties:
        total_inflow:
          $ref: '#/components/schemas/Decimal'
        total_outflow:
          $ref: '#/components/schemas/Decimal'
        net_cash_flow:
          $ref: '#/components/schemas/Decimal'
    TransactionTrendsPoint:
      type: object
      description: One time bucket of the cash flow series.
      required:
        - date
        - inflow
        - outflow
        - net
      properties:
        date:
          type: string
          format: date
          description: Start of the bucket (UTC).
          example: '2026-06-15'
        inflow:
          $ref: '#/components/schemas/Decimal'
        outflow:
          $ref: '#/components/schemas/Decimal'
        net:
          $ref: '#/components/schemas/Decimal'
    TransactionTrends:
      type: object
      description: Inflow/outflow/net cash flow time series for a currency.
      required:
        - currency
        - start_date
        - end_date
        - interval
        - summary
        - series
      properties:
        currency:
          type: string
          example: NGN
        start_date:
          type: string
          format: date
          example: '2026-06-15'
        end_date:
          type: string
          format: date
          example: '2026-07-15'
        interval:
          $ref: '#/components/schemas/InsightsInterval'
        summary:
          $ref: '#/components/schemas/TransactionTrendsSummary'
        series:
          type: array
          items:
            $ref: '#/components/schemas/TransactionTrendsPoint'
    TransactionBreakdownGroupBy:
      type: string
      description: |
        Dimension to group the transaction breakdown by. payment_method buckets transactions into payment rails (bank_transfer, mobile_money, direct_debit, crypto, others) derived from their category.
      enum:
        - status
        - payment_method
      example: status
    TransactionBreakdownItem:
      type: object
      description: One slice of the breakdown.
      required:
        - key
        - count
        - percentage
      properties:
        key:
          type: string
          description: Value of the grouped dimension, e.g. a transaction status or payment method.
          example: completed
        count:
          type: integer
          format: int64
          example: 91646
        percentage:
          $ref: '#/components/schemas/Decimal'
    TransactionBreakdown:
      type: object
      description: Transaction counts grouped by a dimension.
      required:
        - group_by
        - total_count
        - items
      properties:
        group_by:
          $ref: '#/components/schemas/TransactionBreakdownGroupBy'
        total_count:
          type: integer
          format: int64
          example: 100932
        items:
          type: array
          items:
            $ref: '#/components/schemas/TransactionBreakdownItem'
    NullableDecimal:
      type: string
      description: nullable decimal value
      example: '100'
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
        name: decimal
      nullable: true
    CustomerGrowthSummary:
      type: object
      description: Customer totals for the reporting range.
      required:
        - total_customers
        - new_customers
      properties:
        total_customers:
          type: integer
          format: int64
          description: Total customers as at end_date.
          example: 100932
        new_customers:
          type: integer
          format: int64
          description: Customers added within the reporting range.
          example: 2340
        growth_rate:
          $ref: '#/components/schemas/NullableDecimal'
    CustomerGrowthPoint:
      type: object
      description: One time bucket of the customer growth series.
      required:
        - date
        - new_customers
        - cumulative_customers
      properties:
        date:
          type: string
          format: date
          description: Start of the bucket (UTC).
          example: '2026-06-15'
        new_customers:
          type: integer
          format: int64
          example: 12
        cumulative_customers:
          type: integer
          format: int64
          example: 98211
    CustomerGrowth:
      type: object
      description: Business customer growth trend.
      required:
        - start_date
        - end_date
        - interval
        - summary
        - series
      properties:
        start_date:
          type: string
          format: date
          example: '2026-06-15'
        end_date:
          type: string
          format: date
          example: '2026-07-15'
        interval:
          $ref: '#/components/schemas/InsightsInterval'
        summary:
          $ref: '#/components/schemas/CustomerGrowthSummary'
        series:
          type: array
          items:
            $ref: '#/components/schemas/CustomerGrowthPoint'
    ValidateDestinationRequest:
      type: object
      required:
        - type
        - currency
      properties:
        type:
          type: string
          example: address
          enum:
            - address
        address:
          type: string
          example: tb1qj4263506wyu8khrz2dwce0agk8lhyjgy269rxr
          description: |
            This is the address for type `address`
        currency:
          $ref: '#/components/schemas/Currency'
        network:
          type: string
          example: BTC
          description: |
            This specifies the blockchain network associated with the address receiving the payment, typically used with address type payouts.
        memo:
          type: string
          example: memo
          description: |
            This refers to the memo required for blockchain networks that mandate a memo for cryptocurrency transactions.
    ValidateDestinationResponseObject:
      allOf:
        - $ref: '#/components/schemas/ValidateDestinationRequest'
        - type: object
          properties:
            valid:
              type: boolean
              example: true
    ValidateDestinationResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/ValidateDestinationResponseObject'
    Bank:
      type: object
      required:
        - name
        - code
        - currency
      properties:
        name:
          type: string
          x-order: 1
          example: Wema Bank
        code:
          type: string
          example: '000017'
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          example: NGN
    ListBankResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Bank'
    CurrencyMini:
      type: object
      required:
        - code
        - name
        - symbol
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/Currency'
        name:
          type: string
          example: Bitcoin
          description: The official name of the cryptocurrency.
        symbol:
          type: string
          example: $
          description: The official symbol of the cryptocurrency.\
    PayObj:
      type: object
      required:
        - channel
        - name
        - min
        - max
        - currency
        - processing_time
      properties:
        channel:
          type: string
          example: bank-transfer
          description: The channel of the payment option.
        name:
          type: string
          example: Bitcoin
          description: The name of the payment option.
        min:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        max:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        processing_time:
          type: string
          example: 0-15 minutes
          description: The average time to process via the payment option.
    Country:
      type: object
      required:
        - id
        - name
        - currency
        - payment_methods
        - payout_methods
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/CountryID'
          x-order: 1
        name:
          type: string
          x-order: 2
          example: Bitcoin
          description: The official name of the cryptocurrency.
        currency:
          allOf:
            - $ref: '#/components/schemas/CurrencyMini'
        payment_methods:
          type: array
          items:
            $ref: '#/components/schemas/PayObj'
        payout_methods:
          type: array
          items:
            $ref: '#/components/schemas/PayObj'
    CountriesListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              description: List of recipients
              items:
                $ref: '#/components/schemas/Country'
          required:
            - data
    LookUpResponseObject:
      type: object
      required:
        - username
        - currency
        - network
        - address
        - country_id
      properties:
        username:
          type: string
          example: john_doe@busha
        currency:
          type: string
          example: BTC
        country_id:
          $ref: '#/components/schemas/CountryID'
        network:
          type: string
          example: BTC
        address:
          type: string
          example: tb1qj4263506wyu8khrz2dwce0agk8lhyjgy269rxr
        memo:
          type: string
          example: memo123
        auto_convert_currency:
          type: string
          example: NGN
    MerchantObject:
      x-internal: false
      type: object
      required:
        - username
        - supported_currencies
      properties:
        username:
          type: string
          example: john_doe@busha
        supported_currencies:
          type: array
          items:
            $ref: '#/components/schemas/Currency'
          example:
            - BTC
        logo:
          type: string
          format: url
          example: https://logo@cdn.url
    RegenerateDepositAddressReq:
      type: object
      required:
        - network
        - currency
      properties:
        network:
          $ref: '#/components/schemas/Currency'
        currency:
          $ref: '#/components/schemas/Currency'
    VirtualBankAccountMeta:
      type: object
      description: Additional metadata for the virtual bank account
      required:
        - methods
      properties:
        methods:
          type: array
          items:
            type: string
            enum:
              - ACH
              - WIRE
          example:
            - ACH
          description: The payment methods for this virtual bank account
        address:
          type: string
          example: 1800 North Pole St., Orlando, FL 32801
        sort_code:
          type: string
          example: 26-74-90
    VirtualBankAccount:
      type: object
      required:
        - id
        - profile_id
        - currency_code
        - account_name
        - account_number
        - bank_name
        - bank_code
        - status
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/NanoID'
        profile_id:
          $ref: '#/components/schemas/NanoID'
        currency_code:
          $ref: '#/components/schemas/Currency'
        account_name:
          type: string
          example: John Doe - Busha
        account_number:
          type: string
          example: '1234567890'
        bank_name:
          type: string
          example: Wema Bank
        bank_code:
          type: string
          example: '035'
        status:
          type: string
          example: active
        reference:
          type: string
          example: '1234567890'
        created_at:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
        fee:
          $ref: '#/components/schemas/Decimal'
        meta:
          $ref: '#/components/schemas/VirtualBankAccountMeta'
    FeeItem:
      type: object
      description: A fee or setup item with label, value and optional description
      required:
        - label
        - value
      properties:
        label:
          type: string
          example: Setup time
          description: The display label for the item
        value:
          type: string
          example: 1-2 days
          description: The value or amount for the item
        description:
          type: string
          example: Getting your account takes
          description: Additional description for the item
        is_free:
          type: boolean
          default: false
          description: Whether this item is free (for badge display)
    SetupAndFees:
      type: object
      description: Setup and fees information for the virtual bank account
      required:
        - setup_time
        - activation_fee
        - monthly_maintenance_fee
        - minimum_deposit
      properties:
        setup_time:
          $ref: '#/components/schemas/FeeItem'
        activation_fee:
          $ref: '#/components/schemas/FeeItem'
        monthly_maintenance_fee:
          $ref: '#/components/schemas/FeeItem'
        minimum_deposit:
          $ref: '#/components/schemas/FeeItem'
    PaymentMethodFee:
      type: object
      description: Payment method and its associated fee
      required:
        - method
        - fee
      properties:
        method:
          type: string
          example: ACH
          description: The payment method name
        fee:
          type: string
          example: 1% of deposit
          description: The fee description for this payment method
        supported:
          type: boolean
          default: true
          description: Whether this payment method is supported
    ProcessingTime:
      type: object
      description: Processing time information
      required:
        - description
      properties:
        title:
          type: string
          example: Processing time
          description: The section title
        description:
          type: string
          example: Incoming deposits take 1-3 business days to arrive, depending on the payment method used
          description: Detailed processing time description
    LimitItem:
      type: object
      description: A limit item with label and value
      required:
        - label
        - value
      properties:
        label:
          type: string
          example: 1st party deposits
          description: The limit type label
        value:
          type: string
          example: $100,000 max/deposit
          description: The limit value description
    DepositLimits:
      type: object
      description: Deposit limits for different party types
      required:
        - first_party
        - third_party
      properties:
        first_party:
          $ref: '#/components/schemas/LimitItem'
        third_party:
          $ref: '#/components/schemas/LimitItem'
    VirtualBankAccountTerms:
      type: object
      description: Terms and conditions for a virtual bank account
      required:
        - title
        - subtitle
        - setup_and_fees
        - payment_methods
        - processing_time
        - limits
        - accepted_payments
      properties:
        title:
          type: string
          example: Account terms of use
          description: The main title for the terms screen
        subtitle:
          type: string
          example: To create a USD account, review & accept these usage terms
          description: The subtitle explaining the purpose
        setup_and_fees:
          $ref: '#/components/schemas/SetupAndFees'
        payment_methods:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodFee'
          description: List of payment methods and their associated fees
        processing_time:
          $ref: '#/components/schemas/ProcessingTime'
        limits:
          $ref: '#/components/schemas/DepositLimits'
        accepted_payments:
          type: array
          items:
            type: string
          description: List of accepted payment descriptions
          example:
            - Receive unlimited deposit from accounts in your name, from registered business entities or from family members who share your surname.
            - Payments from sources other than those listed above (3rd party deposits) are also accepted, subject to limits.
    AmountWithCounter:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        currency:
          $ref: '#/components/schemas/Currency'
        counter:
          $ref: '#/components/schemas/AmountWithCurrency'
    Pairs:
      type: object
      required:
        - id
        - base
        - base_currency_name
        - counter
        - counter_currency_name
        - type
        - is_buy_supported
        - is_sell_supported
        - buy_price
        - sell_price
      properties:
        id:
          type: string
          x-order: 1
          example: BTCNGN
        base:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 2
        base_currency_name:
          type: string
          x-order: 2
          example: Bitcoin
        counter:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 3
        counter_currency_name:
          type: string
          x-order: 3
          example: Naira
        type:
          type: string
          x-order: 4
          enum:
            - crypto
            - fiat
            - stablecoin
            - stock
        buy_price:
          x-order: 5
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
        sell_price:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          x-order: 6
        is_buy_supported:
          x-order: 7
          type: boolean
        is_sell_supported:
          x-order: 8
          type: boolean
        min_buy_amount:
          x-order: 9
          allOf:
            - $ref: '#/components/schemas/AmountWithCounter'
        min_sell_amount:
          x-order: 10
          allOf:
            - $ref: '#/components/schemas/AmountWithCounter'
        max_buy_amount:
          x-order: 11
          allOf:
            - $ref: '#/components/schemas/AmountWithCounter'
        max_sell_amount:
          x-order: 12
          allOf:
            - $ref: '#/components/schemas/AmountWithCounter'
        base_decimal:
          type: string
          x-order: 13
          example: '6'
        counter_decimal:
          type: string
          x-order: 14
          example: '6'
        percentage_change:
          allOf:
            - $ref: '#/components/schemas/Decimal'
    PairsListResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          properties:
            data:
              type: array
              maxItems: 100
              items:
                $ref: '#/components/schemas/Pairs'
    PaymentLinkStatus:
      type: string
      enum:
        - draft
        - pending
        - active
        - expired
        - deleted
        - paid
    PaymentLinkType:
      type: string
      enum:
        - payment_link
        - invoice
    AmountLimit:
      type: object
      required:
        - min_amount
        - max_amount
      properties:
        min_amount:
          $ref: '#/components/schemas/Decimal'
        max_amount:
          $ref: '#/components/schemas/Decimal'
    PaymentLinkExtraInfo:
      type: object
      required:
        - field_name
        - required
      properties:
        field_name:
          type: string
        required:
          type: boolean
    InvoiceItem:
      type: object
      required:
        - item
        - quantity
        - amount
      properties:
        item:
          type: string
          description: Name/description of the item
          maxLength: 255
        quantity:
          type: integer
          description: Quantity of the item
          minimum: 1
        amount:
          $ref: '#/components/schemas/Decimal'
          description: Unit price of the item
    PaymentLinkMeta:
      type: object
      properties:
        images:
          type: array
          items:
            type: string
            format: url
        allow_customer_amount:
          type: boolean
        amount_limit:
          $ref: '#/components/schemas/AmountLimit'
        allow_quantity_selection:
          type: boolean
        require_extra_info:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLinkExtraInfo'
        customer_email:
          type: string
          format: email
          description: Customer email for invoices
        customer_name:
          type: string
          description: Customer name for invoices
        due_date:
          type: string
          format: date-time
          description: Due date for invoices
        note:
          type: string
          maxLength: 250
          description: Optional note for invoices
        items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceItem'
    TimeStamp:
      type: string
      format: date-time
      example: '2023-10-15T12:15:30Z'
      x-go-type: time.Time
    PaymentLink:
      type: object
      required:
        - id
        - profile_id
        - type
        - fixed
        - one_time
        - name
        - link
        - title
        - description
        - target_currency
        - status
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/NanoID'
        profile_id:
          $ref: '#/components/schemas/NanoID'
        type:
          x-order: 2
          $ref: '#/components/schemas/PaymentLinkType'
        fixed:
          x-order: 3
          type: boolean
          example: false
          description: |
            If true it will use the fixed amount, otherwise it will use the dynamic amount
        one_time:
          x-order: 4
          type: boolean
          example: false
          description: |
            If true it is a one-time link, otherwise it is a reusable link
        link:
          type: string
          format: url
          example: https://pay.busha.io/charges/123456789
        name:
          x-order: 5
          type: string
          example: Payment Link
        title:
          x-order: 6
          type: string
          description: |
            The display title shown to customers
        description:
          x-order: 7
          type: string
          description: |
            The display description shown to customers
        quote_amount:
          x-order: 8
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: |
            The amount to be paid for the product/service pegged to the quote currency
        quote_currency:
          x-order: 9
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: |
            The currency used to price the amount, which is converted from the source amount
        target_amount:
          x-order: 10
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: |
            The amount to be paid for the product/service in a crypto currency (target currency)
        target_currency:
          x-order: 11
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: |
            The crypto currency to which payment is to be received in
        meta:
          x-order: 12
          allOf:
            - $ref: '#/components/schemas/PaymentLinkMeta'
        status:
          x-order: 13
          allOf:
            - $ref: '#/components/schemas/PaymentLinkStatus'
        pub_key:
          type: string
        created_at:
          x-order: 14
          allOf:
            - $ref: '#/components/schemas/TimeStamp'
        updated_at:
          x-order: 15
          allOf:
            - $ref: '#/components/schemas/TimeStamp'
        expires_at:
          x-order: 16
          allOf:
            - $ref: '#/components/schemas/TimeStamp'
    PaymentLinkListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          required:
            - data
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PaymentLink'
    PaymentLinkRequestAmountLimit:
      type: object
      required:
        - min_amount
        - max_amount
      properties:
        min_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        max_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
    PaymentLinkRequestInvoiceItem:
      type: object
      required:
        - item
        - quantity
        - amount
      properties:
        item:
          type: string
          description: Name/description of the item
          maxLength: 255
        quantity:
          type: integer
          description: Quantity of the item
          minimum: 1
        amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: Unit price of the item
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
    CreatePaymentLinkReq:
      type: object
      required:
        - fixed
        - one_time
        - name
        - description
        - title
        - target_currency
      properties:
        type:
          $ref: '#/components/schemas/PaymentLinkType'
          description: Optional. Derived from fixed/one_time if not provided
        fixed:
          type: boolean
        one_time:
          type: boolean
        name:
          type: string
        title:
          type: string
        description:
          type: string
        quote_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        require_extra_info:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLinkExtraInfo'
        images:
          type: array
          items:
            type: string
            format: url
        allow_customer_amount:
          type: boolean
        amount_limit:
          $ref: '#/components/schemas/PaymentLinkRequestAmountLimit'
        allow_quantity_selection:
          type: boolean
        customer_email:
          type: string
          format: email
          description: Required when type is invoice
        customer_name:
          type: string
          description: Required when type is invoice
        due_date:
          type: string
          format: date-time
          description: Optional due date for invoice (must be in the future)
        note:
          type: string
          maxLength: 250
          description: Optional note for invoice (max 250 characters)
        items:
          type: array
          description: Line items for invoice type payment links
          items:
            $ref: '#/components/schemas/PaymentLinkRequestInvoiceItem'
        dry_run:
          type: boolean
          description: if true, will not create a payment transfer
    NullableCurrency:
      type: string
      x-order: 20
      example: BTC
      format: string
      maxLength: 10
      minLength: 1
      nullable: true
    UpdatePaymentLinkReq:
      type: object
      properties:
        quote_amount:
          type: string
          format: decimal
          nullable: true
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        quote_currency:
          $ref: '#/components/schemas/NullableCurrency'
        target_amount:
          type: string
          format: decimal
          nullable: true
          x-go-type: decimal.Decimal
          x-go-type-import:
            path: github.com/shopspring/decimal
            name: decimal
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        name:
          type: string
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - pending
            - active
        require_extra_info:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLinkExtraInfo'
        images:
          type: array
          items:
            type: string
            format: url
        allow_customer_amount:
          type: boolean
        amount_limit:
          $ref: '#/components/schemas/PaymentLinkRequestAmountLimit'
        allow_quantity_selection:
          type: boolean
        customer_email:
          type: string
          format: email
          description: Can update customer email for existing invoices
        customer_name:
          type: string
          description: Can update customer name for existing invoices
        due_date:
          type: string
          format: date-time
          description: Can update due date for existing invoices (must be in the future)
        note:
          type: string
          maxLength: 250
          description: Can update note for existing invoices (max 250 characters)
        items:
          type: array
          description: Update line items for existing invoices
          items:
            $ref: '#/components/schemas/PaymentLinkRequestInvoiceItem'
    PaymentRequestStatus:
      type: string
      enum:
        - pending
        - expired
        - cancelled
        - completed
        - failed
        - multiple_deposits
        - under_payment
        - over_payment
    PaymentRequestType:
      type: string
      enum:
        - donation
        - checkout
        - invoice
    QuoteRate:
      type: object
      properties:
        product:
          type: string
          example: BTCUSDT
        rate_explained:
          type: string
          example: 1 BTC = 1000 USDT
        source_currency:
          $ref: '#/components/schemas/Currency'
        target_currency:
          $ref: '#/components/schemas/Currency'
        rate:
          $ref: '#/components/schemas/Decimal'
        side:
          type: string
          enum:
            - buy
            - sell
          example: sell
        type:
          type: string
          enum:
            - FIXED
          example: FIXED
    FeeType:
      type: string
      enum:
        - FIXED
        - PERCENTAGE
        - TIERED
      example: FIXED
    Fee:
      type: object
      x-order: 40
      required:
        - name
        - amount
        - type
      properties:
        name:
          type: string
          example: processing_fee
        amount:
          $ref: '#/components/schemas/AmountWithCurrency'
        converted_amount:
          $ref: '#/components/schemas/AmountWithCurrency'
        type:
          $ref: '#/components/schemas/FeeType'
    PayOutObj:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          example: address
          description: |
            The payout type. NOTE: `sweep` is reserved for Busha Business
            dashboard sessions (master <-> sub-account internal transfers)
            and is rejected on public API-key requests.
          enum:
            - address
            - bank_transfer
            - mobile_money
            - paybill
            - till
            - payout_batch
            - balance
            - savings
            - direct_debit
            - sweep
            - internal
        recipient_id:
          type: string
          example: 64ae8c26ea1033204c805a8a
          description: |
            This represents the recipient ID, used for `mobile_money` and `bank_transfer` types.
            For `payout_batch`, this should contain the payout batch ID.
        address:
          type: string
          example: tb1qj4263506wyu8khrz2dwce0agk8lhyjgy269rxr
          description: |
            This could be the address, user email or username for type `address`. For type `sweep`, this is the email of the destination account. Required when the sender is the master (master -> sub); optional when the sender is a sub-account (the destination master is resolved automatically from the sub's parent business).
            For type `internal`, this is the destination Busha profile ID, destination email, or a public key that resolves to the owning business profile.
        network:
          type: string
          example: BTC
          description: |
            This specifies the blockchain network associated with the address receiving the payment, typically used with address type payouts.
        memo:
          type: string
          example: memo
          description: |
            This refers to the memo required for blockchain networks that mandate a memo for cryptocurrency transactions.
        narration:
          type: string
          example: Payment for services
          description: |
            A narration or description for the withdrawal. Required for USD bank transfer withdrawals.
        payment_invoice_url:
          type: string
          example: https://example.com/invoice.pdf
          description: |
            URL of the payment invoice or supporting document. Required for business account USD withdrawals
            and personal account USD withdrawals exceeding $10,000.
    RecipientDetails:
      type: object
      properties:
        account_name:
          type: string
        bank_name:
          type: string
        account_number:
          type: string
        country_code:
          type: string
          example: NG
        provider:
          type: string
        iban:
          type: string
          example: NG12345678901234567890
        currency:
          type: string
        phone_number:
          type: string
        name:
          type: string
        email:
          type: string
          example: sbsbs@busha.co
        bank_code:
          type: string
          example: '100020'
    PaymentObj:
      allOf:
        - $ref: '#/components/schemas/PayOutObj'
        - type: object
          properties:
            profile_id:
              type: string
              example: profile-id-1234
            memo:
              type: string
              example: address memo
            recipient_details:
              $ref: '#/components/schemas/RecipientDetails'
            blockchain_hash:
              type: string
              x-order: 16
              example: 31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171
            blockchain_url:
              type: string
              x-order: 16
              example: https://explorer.com/tx/31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171
            session_id:
              type: string
              x-order: 16
              example: 31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171
            from_address:
              type: string
              x-order: 16
              example: 31b99c79e2fb7554d0a9421867a53a80e6810cdfd2b06826eec1b2a22974b171
            expires_at:
              type: string
              format: date-time
              example: '2023-10-15T12:15:30Z'
    TwoStep:
      type: object
      required:
        - type
        - message
        - resend_allowed
      x-order: 17
      properties:
        type:
          type: string
          enum:
            - authenticator
          example: authenticator
          description: the type of two step verification required
        message:
          type: string
          example: Enter your 2FA code to continue
        resend_allowed:
          type: boolean
          example: false
          description: If the code can be resent
    AdditionalInfo:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: email address for the payment request
        phone_number:
          $ref: '#/components/schemas/PhoneField'
        name:
          $ref: '#/components/schemas/NameField'
        source:
          type: string
          description: The source of the payment request
          example: web
    MerchantInfo:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: name of the business
          example: busha
        email:
          type: string
          format: email
          description: email of the business
          example: busha@me.com
    Timeline:
      type: object
      required:
        - step
        - done
        - status
        - title
        - description
      properties:
        step:
          type: integer
          x-order: 1
          example: 1
        done:
          type: boolean
          x-order: 2
          example: true
        status:
          type: string
          x-order: 3
          enum:
            - pending
            - processing
            - funds_converted
            - funds_received
            - outgoing_payment_sent
            - funds_delivered
            - reverse_fund_conversion
            - failed
            - completed
        title:
          type: string
          x-order: 4
          example: Transfer started
        description:
          type: string
          x-order: 5
          example: Transfer started
          description: Waiting for payment
        timestamp:
          type: string
          x-order: 6
          format: date-time
          example: '2023-10-15T12:15:30Z'
    TransferTimeline:
      type: object
      required:
        - total_steps
        - current_step
        - transfer_status
        - events
      properties:
        total_steps:
          type: integer
          x-order: 1
        current_step:
          type: integer
          x-order: 2
        transfer_status:
          type: string
          x-order: 3
        events:
          type: array
          items:
            $ref: '#/components/schemas/Timeline'
    PaymentRequest:
      type: object
      required:
        - id
        - source_amount
        - source_currency
        - target_amount
        - target_currency
        - requested_amount
        - currency
        - rate
        - fees
        - reference
        - additional_info
        - merchant_info
        - status
        - type
        - created_at
        - updated_at
        - expires_at
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/NanoID'
          x-order: 1
        type:
          allOf:
            - $ref: '#/components/schemas/PaymentRequestType'
          x-order: 2
        status:
          allOf:
            - $ref: '#/components/schemas/PaymentRequestStatus'
          x-order: 3
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 4
        source_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 5
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 6
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 7
        requested_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: The amount requested by the merchant
          x-order: 8
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: The currency it was requested in
          x-order: 9
        rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 10
        fees:
          type: array
          items:
            $ref: '#/components/schemas/Fee'
          x-order: 11
        pay_in:
          allOf:
            - $ref: '#/components/schemas/PaymentObj'
          x-order: 12
        two_step:
          allOf:
            - $ref: '#/components/schemas/TwoStep'
          x-order: 13
        reference:
          type: string
          x-order: 14
        merchant_reference:
          type: string
          x-order: 15
        additional_info:
          allOf:
            - $ref: '#/components/schemas/AdditionalInfo'
          x-order: 16
        merchant_info:
          allOf:
            - $ref: '#/components/schemas/MerchantInfo'
          x-order: 17
        source:
          type: string
          description: The source of the payment request
          x-order: 18
        source_id:
          type: string
          description: The source id of the payment request
          x-order: 19
        timeline:
          allOf:
            - $ref: '#/components/schemas/TransferTimeline'
          x-order: 20
        created_at:
          type: string
          format: date-time
          example: '2023-10-15T12:15:30Z'
          x-order: 21
        updated_at:
          type: string
          format: date-time
          example: '2023-10-15T12:15:30Z'
          x-order: 22
        expires_at:
          type: string
          format: date-time
          example: '2023-10-15T12:15:30Z'
          x-order: 23
        quote_rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 24
          description: This shows the rate used to derive the amount when quote_currency is provided.
    UnAuthPayInObj:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          example: address
          enum:
            - address
            - mobile_money
            - temporary_bank_account
            - direct_debit
            - balance
        network:
          type: string
          example: BTC
          description: |
            This specifies the blockchain network associated with the address receiving the payment, typically used with address type payouts.
    PayInObj:
      allOf:
        - $ref: '#/components/schemas/UnAuthPayInObj'
        - type: object
          properties:
            phone:
              $ref: '#/components/schemas/PhoneField'
            recipient_id:
              type: string
              example: 64ae8c26ea1033204c805a8a
              description: |
                This represents the recipient ID. Used for `direct_debit` types (mandate ID).
    CreatePaymentRequestForLinkReq:
      type: object
      required:
        - source_currency
      properties:
        quote_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        source_currency:
          $ref: '#/components/schemas/Currency'
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        pay_in:
          $ref: '#/components/schemas/PayInObj'
        requested_info:
          type: object
          additionalProperties:
            type: string
        reference:
          type: string
    PaymentRequestListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          required:
            - data
          properties:
            data:
              type: array
              description: List of payment requests
              items:
                $ref: '#/components/schemas/PaymentRequest'
    CreatePaymentRequest:
      type: object
      required:
        - additional_info
        - source_currency
        - target_currency
      properties:
        additional_info:
          $ref: '#/components/schemas/AdditionalInfo'
        quote_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: This optional field specifies the currency to price the payment request in, which is converted from the source amount
          example: NGN
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        source_currency:
          $ref: '#/components/schemas/Currency'
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        target_currency:
          $ref: '#/components/schemas/Currency'
        pay_in:
          $ref: '#/components/schemas/PayInObj'
        reference:
          type: string
          description: reference for the payment request
          example: busha-123
    PaymentRequestResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/PaymentRequest'
    FinalizePaymentRequest:
      type: object
      properties:
        code:
          type: string
          maxLength: 6
          description: Optional auth code required for MFA
    PledgeAmountRequest:
      type: object
      required:
        - asset
        - amount
      properties:
        asset:
          $ref: '#/components/schemas/Currency'
        amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
    PledgeMeta:
      type: object
      additionalProperties: true
      description: Optional non-query-critical pledge context.
    CreatePledgeQuoteRequest:
      type: object
      required:
        - reference
        - items
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 255
          description: Beneficiary-supplied credit agreement or case reference.
          example: credit_agreement_93b7
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:255
            filter: trim
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PledgeAmountRequest'
        expires_at:
          $ref: '#/components/schemas/TimeStamp'
        meta:
          $ref: '#/components/schemas/PledgeMeta'
    PledgeQuoteItem:
      type: object
      required:
        - asset
        - amount
        - can_lock
      properties:
        asset:
          $ref: '#/components/schemas/Currency'
        amount:
          $ref: '#/components/schemas/Decimal'
        can_lock:
          type: boolean
          example: true
    PledgeQuote:
      type: object
      required:
        - id
        - status
        - expires_at
        - reference
        - can_create
        - items
      properties:
        id:
          type: string
          example: PLQ_01HX...
        status:
          type: string
          enum:
            - quoted
          example: quoted
        expires_at:
          $ref: '#/components/schemas/TimeStamp'
        reference:
          type: string
          example: credit_agreement_93b7
        can_create:
          type: boolean
          example: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/PledgeQuoteItem'
    PledgeStatus:
      type: string
      enum:
        - authorized
        - active
        - liquidation_pending
        - released
        - liquidated
        - expired
        - cancelled
    PledgeItemStatus:
      type: string
      enum:
        - locked
        - partially_released
        - released
        - partially_liquidated
        - liquidated
    PledgeItem:
      type: object
      required:
        - id
        - asset
        - locked_amount
        - released_amount
        - liquidated_amount
        - status
      properties:
        id:
          type: string
          example: PLI_01HX...
        asset:
          $ref: '#/components/schemas/Currency'
        locked_amount:
          $ref: '#/components/schemas/Decimal'
        released_amount:
          $ref: '#/components/schemas/Decimal'
        liquidated_amount:
          $ref: '#/components/schemas/Decimal'
        available_to_release:
          $ref: '#/components/schemas/Decimal'
        status:
          $ref: '#/components/schemas/PledgeItemStatus'
    PledgeEvent:
      type: object
      required:
        - id
        - type
        - actor_type
        - created_at
      properties:
        id:
          type: string
          example: PLE_01HX...
        type:
          type: string
          example: pledge.activated
        actor_type:
          type: string
          enum:
            - customer
            - beneficiary
            - admin
            - system
          example: beneficiary
        reference:
          type: string
          example: activation_disb_9f1
        created_at:
          $ref: '#/components/schemas/TimeStamp'
    Pledge:
      type: object
      required:
        - id
        - status
        - reference
        - mandate_hash
        - items
      properties:
        id:
          type: string
          example: PLG_01HX...
        status:
          $ref: '#/components/schemas/PledgeStatus'
        customer_profile_id:
          type: string
          example: PRF_customer...
        beneficiary_profile_id:
          type: string
          example: BUS_beneficiary...
        reference:
          type: string
          example: credit_agreement_93b7
        mandate_hash:
          type: string
          example: sha256:...
        activated_at:
          $ref: '#/components/schemas/TimeStamp'
        expires_at:
          $ref: '#/components/schemas/TimeStamp'
        released_at:
          $ref: '#/components/schemas/TimeStamp'
        liquidated_at:
          $ref: '#/components/schemas/TimeStamp'
        items:
          type: array
          items:
            $ref: '#/components/schemas/PledgeItem'
        events:
          type: array
          items:
            $ref: '#/components/schemas/PledgeEvent'
    CreatePledgeRequest:
      type: object
      required:
        - quote_id
      properties:
        quote_id:
          type: string
          minLength: 1
          description: ID of the previously created pledge quote.
          example: PLQ_01HX...
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1
            filter: trim
        meta:
          $ref: '#/components/schemas/PledgeMeta'
    ActivatePledgeRequest:
      type: object
      required:
        - reference
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 255
          example: activation_disb_9f1
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:255
            filter: trim
        activated_at:
          $ref: '#/components/schemas/TimeStamp'
        meta:
          $ref: '#/components/schemas/PledgeMeta'
    PledgeAction:
      type: object
      required:
        - id
        - status
        - event_id
      properties:
        id:
          type: string
          example: PLG_01HX...
        status:
          $ref: '#/components/schemas/PledgeStatus'
        activated_at:
          $ref: '#/components/schemas/TimeStamp'
        event_id:
          type: string
          example: PLE_01HX...
    AddPledgeItemsRequest:
      type: object
      required:
        - reference
        - items
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 255
          example: topup_7af2
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:255
            filter: trim
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PledgeAmountRequest'
        reason:
          type: string
          maxLength: 255
          example: beneficiary_requested_top_up
        meta:
          $ref: '#/components/schemas/PledgeMeta'
    AddPledgeItemsResult:
      type: object
      required:
        - id
        - status
        - items
        - event_id
      properties:
        id:
          type: string
          example: PLG_01HX...
        status:
          $ref: '#/components/schemas/PledgeStatus'
        items:
          type: array
          items:
            $ref: '#/components/schemas/PledgeItem'
        event_id:
          type: string
          example: PLE_01HZ...
    PledgeItemAmountRequest:
      type: object
      required:
        - pledge_item_id
        - amount
      properties:
        pledge_item_id:
          type: string
          minLength: 1
          example: PLI_01HX...
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1
            filter: trim
        amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
    ReleasePledgeRequest:
      type: object
      required:
        - reference
        - full_release
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 255
          example: release_rel_901
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:255
            filter: trim
        full_release:
          type: boolean
          description: Release all remaining pledged assets when true.
          example: false
        reason:
          type: string
          maxLength: 255
          example: partial_repayment
        items:
          type: array
          items:
            $ref: '#/components/schemas/PledgeItemAmountRequest'
        meta:
          $ref: '#/components/schemas/PledgeMeta'
    ReleasedPledgeItem:
      type: object
      required:
        - pledge_item_id
        - asset
        - released_amount
        - remaining_locked_amount
      properties:
        pledge_item_id:
          type: string
          example: PLI_01HX...
        asset:
          $ref: '#/components/schemas/Currency'
        released_amount:
          $ref: '#/components/schemas/Decimal'
        remaining_locked_amount:
          $ref: '#/components/schemas/Decimal'
    ReleasePledgeResult:
      type: object
      required:
        - id
        - status
        - released_items
        - event_id
      properties:
        id:
          type: string
          example: PLG_01HX...
        status:
          $ref: '#/components/schemas/PledgeStatus'
        released_items:
          type: array
          items:
            $ref: '#/components/schemas/ReleasedPledgeItem'
        event_id:
          type: string
          example: PLE_01JA...
    RequestPledgeLiquidationRequest:
      type: object
      required:
        - reference
        - reason
        - beneficiary_due
        - items
        - evidence
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 255
          example: default_case_348
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:255
            filter: trim
        reason:
          type: string
          minLength: 1
          maxLength: 255
          example: default_under_beneficiary_terms
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:255
            filter: trim
        beneficiary_due:
          $ref: '#/components/schemas/AmountWithCurrency'
        items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/PledgeItemAmountRequest'
        evidence:
          type: object
          additionalProperties: true
          description: Beneficiary evidence supporting the liquidation request.
        meta:
          $ref: '#/components/schemas/PledgeMeta'
    PledgeLiquidationStatus:
      type: string
      enum:
        - pending_execution
        - cancelled
        - processing
        - completed
        - failed
      x-enum-varnames:
        - PledgeLiquidationStatusPendingExecution
        - PledgeLiquidationStatusCancelled
        - PledgeLiquidationStatusProcessing
        - PledgeLiquidationStatusCompleted
        - PledgeLiquidationStatusFailed
    PledgeLiquidation:
      type: object
      required:
        - id
        - pledge_id
        - status
        - notice_period_seconds
        - execute_after
        - beneficiary_due
        - created_at
      properties:
        id:
          type: string
          example: PLR_01JB...
        pledge_id:
          type: string
          example: PLG_01HX...
        status:
          $ref: '#/components/schemas/PledgeLiquidationStatus'
          example: pending_execution
        notice_period_seconds:
          type: integer
          format: int64
          example: 86400
        execute_after:
          $ref: '#/components/schemas/TimeStamp'
        beneficiary_due:
          $ref: '#/components/schemas/AmountWithCurrency'
        created_at:
          $ref: '#/components/schemas/TimeStamp'
    CancelPledgeLiquidationRequest:
      type: object
      required:
        - reference
        - reason
      properties:
        reference:
          type: string
          minLength: 1
          maxLength: 255
          example: cancel_default_case_348
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:255
            filter: trim
        reason:
          type: string
          minLength: 1
          maxLength: 255
          example: customer_repaid
          x-oapi-codegen-extra-tags:
            validate: required|min_len:1|max_len:255
            filter: trim
        meta:
          $ref: '#/components/schemas/PledgeMeta'
    CancelPledgeLiquidationResult:
      type: object
      required:
        - id
        - pledge_id
        - status
        - cancelled_at
        - event_id
      properties:
        id:
          type: string
          example: PLR_01JB...
        pledge_id:
          type: string
          example: PLG_01HX...
        status:
          $ref: '#/components/schemas/PledgeLiquidationStatus'
          example: cancelled
        cancelled_at:
          $ref: '#/components/schemas/TimeStamp'
        event_id:
          type: string
          example: PLE_01JC...
    ResourceID:
      type: string
      x-order: 1
      example: bus_123456789
      format: string
      description: A valid id
      x-oapi-codegen-extra-tags:
        validate: required|nanoid
    QuoteReference:
      type: string
      x-order: 2
      example: QUO_123456abc
      maxLength: 64
      minLength: 12
    Quote:
      type: object
      required:
        - id
        - source_currency
        - target_currency
        - source_amount
        - target_amount
        - profile_id
        - reference
        - created_at
        - updated_at
        - status
        - rate
        - fees
      properties:
        id:
          $ref: '#/components/schemas/ResourceID'
        source_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 5
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 6
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 7
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 8
        profile_id:
          $ref: '#/components/schemas/NanoID'
        rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 9
        fees:
          type: array
          x-order: 10
          items:
            $ref: '#/components/schemas/Fee'
        pay_in:
          allOf:
            - $ref: '#/components/schemas/PaymentObj'
          x-order: 11
        pay_out:
          allOf:
            - $ref: '#/components/schemas/PaymentObj'
          x-order: 12
        reference:
          allOf:
            - $ref: '#/components/schemas/QuoteReference'
          x-order: 12
        status:
          type: string
          x-order: 13
          enum:
            - pending
            - accepted
            - expired
          example: pending
        expires_at:
          type: string
          x-order: 14
          format: date-time
          example: '2023-12-01T15:04:05Z'
        created_at:
          type: string
          x-order: 15
          format: date-time
          example: '2023-10-15T12:15:30Z'
        updated_at:
          type: string
          x-order: 16
          format: date-time
          example: '2023-10-15T12:20:45Z'
        two_step:
          $ref: '#/components/schemas/TwoStep'
        quote_rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 17
          description: This shows the rate used to derive the amount when quote_currency is provided.
    CreateQuoteRequest:
      type: object
      required:
        - source_currency
        - target_currency
      properties:
        source_currency:
          $ref: '#/components/schemas/Currency'
        target_currency:
          $ref: '#/components/schemas/Currency'
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: This optional field specifies the currency to price the quote in, which is converted from the source amount
          example: NGN
        quote_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: The amount in the pricing currency. Required when quote_currency is provided
          example: '100'
          x-oapi-codegen-extra-tags:
            validate: requiredWith:QuoteCurrency|num_gte:0
        reversal_policy:
          type: string
          description: This optional field specifies the reversal policy for the conversion. Allowed values are 'conversion_only'.
          enum:
            - conversion_only
        reference:
          $ref: '#/components/schemas/QuoteReference'
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: Source Amount. Either `source_amount` or `target_amount` must be set.
          example: '100'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: Target Amount. Either `source_amount` or `target_amount` must be set.
          example: '100'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        pay_in:
          allOf:
            - $ref: '#/components/schemas/PayInObj'
            - type: object
              properties:
                phone:
                  $ref: '#/components/schemas/PhoneField'
        pay_out:
          $ref: '#/components/schemas/PayOutObj'
    UnauthenticatedCreateQuote:
      type: object
      required:
        - source_currency
        - target_currency
      properties:
        source_currency:
          $ref: '#/components/schemas/Currency'
        target_currency:
          $ref: '#/components/schemas/Currency'
        quote_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: This optional field specifies the currency to price the quote in, which is converted from the source amount
          example: NGN
        quote_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: The amount in the pricing currency. Required when quote_currency is provided
          example: '100'
          x-oapi-codegen-extra-tags:
            validate: requiredWith:QuoteCurrency|num_gte:0
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: Source Amount. Either `source_amount` or `target_amount` must be set.
          example: '100'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: Target Amount. Either `source_amount` or `target_amount` must be set.
          example: '100'
          x-oapi-codegen-extra-tags:
            validate: num_gte:0
        pay_in:
          $ref: '#/components/schemas/UnAuthPayInObj'
        pay_out:
          $ref: '#/components/schemas/PayOutObj'
    PaymentMethodLimitObj:
      type: object
      properties:
        max_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: The maximum allowed amount for this payment method.
    FieldRequirement:
      type: object
      description: Describes the requirement condition for a field.
      properties:
        required:
          type: boolean
          description: Whether this field is always required.
        required_above:
          type: string
          description: The field is required when the amount exceeds this threshold.
          example: '10000'
    PaymentOptionMeta:
      type: object
      description: |
        Optional metadata for the payment option. Contains additional context-specific
        information such as per-payment-method limits resolved based on the requesting
        profile type (personal or business).
      properties:
        payment_method_limits:
          type: object
          description: |
            Maximum amount limits keyed by payment method ID. The limits returned
            are resolved server-side based on the requesting profile type.
          additionalProperties:
            $ref: '#/components/schemas/PaymentMethodLimitObj'
        field_requirements:
          type: object
          description: |
            Describes which additional fields are required when creating a withdrawal
            for this payment option. Keyed by field name.
          additionalProperties:
            $ref: '#/components/schemas/FieldRequirement'
    PaymentOptionObj:
      type: object
      required:
        - channel
        - name
        - description
        - currency
        - payment_method_ids
        - minimum_fee
        - maximum_fee
        - minimum_amount
        - maximum_amount
        - recommended
        - new
        - support_conversion
      properties:
        channel:
          type: string
        name:
          type: string
        description:
          type: string
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
        payment_method_ids:
          type: array
          items:
            $ref: '#/components/schemas/NanoID'
        maximum_fee:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        minimum_fee:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        maximum_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        minimum_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
        recommended:
          type: boolean
        new:
          type: boolean
        support_conversion:
          type: boolean
        meta:
          $ref: '#/components/schemas/PaymentOptionMeta'
    RecipientBase-2025-07-11:
      type: object
      required:
        - type
      properties:
        channel:
          type: string
          description: Channel for the transfer (business_mobile_money only)
          x-oapi-codegen-extra-tags:
            mapstructure: channel,omitempty
        currency:
          type: string
          description: Currency code for the recipient
          x-oapi-codegen-extra-tags:
            mapstructure: currency,omitempty
        country_code:
          type: string
          description: Country code for the recipient
          x-oapi-codegen-extra-tags:
            mapstructure: country_code,omitempty
        type:
          type: string
          description: Type of recipient account
          enum:
            - ngn_bank
            - kes_bank
            - usd_bank
            - gbp_bank
            - mpesa_mobile_money
            - mtn_mobile_money
            - crypto
            - paybill
            - till
          x-oapi-codegen-extra-tags:
            mapstructure: ',omitempty'
        entity_type:
          type: string
          additionalProperties: true
          description: Type of legal entity (for US, GB)
          enum:
            - personal
            - business
          x-oapi-codegen-extra-tags:
            mapstructure: entity_type,omitempty
        transfer_type:
          type: string
          additionalProperties: true
          description: Type of transfer (for US)
          enum:
            - ach
            - wire
            - swift
          x-oapi-codegen-extra-tags:
            mapstructure: transfer_type,omitempty
        address_label:
          type: string
          description: Name of the wallet (for crypto)
          x-oapi-codegen-extra-tags:
            mapstructure: wallet_name,omitempty
        account_name:
          type: string
          description: Name on the account
          x-oapi-codegen-extra-tags:
            mapstructure: account_name,omitempty
        email:
          type: string
          format: email
          description: Email associated with the recipient
          x-oapi-codegen-extra-tags:
            mapstructure: email,omitempty
        bank_name:
          type: string
          description: Name of the bank (for NG, US, GB)
          x-oapi-codegen-extra-tags:
            mapstructure: bank_name,omitempty
        bank_code:
          type: string
          description: Bank code (for NG only)
          x-oapi-codegen-extra-tags:
            mapstructure: bank_code,omitempty
        sort_code:
          type: string
          description: Sort code (for GB only)
          x-oapi-codegen-extra-tags:
            mapstructure: sort_code,omitempty
        routing_number:
          type: string
          description: Routing number (for US domestic ACH/Wire)
          x-oapi-codegen-extra-tags:
            mapstructure: routing_number,omitempty
        swift_code:
          type: string
          description: SWIFT/BIC code (for international transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: swift_code,omitempty
        account_number:
          type: string
          description: Account number (for domestic transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: account_number,omitempty
        till_number:
          type: string
          description: Till number (for domestic transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: till_number,omitempty
        paybill:
          type: string
          description: Paybill (for domestic transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: paybill,omitempty
        iban:
          type: string
          description: IBAN (for international transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: iban,omitempty
        phone_number:
          $ref: '#/components/schemas/PhoneField'
        network:
          type: string
          description: Blockchain network (for crypto transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: network,omitempty
        address:
          type: string
          description: Wallet address (for crypto transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: address,omitempty
        memo:
          type: string
          description: Tag/memo (for crypto transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: memo,omitempty
        recipient_address:
          type: string
          description: Address details (for international transfers)
          x-oapi-codegen-extra-tags:
            mapstructure: recipient_address,omitempty
        recipient_city:
          type: string
          description: City of the recipient's address (for US transfers)
          example: Woodhaven
          x-oapi-codegen-extra-tags:
            mapstructure: recipient_city,omitempty
        recipient_state:
          type: string
          description: State of the recipient's address (for US transfers)
          example: NY
          x-oapi-codegen-extra-tags:
            mapstructure: recipient_state,omitempty
        recipient_postal_code:
          type: string
          description: Postal code of the recipient's address (for US transfers)
          example: '11421'
          x-oapi-codegen-extra-tags:
            mapstructure: recipient_postal_code,omitempty
        intermediary_bank_name:
          type: string
          example: JPMorgan Chase Bank
          x-oapi-codegen-extra-tags:
            mapstructure: intermediary_bank_name,omitempty
        intermediary_bank_address:
          type: string
          example: 270 Park Avenue, New York, NY 10017
          x-oapi-codegen-extra-tags:
            mapstructure: intermediary_bank_address,omitempty
        intermediary_swift_code:
          type: string
          example: CHASUS33
          x-oapi-codegen-extra-tags:
            mapstructure: intermediary_swift_code,omitempty
        busha_wallet:
          type: boolean
          description: Whether the recipient is a a busha wallet
          x-oapi-codegen-extra-tags:
            mapstructure: busha_wallet,omitempty
    Recipient-2025-07-11:
      allOf:
        - $ref: '#/components/schemas/RecipientBase-2025-07-11'
        - type: object
          required:
            - object
            - id
            - profile_id
            - active
            - owned_by_customer
            - type
            - category
          properties:
            object:
              type: string
              description: Type of object
              example: recipient
            id:
              $ref: '#/components/schemas/ResourceID'
            profile_id:
              $ref: '#/components/schemas/NanoID'
            active:
              type: boolean
              description: Whether the recipient is active
            owned_by_customer:
              type: boolean
              description: Whether the recipient is owned by the customer
            category:
              type: string
              description: Category of recipient
              enum:
                - bank
                - mobile_money
                - crypto
    RecipientField:
      type: object
      required:
        - value
        - display_name
        - name
        - is_copyable
        - is_visible
        - required
      properties:
        value:
          type: string
          description: The value of the recipient field
          example: Access Bank Nigeria
        display_name:
          type: string
          description: Human-readable name of the field
          example: Bank Name
        name:
          type: string
          maxLength: 255
          x-oapi-codegen-extra-tags:
            validate: max_len:255
          description: System identifier for the field
          example: bank_name
        is_copyable:
          type: boolean
          description: Whether the field value can be copied
          example: false
        is_visible:
          type: boolean
          description: Whether the field should be displayed
          example: true
        required:
          type: boolean
          description: Whether the field is required
          example: true
    Recipient:
      deprecated: true
      type: object
      required:
        - object
        - id
        - user_id
        - profile_id
        - type
        - legal_entity_type
        - owned_by_customer
        - active
        - created_at
        - updated_at
        - fields
      properties:
        object:
          type: string
          description: Type of the object
          example: recipient
        id:
          $ref: '#/components/schemas/ID'
        user_id:
          $ref: '#/components/schemas/ID'
        profile_id:
          $ref: '#/components/schemas/ID'
        currency_id:
          $ref: '#/components/schemas/Currency'
        country_id:
          $ref: '#/components/schemas/CountryID'
        type:
          type: string
          description: Type of recipient account
          example: ngn_bank_transfer
        legal_entity_type:
          type: string
          description: Type of legal entity
          enum:
            - business
            - personal
          example: business
        owned_by_customer:
          type: boolean
          description: Whether the recipient is owned by the customer
          example: true
        active:
          type: boolean
          description: Whether the recipient is active
          example: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the recipient was created
          example: '2024-05-16T13:06:31.409336+01:00'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the recipient was last updated
          example: '2024-05-16T13:06:31.409336+01:00'
        fields:
          type: array
          description: List of fields containing recipient details
          items:
            $ref: '#/components/schemas/RecipientField'
    RecipientListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              description: List of recipients
              items:
                oneOf:
                  - $ref: '#/components/schemas/Recipient-2025-07-11'
                  - $ref: '#/components/schemas/Recipient'
          required:
            - data
    RecipientCreate-2025-07-11:
      allOf:
        - $ref: '#/components/schemas/RecipientBase-2025-07-11'
        - type: object
          properties:
            one_time:
              type: boolean
              description: Whether the recipient is a one-time recipient. One-time recipients are stored but not returned in list or get responses.
    CreateRecipientRequest:
      oneOf:
        - $ref: '#/components/schemas/RecipientCreate-2025-07-11'
        - type: object
          deprecated: true
          required:
            - currency_id
            - country_id
            - type
            - legal_entity_type
            - fields
          properties:
            currency_id:
              $ref: '#/components/schemas/Currency'
            country_id:
              $ref: '#/components/schemas/CountryID'
            type:
              type: string
              description: Type of recipient account
              example: ngn_bank_transfer
            legal_entity_type:
              type: string
              description: Type of legal entity
              enum:
                - business
                - personal
              example: business
            fields:
              type: array
              description: List of fields containing recipient details
              items:
                type: object
                required:
                  - name
                  - value
                properties:
                  name:
                    type: string
                    description: Field identifier
                    example: bank_name
                  value:
                    type: string
                    description: Field value
                    example: Access Bank Nigeria
    RecipientResponse:
      allOf:
        - $ref: '#/components/schemas/BaseSchema'
        - type: object
          required:
            - data
          properties:
            data:
              oneOf:
                - $ref: '#/components/schemas/Recipient'
                - $ref: '#/components/schemas/Recipient-2025-07-11'
    Channel:
      type: string
      description: Channel for the transfer
      enum:
        - mobile_money
        - bank_transfer
        - pay_bill
        - till
      example: bank_transfer
    ResolveBankAccountRequest:
      type: object
      required:
        - country_id
        - currency_id
        - channel
        - account_number
      properties:
        currency_id:
          $ref: '#/components/schemas/Currency'
        country_id:
          $ref: '#/components/schemas/CountryID'
        channel:
          $ref: '#/components/schemas/Channel'
        bank_code:
          type: string
          description: Bank sort code
          example: '000013'
        account_number:
          type: string
          description: Account number for receiving bank
          example: '0123456789'
      example:
        currency_id: NGN
        country_id: NG
        channel: mobile_money
        bank_code: '000013'
        account_number: '0123456789'
    ResolveBankAccountResp:
      type: object
      required:
        - country_id
        - currency_id
        - channel
        - account_number
        - account_name
      properties:
        country_id:
          $ref: '#/components/schemas/CountryID'
        currency_id:
          $ref: '#/components/schemas/Currency'
        channel:
          $ref: '#/components/schemas/Channel'
        bank_code:
          type: string
          description: Bank sort code
          example: '000013'
        account_number:
          type: string
          description: Account number for receiving bank
          example: '0123456789'
        account_name:
          type: string
          description: Name on receiving account
          example: John Doe
        bank_name:
          type: string
          description: Name of receiving bank
          example: Trust Bank
    PriceChange:
      type: object
      description: Price change with currency, absolute amount and percentage.
      properties:
        currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          description: Currency the amount is denominated in.
        amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: Absolute change (current - reference).
        percent:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: Percentage change, e.g. 1.25 = +1.25%.
    Stock:
      type: object
      required:
        - symbol
        - name
        - display_ticker
        - type
        - weekend_enabled
        - is_market_open
        - buy_supported
        - sell_supported
      properties:
        symbol:
          type: string
          example: AAPL
          description: Display ticker, the user-facing stock identity.
          x-order: 1
        name:
          type: string
          example: Apple
          x-order: 2
        display_ticker:
          type: string
          example: AAPL
          description: Display label only. Not a pricing or reconciliation key.
          x-order: 3
        type:
          type: string
          enum:
            - stock
            - etf
          x-order: 4
        sector:
          type: string
          x-order: 5
        logo_url:
          allOf:
            - $ref: '#/components/schemas/UrlField'
          x-order: 6
        price:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          description: Latest token price in USD; absent when no fresh price.
          x-order: 7
        change_24h:
          allOf:
            - $ref: '#/components/schemas/PriceChange'
          description: 24h price change (absolute and percent); absent when no 24h history.
          x-order: 8
        weekend_enabled:
          type: boolean
          x-order: 9
        is_market_open:
          type: boolean
          description: |
            Whether this stock's market is open right now, from the persisted book-meta snapshot (the inverse of its closed state, so it is off-hours aware). Falls back to the live venue observation until the first snapshot is written.
          x-order: 10
        buy_supported:
          type: boolean
          x-order: 11
        sell_supported:
          type: boolean
          x-order: 12
    MarketStatus:
      type: object
      required:
        - open
        - session
      properties:
        open:
          type: boolean
          x-order: 1
        session:
          type: string
          enum:
            - premarket
            - regular
            - postmarket
            - overnight
            - offhours
            - paused
            - closed
          x-order: 2
        next_open:
          type: string
          format: date-time
          nullable: true
          description: |
            Next scheduled venue open (RFC3339). Prefers the venue's own schedule when the vendor answers it — holiday-aware — falling back to a calendar-blind weekly-schedule computation only when it doesn't. Usually set while closed; may also be set while open, naming the open that follows the next close.
          x-order: 3
        next_close:
          type: string
          format: date-time
          nullable: true
          description: |
            Next scheduled venue close (RFC3339). Same venue-preferred, calendar-fallback sourcing as next_open. Under the calendar fallback this is set only while open, but the venue's own answer may report a next_close while the market currently reads closed too (e.g. a paused state) — callers should not infer "market is open" merely from this being present.
          x-order: 4
    StockMovers:
      type: object
      required:
        - gainers
        - losers
      properties:
        gainers:
          type: array
          items:
            $ref: '#/components/schemas/Stock'
          description: Sorted by change_24h_percent, highest first.
          x-order: 1
        losers:
          type: array
          items:
            $ref: '#/components/schemas/Stock'
          description: Sorted by change_24h_percent, lowest first.
          x-order: 2
    StockPosition:
      type: object
      required:
        - symbol
        - name
        - display_ticker
        - tokens
        - value
        - cost_basis
        - is_market_open
        - buy_supported
        - sell_supported
      properties:
        symbol:
          type: string
          example: AAPL
          x-order: 1
        name:
          type: string
          example: Apple
          x-order: 2
        display_ticker:
          type: string
          example: AAPL
          x-order: 3
        logo_url:
          allOf:
            - $ref: '#/components/schemas/UrlField'
          x-order: 4
        tokens:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: Token quantity held, 18 decimal places.
          x-order: 5
        price:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          description: Display (mid) token price; absent when no price is available.
          x-order: 6
        value:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          description: tokens times price; zero when there is no price.
          x-order: 7
        cost_basis:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          description: Total paid for the position under average-cost accounting.
          x-order: 8
        average_price:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          description: Average entry price (cost_basis / tokens); absent when there is no position.
          x-order: 9
        average_price_change:
          allOf:
            - $ref: '#/components/schemas/PriceChange'
          description: Change between current price and average entry price; absent when no position or unpriced.
          x-order: 10
        unrealized_pnl:
          allOf:
            - $ref: '#/components/schemas/PriceChange'
          description: All-time return; amount is total P&L, percent is return %. Absent when the position is unpriced.
          x-order: 11
        change_24h:
          allOf:
            - $ref: '#/components/schemas/PriceChange'
          description: 24h price change (absolute and percent); absent when no 24h history.
          x-order: 13
        is_market_open:
          type: boolean
          description: |
            Whether this stock's market is open right now, from the persisted book-meta snapshot (the inverse of its closed state, so it is off-hours aware). Falls back to the live venue observation until the first snapshot is written.
          x-order: 14
        buy_supported:
          type: boolean
          description: Whether a buy can be placed; tradeable symbol with the market open.
          x-order: 15
        sell_supported:
          type: boolean
          description: Whether a sell can be placed; tradeable symbol with the market open.
          x-order: 16
    StockPortfolio:
      type: object
      required:
        - positions
        - holdings_count
        - total_value
        - total_cost_basis
        - unrealized_pnl
        - unpriced_count
      properties:
        positions:
          type: array
          items:
            $ref: '#/components/schemas/StockPosition'
          x-order: 1
        holdings_count:
          type: integer
          x-order: 2
        total_value:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          description: Sum of every position valued at its display (mid) price.
          x-order: 3
        total_cost_basis:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          description: Total paid across every position, priced or not — a historical fact independent of today's feed.
          x-order: 4
        unrealized_pnl:
          allOf:
            - $ref: '#/components/schemas/PriceChange'
          description: Summed only across positions that currently have a price; amount is total P&L, percent is return %. See unpriced_count.
          x-order: 5
        unpriced_count:
          type: integer
          description: How many positions were excluded from unrealized_pnl for want of a current price. Zero means those totals are complete; caption them as partial otherwise.
          x-order: 6
    StockActivity:
      type: object
      required:
        - id
        - symbol
        - action
        - tokens
        - amount
        - unit_price
        - status
        - created_at
      properties:
        id:
          type: string
          example: SBE_1a2b3c
          x-order: 1
        symbol:
          type: string
          example: AAPL
          x-order: 2
        action:
          type: string
          enum:
            - buy
            - sell
          x-order: 3
        tokens:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 4
        amount:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          description: Settlement value of the fill.
          x-order: 5
        unit_price:
          allOf:
            - $ref: '#/components/schemas/AmountWithCurrency'
          description: Executed price per token, spread included.
          x-order: 6
        funding_currency:
          type: string
          example: NGN
          x-order: 7
        funding_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 8
        status:
          type: string
          enum:
            - completed
          example: completed
          x-order: 9
        created_at:
          type: string
          format: date-time
          x-order: 10
    StockPositionDetail:
      type: object
      required:
        - position
        - activities
      properties:
        position:
          $ref: '#/components/schemas/StockPosition'
        activities:
          type: array
          items:
            $ref: '#/components/schemas/StockActivity'
    StockDetail:
      allOf:
        - $ref: '#/components/schemas/Stock'
        - type: object
          properties:
            description:
              type: string
            isin:
              type: string
            buy_price:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
              description: Display buy price (token price plus spread).
            sell_price:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
            underlying_price:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
              description: Underlying stock market price. Informational only.
            shares_multiplier:
              allOf:
                - $ref: '#/components/schemas/Decimal'
              description: Shares represented by one token; drifts up as dividends reinvest.
            session:
              type: string
              enum:
                - premarket
                - regular
                - postmarket
                - overnight
                - offhours
                - paused
                - closed
            min_order:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
            max_order:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
            open_price:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
              description: |
                Opening price of the current daily candle. Absent when the daily chart has not been requested recently enough to be cached.
            range_24h_high:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
              description: Highest recorded price in the last 24h; absent without history.
            range_24h_low:
              allOf:
                - $ref: '#/components/schemas/AmountWithCurrency'
              description: Lowest recorded price in the last 24h; absent without history.
            following:
              type: boolean
              description: |
                Whether this symbol is on the authenticated profile's stock watchlist. Always false for anonymous (unauthenticated) requests.
    StockCandle:
      type: object
      required:
        - time
        - open
        - high
        - low
        - close
      properties:
        time:
          type: string
          format: date-time
        open:
          $ref: '#/components/schemas/Decimal'
        high:
          $ref: '#/components/schemas/Decimal'
        low:
          $ref: '#/components/schemas/Decimal'
        close:
          $ref: '#/components/schemas/Decimal'
    StockOHLC:
      type: object
      required:
        - symbol
        - period
        - candles
      properties:
        symbol:
          type: string
        period:
          type: string
          enum:
            - 1d
            - 1w
            - 1m
            - 1y
            - all
        candles:
          type: array
          items:
            $ref: '#/components/schemas/StockCandle'
    TransactionTypes:
      type: string
      description: transaction type
      enum:
        - buys
        - sells
        - converts
        - utilities
        - rewards
        - loans
        - savings
        - savings.withdrawals
        - savings.deposit
        - savings.interests
        - deposits
        - withdrawals
        - sends
        - receives
        - card_fees
    TransactionStatus:
      type: string
      description: Transaction status. `pending_review` indicates that the transaction requires manual review before completion.
      enum:
        - pending
        - pending_review
        - completed
        - failed
        - cancelled
        - processing
      example: completed
    TxnMetaConversion:
      type: object
      properties:
        source_currency:
          type: string
          description: Currency being converted from
        source_amount:
          $ref: '#/components/schemas/Decimal'
        target_currency:
          type: string
          description: Currency being converted to
        target_amount:
          $ref: '#/components/schemas/Decimal'
        rate:
          $ref: '#/components/schemas/Decimal'
        rate_explained:
          type: string
          description: Human readable rate explanation
    TxnMetaBankTransferSource:
      type: object
      description: Bank Transfer Source
      properties:
        bank_name:
          type: string
          description: Bank name
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        session_id:
          type: string
          description: Session ID
    TxnMetaMobileMoneySource:
      type: object
      description: Mobile Money Source
      properties:
        provider:
          type: string
          description: Provider Name
        phone_number:
          type: string
          description: Phone number
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        paybill:
          type: string
          description: Paybill number
        till_number:
          type: string
          description: Till number
    TxnMetaUsernameSource:
      type: object
      description: Username Source
      properties:
        username:
          type: string
          description: Username
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaEmailSource:
      type: object
      description: Email Source
      properties:
        email:
          type: string
          description: Email
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaCryptoWalletSource:
      type: object
      description: Crypto Wallet Source
      properties:
        network_name:
          type: string
          description: Network name
        network_currency:
          type: string
          description: Network currency
        address:
          type: string
          description: Wallet address
        destination_tag:
          type: string
          description: Destination tag
        confirmations:
          type: string
          format: integer
          description: Number of confirmations
        hash:
          type: string
          description: Transaction hash
        blockchain_url:
          type: string
          description: Blockchain URL
        address_url:
          type: string
          description: Address URL
    TxnMetaBankTransferDestination:
      type: object
      description: Bank Transfer Destination
      properties:
        bank_name:
          type: string
          description: Bank name
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        session_id:
          type: string
          description: Session ID
    TxnMetaWireTransferDestination:
      type: object
      description: Wire transfer Destination
      properties:
        bank_name:
          type: string
          description: Bank name
        swift_code:
          type: string
          description: SWIFT code
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        imad:
          type: string
          description: IMAD
        routing_number:
          type: string
          description: Routing number
        address:
          type: string
          description: Address
    TxnMetaMobileMoneyDestination:
      type: object
      description: Mobile Money Destination
      properties:
        provider:
          type: string
          description: Provider Name
        phone_number:
          type: string
          description: Phone number
        account_number:
          type: string
          description: Account number
        account_name:
          type: string
          description: Account name
        paybill:
          type: string
          description: Paybill number
        till_number:
          type: string
          description: Till number
    TxnMetaUsernameDestination:
      type: object
      description: Username Destination
      properties:
        username:
          type: string
          description: Username
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
    TxnMetaEmailDestination:
      type: object
      description: Email Destination
      properties:
        email:
          type: string
          description: Email
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
        message:
          type: string
          description: Note from the sender to the recipient (gifted vouchers)
          example: Happy birthday Ada!
    TxnMetaCryptoWalletDestination:
      type: object
      description: Crypto Wallet Destination
      properties:
        network_name:
          type: string
          description: Network name
        network_currency:
          type: string
          description: Network currency
        address:
          type: string
          description: Wallet address
        destination_tag:
          type: string
          description: Destination tag
        hash:
          type: string
          description: Transaction hash
        blockchain_url:
          type: string
          description: Blockchain URL
        address_url:
          type: string
          description: Address URL
    TxnMetaSaving:
      type: object
      description: Savings details
      properties:
        action:
          type: string
          description: Savings action type
          enum:
            - deposit
            - withdrawal
            - interest
        id:
          type: string
          description: Savings plan identifier
    TxnMetaService:
      type: object
      description: Service details (for utility transactions)
      properties:
        type:
          type: string
          description: Service type
          enum:
            - airtime
            - data
            - bills
            - voucher
            - betting
            - electricity
            - cable
            - card
        phone_number:
          type: string
          description: Phone number (for airtime)
        network:
          type: string
          description: Network provider
        merchant:
          type: string
          description: Merchant name (for vouchers)
        amount:
          $ref: '#/components/schemas/Decimal'
        logo_url:
          type: string
          format: uri
          description: Logo URL for the service provider
        meter_no:
          type: string
          description: Meter number (for electricity)
        account_type:
          type: string
          description: Meter account type, e.g. prepaid/postpaid (for electricity)
        smartcard_no:
          type: string
          description: Smartcard number (for cable)
        plan_name:
          type: string
          description: Subscription plan name (for cable)
        bundle:
          type: string
          description: Data bundle name (for data)
        account_no:
          type: string
          description: Account number on the biller platform (for betting)
        recipient_email:
          type: string
          description: Recipient email address (for voucher delivery)
        account_name:
          type: string
          description: Account name returned by recipient validation (for electricity, cable, betting)
        account_address:
          type: string
          description: Account address returned by recipient validation (for electricity)
    TxnMetaFee:
      type: object
      description: Fee details
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        currency:
          type: string
          description: Currency of fee
    TxnMetaDepositAmounts:
      type: object
      properties:
        amount_paid:
          $ref: '#/components/schemas/Decimal'
        amount_added:
          $ref: '#/components/schemas/Decimal'
    TxnMetaPayoutAmounts:
      type: object
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        total:
          $ref: '#/components/schemas/Decimal'
    TxnMetaAmounts:
      description: Transactions amounts explained
      allOf:
        - type: object
          properties:
            fee:
              $ref: '#/components/schemas/Decimal'
        - oneOf:
            - $ref: '#/components/schemas/TxnMetaDepositAmounts'
            - $ref: '#/components/schemas/TxnMetaPayoutAmounts'
    TxnMetaMoneyAmount:
      type: object
      description: Decimal amount paired with its currency code
      properties:
        amount:
          $ref: '#/components/schemas/Decimal'
        currency:
          type: string
    TxnMetaCardCharge:
      type: object
      description: |
        Multi-currency breakdown for a card spend so the detail screen can
        render merchant local + card billing + funding amounts and the
        applicable network/platform rates without joining back to provider
        data.
      properties:
        card_scheme:
          type: string
          description: Card scheme, e.g. mastercard, visa
        card_last4:
          type: string
          description: Last four digits of the card PAN
        merchant:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: What the merchant charged in their local currency
        billing:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: What the card network billed the card after network FX
        funding:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: What was debited from the user's funding wallet
        fee:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: Provider-charged fee in billing currency. Omitted when zero.
        total:
          allOf:
            - $ref: '#/components/schemas/TxnMetaMoneyAmount'
          description: billing + fee, in billing currency
        rate:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          description: |
            The exchange rate we applied at the time of the charge
            (funding / billing). Omitted when funding currency matches
            billing currency.
        formatted_rate:
          type: string
          description: |
            Human-readable form of `rate`, e.g. "1 USD = 1,350.05 NGN".
            Omitted when `rate` is omitted.
    TransactionMeta:
      type: object
      description: Additional transaction metadata
      required:
        - price
        - balance
      properties:
        conversion:
          $ref: '#/components/schemas/TxnMetaConversion'
        price:
          type: object
          properties:
            amount:
              $ref: '#/components/schemas/Decimal'
            currency:
              type: string
              description: Fiat currency of user
        balance:
          type: object
          properties:
            total:
              $ref: '#/components/schemas/Decimal'
            available:
              $ref: '#/components/schemas/Decimal'
        source:
          type: object
          description: Source details (for deposits, receives)
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - bank_transfer
                    - mobile_money
                    - username
                    - email
                    - wallet
            - oneOf:
                - $ref: '#/components/schemas/TxnMetaBankTransferSource'
                - $ref: '#/components/schemas/TxnMetaMobileMoneySource'
                - $ref: '#/components/schemas/TxnMetaUsernameSource'
                - $ref: '#/components/schemas/TxnMetaEmailSource'
                - $ref: '#/components/schemas/TxnMetaCryptoWalletSource'
        destination:
          type: object
          description: Destination details (for withdraws, sends)
          allOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - bank_transfer
                    - wire_transfer
                    - mobile_money
                    - paybill
                    - till
                    - username
                    - email
                    - wallet
            - oneOf:
                - $ref: '#/components/schemas/TxnMetaBankTransferDestination'
                - $ref: '#/components/schemas/TxnMetaWireTransferDestination'
                - $ref: '#/components/schemas/TxnMetaMobileMoneyDestination'
                - $ref: '#/components/schemas/TxnMetaUsernameDestination'
                - $ref: '#/components/schemas/TxnMetaEmailDestination'
                - $ref: '#/components/schemas/TxnMetaCryptoWalletDestination'
        savings:
          $ref: '#/components/schemas/TxnMetaSaving'
        service:
          $ref: '#/components/schemas/TxnMetaService'
        third_party_reference:
          type: string
          description: Reference from external payment service i.e till, paybill, mobile_money
        fee:
          $ref: '#/components/schemas/TxnMetaFee'
        amounts:
          $ref: '#/components/schemas/TxnMetaAmounts'
        card_charge:
          $ref: '#/components/schemas/TxnMetaCardCharge'
    Transaction:
      type: object
      required:
        - id
        - object
        - status
        - created_at
        - reference
        - user_id
        - profile_id
        - type
        - description
        - sub_description
        - amount
        - currency
        - is_fiat
        - is_credit
        - status_description
      properties:
        id:
          x-order: 1
          allOf:
            - $ref: '#/components/schemas/ID'
        object:
          x-order: 2
          type: string
          description: Type of the object
          example: transaction
        status:
          x-order: 3
          allOf:
            - $ref: '#/components/schemas/TransactionStatus'
          example: completed
        created_at:
          x-order: 4
          type: string
          format: date-time
          description: Timestamp when the transaction was created
          example: '2024-05-16T13:06:31.409336+01:00'
        reference:
          x-order: 5
          type: string
          description: transaction reference
          example: ORD_7ain6FEDWB
        user_id:
          x-order: 6
          allOf:
            - $ref: '#/components/schemas/ID'
        profile_id:
          x-order: 7
          allOf:
            - $ref: '#/components/schemas/ID'
        type:
          x-order: 8
          allOf:
            - $ref: '#/components/schemas/TransactionTypes'
          example: buys
        description:
          x-order: 9
          type: string
          description: transaction description
          example: Bought US Dollar
        sub_description:
          x-order: 10
          type: string
          description: transaction sub_description
          example: With USD Token
        amount:
          x-order: 11
          allOf:
            - $ref: '#/components/schemas/Decimal'
        currency:
          x-order: 12
          allOf:
            - $ref: '#/components/schemas/Currency'
        is_fiat:
          x-order: 13
          type: boolean
          description: tells if transaction is in a fiat currency
        is_credit:
          x-order: 14
          type: boolean
          description: tells if transaction is a credit
        meta:
          x-order: 15
          allOf:
            - $ref: '#/components/schemas/TransactionMeta'
        status_description:
          x-order: 16
          type: string
          description: transaction status_description
          example: This has been processed by Busha
    TransactionsListResponse:
      allOf:
        - $ref: '#/components/schemas/CursorPagination'
        - type: object
          properties:
            data:
              type: array
              description: List of recipients
              items:
                $ref: '#/components/schemas/Transaction'
          required:
            - data
    TransferStatus:
      type: string
      description: Status of a transfer
      enum:
        - pending
        - processing
        - cancelled
        - funds_converted
        - funds_received
        - outgoing_payment_sent
        - funds_delivered
        - funds_not_delivered
        - funds_refunded
        - reverse_fund_conversion
    TransferPayInObj:
      allOf:
        - $ref: '#/components/schemas/PaymentObj'
        - type: object
          properties:
            payer_details:
              $ref: '#/components/schemas/RecipientDetails'
    Transfer:
      type: object
      required:
        - id
        - quote_id
        - description
        - sub_description
        - source_currency
        - target_currency
        - source_amount
        - target_amount
        - profile_id
        - created_at
        - updated_at
        - status
        - rate
        - fees
      properties:
        id:
          $ref: '#/components/schemas/ResourceID'
        quote_id:
          $ref: '#/components/schemas/NanoID'
        reference:
          $ref: '#/components/schemas/QuoteReference'
        stages:
          type: array
          description: Ordered pipeline steps included in the transfer flow.
          example:
            - deposit
            - conversion
          items:
            type: string
            enum:
              - deposit
              - conversion
              - withdrawal
          x-order: 2
        category:
          type: string
          description: Computed shorthand derived from the transfer stages.
          example: buy
          enum:
            - deposit
            - withdrawal
            - conversion
            - buy
            - sell
            - send
            - exchange
          x-order: 3
        description:
          type: string
          example: Bought Bitcoin
          x-order: 4
        sub_description:
          type: string
          example: With Naira
          x-order: 5
        source_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 6
        target_currency:
          allOf:
            - $ref: '#/components/schemas/Currency'
          x-order: 7
        source_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 8
        target_amount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
          x-order: 9
        trade:
          type: string
          example: buy
          x-order: 10
        profile_id:
          $ref: '#/components/schemas/NanoID'
        rate:
          allOf:
            - $ref: '#/components/schemas/QuoteRate'
          x-order: 11
        fees:
          type: array
          x-order: 12
          items:
            $ref: '#/components/schemas/Fee'
        pay_in:
          allOf:
            - $ref: '#/components/schemas/TransferPayInObj'
          x-order: 13
        pay_out:
          allOf:
            - $ref: '#/components/schemas/PaymentObj'
          x-order: 14
        status:
          allOf:
            - $ref: '#/components/schemas/TransferStatus'
          x-order: 15
        timeline:
          allOf:
            - $ref: '#/components/schemas/TransferTimeline'
          x-order: 16
        expires_at:
          type: string
          x-order: 17
          format: date-time
          example: '2023-12-01T15:04:05Z'
        created_at:
          type: string
          x-order: 18
          format: date-time
          example: '2023-10-15T12:15:30Z'
        updated_at:
          type: string
          x-order: 19
          format: date-time
          example: '2023-10-15T12:20:45Z'
    CreateTransferRequest:
      type: object
      required:
        - quote_id
      properties:
        quote_id:
          $ref: '#/components/schemas/NanoID'
  parameters:
    ProfileHeader:
      in: header
      name: X-BU-PROFILE-ID
      required: false
      description: User profile header
      schema:
        type: string
        example: BUS_YOK8tp5Zga01qOKEsqp07
    XBuPublicKey:
      in: header
      name: X-BU-PUBLIC-KEY
      required: false
      schema:
        type: string
        example: pub_uibaidu930ani
    CurrencyType:
      name: type
      in: query
      schema:
        type: array
        items:
          type: string
          enum:
            - fiat
            - crypto
            - stablecoin
      style: form
      example: fiat
      explode: false
    SortQueryParam:
      name: sort
      in: query
      description: The order to sort the results
      schema:
        type: string
        enum:
          - asc
          - desc
        example: asc
    CurrencyCodePathParam:
      name: code
      in: path
      required: true
      description: The currency path parameter
      schema:
        type: string
        example: BTC
        x-go-type: string
    CursorQueryParams:
      name: cursor
      in: query
      description: The cursor
      schema:
        type: string
        format: string
    LimitQueryParam:
      name: limit
      in: query
      description: The number of items to return
      schema:
        type: integer
        example: 10
        x-go-type: uint64
    PathParamNanoID:
      in: path
      name: id
      required: true
      schema:
        type: string
        format: nanoid
        example: bus_123456789
      x-oapi-codegen-extra-tags:
        validate: required|nanoid
    InsightsCurrencyQueryParam:
      name: currency
      in: query
      required: true
      description: Currency to return insights for. Amounts are not converted across currencies.
      schema:
        type: string
        example: NGN
        x-oapi-codegen-extra-tags:
          validate: min_len:3|max_len:10
          filter: trim|upper
    InsightsStartDateQueryParam:
      name: start_date
      in: query
      required: false
      description: Start of the reporting range (inclusive, UTC). Defaults to 30 days before end_date.
      schema:
        type: string
        format: date
      example: '2026-06-15'
    InsightsEndDateQueryParam:
      name: end_date
      in: query
      required: false
      description: End of the reporting range (inclusive, UTC). Defaults to today.
      schema:
        type: string
        format: date
      example: '2026-07-15'
    InsightsIntervalQueryParam:
      name: interval
      in: query
      required: false
      description: Bucket size for the series. Defaults to day.
      schema:
        $ref: '#/components/schemas/InsightsInterval'
    CurrencyQueryParam:
      name: currency
      in: query
      required: false
      description: Filter by currency
      schema:
        type: array
        items:
          type: string
          x-oapi-codegen-extra-tags:
            validate: min_len:3|max_len:10
            filter: trim|upper
      style: form
      explode: false
    CountryQueryParam:
      name: country
      in: query
      x-oapi-codegen-extra-tags:
        validate: alpha2
        filter: trim|upper
      schema:
        type: string
    PaymentLinkTypeQueryParam:
      name: type
      in: query
      required: false
      style: form
      explode: false
      description: Filter by type (payment_link or invoice)
      schema:
        type: array
        items:
          $ref: '#/components/schemas/PaymentLinkType'
    PlatformIDInQueryParam:
      in: query
      name: id
      description: uuid and nano_id
      schema:
        type: array
        items:
          type: string
      style: form
      explode: false
      example: platform_123456
    PledgeIDParam:
      in: path
      name: id
      required: true
      description: Pledge ID
      schema:
        type: string
        example: PLG_01HX...
      x-oapi-codegen-extra-tags:
        validate: required
    LiquidationIDParam:
      in: path
      name: liquidation_id
      required: true
      description: Pledge liquidation ID
      schema:
        type: string
        example: PLR_01JB...
      x-oapi-codegen-extra-tags:
        validate: required
    X-BU-Version:
      in: header
      name: X-BU-Version
      description: The API version to use for this request.
      required: false
      schema:
        type: string
        default: '2025-07-11'
        example: '2025-07-11'
        enum:
          - '2025-06-01'
          - '2025-07-11'
    PathParamUUID:
      in: path
      name: id
      required: true
      schema:
        type: string
        format: uuid
        example: 550e8400-e29b-41d4-a716-446655440000
        x-go-type: string
      x-oapi-codegen-extra-tags:
        validate: required|uuid
    StockSymbolPathParam:
      name: symbol
      in: path
      required: true
      description: The stock's display ticker (e.g. AAPL), never the vendor symbol.
      schema:
        type: string
        example: AAPL
        x-oapi-codegen-extra-tags:
          filter: trim|upper
    StatusQueryParam:
      name: status
      in: query
      description: Filter by status (comma-separated)
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          $ref: '#/components/schemas/TransferStatus'
      example: funds_refunded,funds_converted
  examples:
    DefaultError:
      description: Default error
      value:
        error:
          name: bad_request
          message: Invalid request
    NotFoundError:
      description: Not Found error
      value:
        error:
          name: resource_not_found
          message: Resource Not Found
    UnAuthorizedError:
      description: Unauthorized Error
      value:
        error:
          name: unauthorized
          message: Unauthorized request
    RequestValidationError:
      description: Request Validation error example
      value:
        error:
          name: request_validation
          message: Validation error
        fields:
          field1:
            - reason: One of target and source amount must be set
          field2:
            - reason: One of target and source amount must be set
    SchemaValidationError:
      description: Schema validation error example
      value:
        error:
          name: schema_validation
          message: Error Validating Requests
        schema:
          - reason: The request body is defined as an object. However, it does not meet the schema requirements of the specification
            fix: Ensure that the object being submitted, matches the schema correctly
            schema_validation_error:
              - 'minLength: got 3, want 12'
    InternalServerError:
      description: Internal Server Error
      value:
        error:
          name: internal_server_error
          message: Internal Server Error
    ServiceUnavailableError:
      description: Service Unavailable Error
      value:
        error:
          name: service_unavailable
          message: Service Unavailable
  responses:
    BalanceError4XX:
      description: 409 error when a balance with the same currency already exists for a user
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    BalanceError5XX:
      description: Server error when processing the balance request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    CurrenciesError4XX:
      description: Error from customer resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    CurrenciesError5XX:
      description: Server error when processing the currencies request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    CustomerListResponse:
      description: Customer List Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/CursorPagination'
              - type: object
                required:
                  - pagination
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
    CustomerError4XX:
      description: Something went wrong in Customer resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    CustomerError5XX:
      description: Server error when processing the customers request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    CustomerResponse:
      description: Successful response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Customer'
    GeneralResponse:
      description: A general response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
    CustomerKYCLinkResponse:
      description: Successful response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerKYCLinkResponse'
    CustomerBusinessIndustries:
      description: Successful response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerBusinessIndustry'
    FilesError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    FilesError5XX:
      description: Server error when processing the miscellaneous request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    InsightsError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    InsightsError5XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    MiscellaneousError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    MiscellaneousError5XX:
      description: Server error when processing the miscellaneous request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    LookupResponses:
      description: Successful Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    description: List of Plans
                    items:
                      $ref: '#/components/schemas/LookUpResponseObject'
    MerchantResponse:
      x-internal: false
      description: Successful Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/MerchantObject'
    VirtualBankAccountResponse:
      description: Successful Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/VirtualBankAccount'
    VirtualBankAccountTermsResponse:
      description: Successful Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/VirtualBankAccountTerms'
    PairError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    PairError5XX:
      description: Server error when processing the pair request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    PaymentLinkError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    PaymentLinkError5XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    PaymentRequestError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    PaymentRequestError5XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    PledgeQuoteResponse:
      description: Successful pledge quote response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/PledgeQuote'
    PledgeError4XX:
      description: Client error when processing the pledge request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    PledgeError5XX:
      description: Server error when processing the pledge request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    PledgeListResponse:
      description: Successful pledge list response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/CursorPagination'
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pledge'
    PledgeResponse:
      description: Successful pledge response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Pledge'
    PledgeActionResponse:
      description: Successful pledge lifecycle action response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/PledgeAction'
    AddPledgeItemsResponse:
      description: Successful add pledge items response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/AddPledgeItemsResult'
    ReleasePledgeResponse:
      description: Successful pledge release response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/ReleasePledgeResult'
    PledgeLiquidationResponse:
      description: Successful pledge liquidation response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/PledgeLiquidation'
    CancelPledgeLiquidationResponse:
      description: Successful pledge liquidation cancellation response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/CancelPledgeLiquidationResult'
    QuotesListResponse:
      description: Quotes List Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/CursorPagination'
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Quote'
    QuoteError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    QuoteError5XX:
      description: Server error when processing the quote request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    QuoteResponse:
      description: Quote Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Quote'
    PaymentOptionsListResponse:
      description: Payment Options List Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentOptionObj'
    RecipientError4XX:
      description: Recipient Error sample
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    RecipientError5XX:
      description: Server error when processing the recipient request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    StocksError4XX:
      description: Error from customer resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    StocksError5XX:
      description: Server error when processing the stocks request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    TransactionsError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    TransactionsError5XX:
      description: Server error when processing the transaction request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    TransferListResponse:
      description: Transfer List Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/CursorPagination'
              - type: object
                properties:
                  data:
                    type: array
                    description: List of transfers
                    items:
                      $ref: '#/components/schemas/Transfer'
                required:
                  - data
    TransferError4XX:
      description: Default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            default:
              $ref: '#/components/examples/DefaultError'
            not_found_error:
              $ref: '#/components/examples/NotFoundError'
            unauthorized_error:
              $ref: '#/components/examples/UnAuthorizedError'
            request_validation_error:
              $ref: '#/components/examples/RequestValidationError'
            schema_validation_error:
              $ref: '#/components/examples/SchemaValidationError'
    TransferError5XX:
      description: Server error when processing the transfer request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internal_server_error:
              $ref: '#/components/examples/InternalServerError'
            service_unavailable_error:
              $ref: '#/components/examples/ServiceUnavailableError'
    TransferResponse:
      description: Transfer Response
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/BaseSchema'
              - type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Transfer'