---
openapi: 3.1.0
info:
  title: Lumetrade API
  description: |
    Lumetrade API documentation.

    The Lumetrade API gives third-party partners secure server-to-server access to Lumetrade
    accounts, wallets, currencies, beneficiaries, deposits, withdrawals, and trade data. Use this API
    to build operational dashboards, initiate supported money movement workflows, reconcile
    transactions, and surface account or wallet information in your own internal systems.

    This documentation describes the external `v1` API contract and the conventions your integration
    should follow from its first request through production use.

    ## Authentication and access

    API requests must include both `X-API-KEY` and `X-API-SECRET` headers. API keys are created
    through the authenticated user's API key management flow. The same user can revoke or rotate those
    credentials when needed. Treat the API secret as a server-side credential only; never expose it in
    browser, mobile, or other client-side code.

    Authentication and access failures are handled consistently across the external API:

    - `401` means the request could not be authenticated because API key headers are missing, invalid,
      revoked, or expired.
    - `403` means the request was authenticated, but the API key owner is not allowed to perform the
      action because of permissions, account state, or access rules.

    Individual endpoint documentation does not repeat these responses unless an endpoint has
    authentication or access behavior that differs from the standard API key flow.

    ## Currency and assets

    Supported currencies, assets, networks, and withdrawal rails are configuration-driven. When building
    forms or validation rules, use the relevant external, public, or user currency and payment route
    endpoints instead of hard-coding an asset list from this document. External account and currency
    endpoints are scoped to the API key owner's effective jurisdiction.

    ## Security

    Production and staging integrations must use HTTPS. Rotate API keys immediately if you suspect a
    secret has been exposed. Store secrets in a vault or server-side secret manager, and do not log full
    API secrets.

    ## Error model

    Error responses use Lumetrade's standard error envelope:

    ```json
    {
      "code": 1133,
      "message": "Validation error: amount is required",
      "httpStatus": 400,
      "requestId": "req_01HY...",
      "timestamp": "2026-01-01T00:00:00Z",
      "errors": [
        {
          "field": "amount",
          "message": "must be greater than 0"
        }
      ]
    }
    ```

    Common non-authentication error classes include `400` validation failures, `404` resources not found
    for the authenticated owner, `409` insufficient funds or conflicting money movement state, and `500`
    unexpected server errors.

    ## Pagination and filtering

    Current list endpoints may expose reserved query parameters for page, size, sort, date range, and
    status filters. Unless an endpoint explicitly says otherwise, current responses are unpaginated arrays
    and your integration should not depend on server-side pagination behavior yet.

    ## Transaction lifecycle

    Deposits, withdrawals, trades, and fills move through domain statuses such as pending, processing,
    completed, failed, cancelled, or reversed depending on the resource type. A status is final only when
    the specific endpoint and business flow represent it as terminal. Your integration should poll the
    read endpoints for status changes because webhooks are not currently documented for this API.
  contact:
    name: Lume Forge
  version: v1
servers:
- url: https://api.lumetrade.com
tags:
- name: Beneficiaries
  description: Beneficiary endpoints for the authenticated API key owner.
- name: Withdrawals
  description: Withdrawal history endpoints for the authenticated API key owner.
- name: Trades
  description: Trade history endpoints for the authenticated API key owner.
- name: Accounts
  description: Account endpoints for the authenticated API key owner.
- name: Deposits
  description: Deposit history endpoints for the authenticated API key owner.
- name: Wallets
  description: Wallet endpoints for the authenticated API key owner.
- name: Currencies
  description: Currency catalog endpoints for the authenticated API key owner.
paths:
  "/api/v1/trades/quote":
    post:
      tags:
      - Trades
      summary: Get trade quote
      description: Requests an RFQ quote for the authenticated API key owner.
      operationId: getQuote
      parameters:
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExternalRequestRFQQuoteRequest"
            examples:
              Quote by send amount:
                summary: Request a quote using fromAmount
                description: Quote by send amount
                value:
                  fromAmount: 100
                  fromCurrency: USDT
                  toCurrency: ZAR
                  quoteIntent: client_linked
              Quote by receive amount:
                summary: Request a quote using toAmount
                description: Quote by receive amount
                value:
                  toAmount: 1840
                  fromCurrency: USDT
                  toCurrency: ZAR
                  quoteIntent: client_linked
        required: true
      responses:
        '200':
          description: Quote returned successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Quote request validation failed
          content:
            application/json:
              schema:
                type: object
  "/api/v1/trades/quote/confirm":
    post:
      tags:
      - Trades
      summary: Confirm trade quote
      description: Confirms a previously issued RFQ quote for the authenticated API
        key owner.
      operationId: confirmQuote
      parameters:
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExternalAcceptRFQQuoteRequest"
            examples:
              Confirm by send amount:
                summary: Confirm using fromAmount
                description: Confirm by send amount
                value:
                  fromAmount: 100
                  fromCurrency: USDT
                  toCurrency: ZAR
                  quoteStr: rfq_quote_7K9Q2M
              Confirm by receive amount:
                summary: Confirm using toAmount
                description: Confirm by receive amount
                value:
                  toAmount: 1840
                  fromCurrency: USDT
                  toCurrency: ZAR
                  quoteStr: rfq_quote_7K9Q2M
        required: true
      responses:
        '200':
          description: Quote confirmed successfully
          content:
            application/json:
              examples:
                Confirmed trade by send amount:
                  summary: Trade response returned after confirming a fromAmount quote
                  description: Confirmed trade by send amount
                  value:
                    fromCurrency: USDT
                    toCurrency: ZAR
                    fromAmount: 100
                    toAmount: 1840
                    rate: 18.4
                    isRateInverted: false
                    isRfq: true
                    status: COMPLETED
                    transactionId: TID4J7K2N
                    createdAt: '2026-05-11T10:15:30Z'
                    completedAt: '2026-05-11T10:15:35'
                Confirmed trade by receive amount:
                  summary: Trade response returned after confirming a toAmount quote
                  description: Confirmed trade by receive amount
                  value:
                    fromCurrency: USDT
                    toCurrency: ZAR
                    fromAmount: 100
                    toAmount: 1840
                    rate: 18.4
                    isRateInverted: false
                    isRfq: true
                    status: COMPLETED
                    transactionId: TID4J7K2N
                    createdAt: '2026-05-11T10:15:30Z'
                    completedAt: '2026-05-11T10:15:35'
        '400':
          description: Quote confirmation validation failed
          content:
            application/json:
              schema:
                type: object
  "/api/v1/beneficiaries/withdrawals":
    post:
      tags:
      - Beneficiaries
      summary: Create beneficiary withdrawal
      description: Creates a withdrawal using only the saved details from an existing
        confirmed beneficiary.
      operationId: createWithdrawal
      parameters:
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateBeneficiaryWithdrawalRequest"
        required: true
      responses:
        '201':
          description: Withdrawal created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateWithdrawalResponse"
        '400':
          description: Withdrawal request is invalid
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateWithdrawalResponse"
        '404':
          description: Beneficiary was not found for the authenticated user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CreateWithdrawalResponse"
  "/api/v1/accounts":
    get:
      tags:
      - Accounts
      summary: List accounts
      description: Returns accounts belonging to the authenticated API key owner for
        currencies enabled in the owner's effective jurisdiction.
      operationId: getAccounts
      parameters:
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Accounts returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/ExternalAccountResponse"
    post:
      tags:
      - Accounts
      summary: Create account
      description: Creates an account for the authenticated API key owner only when
        the requested currency is enabled in the owner's effective jurisdiction.
      operationId: createAccount
      parameters:
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ExternalCreateAccountRequest"
        required: true
      responses:
        '201':
          description: Account created successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExternalAccountResponse"
        '400':
          description: Request validation failed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExternalAccountResponse"
        '404':
          description: Currency is not supported for this user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExternalAccountResponse"
        '409':
          description: Account already exists
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExternalAccountResponse"
  "/api/v1/withdrawals":
    get:
      tags:
      - Withdrawals
      summary: List withdrawals
      description: Returns the authenticated user's withdrawal history. Pagination,
        sorting, date filtering, and status filtering parameters are reserved for
        this list endpoint; current responses remain unpaginated until server-side
        pagination is enabled.
      operationId: getWithdrawHistory
      parameters:
      - name: page
        in: query
        description: Page number, zero-based.
        required: false
        schema:
          type: integer
          format: int32
        example: 0
      - name: size
        in: query
        description: 'Page size. Planned maximum: 100.'
        required: false
        schema:
          type: integer
          format: int32
        example: 50
      - name: sort
        in: query
        description: 'Sort expression: field,direction.'
        required: false
        schema:
          type: string
        example: completedAt,desc
      - name: dateFrom
        in: query
        description: Reserved inclusive lower timestamp bound.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-01-01T00:00:00Z'
      - name: dateTo
        in: query
        description: Reserved inclusive upper timestamp bound.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-01-31T23:59:59Z'
      - name: status
        in: query
        description: Reserved withdrawal status filter.
        required: false
        schema:
          type: string
        example: COMPLETED
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Withdrawals returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/WithdrawResponse"
  "/api/v1/withdrawals/{transactionId}":
    get:
      tags:
      - Withdrawals
      summary: Get withdrawal
      description: Returns a single withdrawal belonging to the authenticated API
        key owner.
      operationId: getWithdraw
      parameters:
      - name: transactionId
        in: path
        description: Withdrawal transaction id returned by the withdrawal list endpoint.
        required: true
        schema:
          type: string
        example: wd_5M8Q1P
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Withdrawal returned successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WithdrawResponse"
        '404':
          description: Withdrawal was not found for the authenticated user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WithdrawResponse"
  "/api/v1/wallets":
    get:
      tags:
      - Wallets
      summary: List wallets
      description: Returns wallets belonging to the authenticated API key owner.
      operationId: getWallets
      parameters:
      - name: paymentMethodType
        in: query
        description: Optional payment method type filter for fiat wallets.
        required: false
        schema:
          type: string
        example: EFT
      - name: networkName
        in: query
        description: Optional network name filter for crypto wallets.
        required: false
        schema:
          type: string
        example: Ethereum (ETH)
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Wallets returned successfully
          content:
            application/json:
              examples:
                Fiat virtual EFT wallet:
                  summary: Fiat wallet with user-specific EFT bank account details
                  description: Fiat virtual EFT wallet
                  value:
                  - id: wal_3Q8M1K
                    currency: ZAR
                    depositDetails:
                      bankName: Nedbank
                      accountName: Example Customer
                      accountNumber: '9876543210'
                      accountType: Current
                      branchCode: '198765'
                    networkName:
                    paymentMethodType: EFT
                Crypto wallet:
                  summary: Crypto wallet with blockchain address deposit details
                  description: Crypto wallet
                  value:
                  - id: wal_7K9Q2M
                    currency: BTC
                    depositDetails:
                      address: bc1qexample...
                      address_tag: '123456'
                    networkName: Bitcoin
                    paymentMethodType:
  "/api/v1/wallets/{walletId}":
    get:
      tags:
      - Wallets
      summary: Get wallet
      description: Returns one wallet belonging to the authenticated API key owner.
      operationId: getWallet
      parameters:
      - name: walletId
        in: path
        description: Wallet id returned by the wallet list endpoint.
        required: true
        schema:
          type: string
        example: wal_3Q8M1K
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Wallet returned successfully
          content:
            application/json:
              examples:
                Fiat virtual EFT wallet:
                  summary: Fiat wallet with user-specific EFT bank account details
                  description: Fiat virtual EFT wallet
                  value:
                    id: wal_3Q8M1K
                    currency: ZAR
                    depositDetails:
                      bankName: Nedbank
                      accountName: Example Customer
                      accountNumber: '9876543210'
                      accountType: Current
                      branchCode: '198765'
                    networkName:
                    paymentMethodType: EFT
                Crypto wallet:
                  summary: Crypto wallet with blockchain address deposit details
                  description: Crypto wallet
                  value:
                    id: wal_7K9Q2M
                    currency: BTC
                    depositDetails:
                      address: bc1qexample...
                      address_tag: '123456'
                    networkName: Bitcoin
                    paymentMethodType:
        '404':
          description: Wallet was not found for the authenticated user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/WalletResponse"
  "/api/v1/trades":
    get:
      tags:
      - Trades
      summary: List trades
      description: Returns the authenticated user's trade history, including any fills
        linked to each trade. Pagination, sorting, date filtering, and status filtering
        parameters are reserved for this list endpoint; current responses remain unpaginated
        until server-side pagination is enabled.
      operationId: tradeHistory
      parameters:
      - name: page
        in: query
        description: Page number
        required: false
        schema:
          type: integer
          format: int32
        example: 0
      - name: size
        in: query
        description: Page size
        required: false
        schema:
          type: integer
          format: int32
        example: 50
      - name: sort
        in: query
        description: 'Sort expression: field,direction.'
        required: false
        schema:
          type: string
        example: completedAt,desc
      - name: dateFrom
        in: query
        description: Lower timestamp bound.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-01-01T00:00:00Z'
      - name: dateTo
        in: query
        description: Upper timestamp bound.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-01-31T23:59:59Z'
      - name: status
        in: query
        description: Trade status filter.
        required: false
        schema:
          type: string
        example: COMPLETED
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Trades returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/TradeResponse"
  "/api/v1/trades/{transactionId}":
    get:
      tags:
      - Trades
      summary: Get trade
      description: Returns a single trade belonging to the authenticated API key owner.
      operationId: getTrade
      parameters:
      - name: transactionId
        in: path
        description: Trade transaction id returned by the trade list endpoint.
        required: true
        schema:
          type: string
        example: TID4J7K2N
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Trade returned successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TradeResponse"
        '404':
          description: Trade was not found for the authenticated user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/TradeResponse"
  "/api/v1/deposits":
    get:
      tags:
      - Deposits
      summary: List deposits
      description: Returns the authenticated user's deposit history. Pagination, sorting,
        date filtering, and status filtering parameters are reserved for this list
        endpoint; current responses remain unpaginated until server-side pagination
        is enabled.
      operationId: depositHistory
      parameters:
      - name: page
        in: query
        description: Page number, zero-based.
        required: false
        schema:
          type: integer
          format: int32
        example: 0
      - name: size
        in: query
        description: 'Page size. Planned maximum: 100.'
        required: false
        schema:
          type: integer
          format: int32
        example: 50
      - name: sort
        in: query
        description: 'Sort expression: field,direction.'
        required: false
        schema:
          type: string
        example: completedAt,desc
      - name: dateFrom
        in: query
        description: Lower timestamp bound.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-01-01T00:00:00Z'
      - name: dateTo
        in: query
        description: Upper timestamp bound.
        required: false
        schema:
          type: string
          format: date-time
        example: '2026-01-31T23:59:59Z'
      - name: status
        in: query
        description: Deposit status filter.
        required: false
        schema:
          type: string
        example: COMPLETED
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deposits returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/DepositResponse"
  "/api/v1/deposits/{transactionId}":
    get:
      tags:
      - Deposits
      summary: Get deposit
      description: Returns a single deposit belonging to the authenticated API key
        owner.
      operationId: getDeposit
      parameters:
      - name: transactionId
        in: path
        description: Deposit Transaction id returned by the deposit list endpoint.
        required: true
        schema:
          type: string
        example: dep_9H2K7P
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deposit returned successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/DepositResponse"
        '404':
          description: Deposit was not found for the authenticated user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/DepositResponse"
  "/api/v1/currencies":
    get:
      tags:
      - Currencies
      summary: List currencies
      description: Returns enabled currencies for the authenticated API key owner's
        effective jurisdiction.
      operationId: getCurrencies
      parameters:
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Currencies returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/ExternalCurrencyResponse"
  "/api/v1/beneficiaries":
    get:
      tags:
      - Beneficiaries
      summary: List beneficiaries
      description: Returns confirmed beneficiaries belonging to the authenticated
        API key owner.
      operationId: getBeneficiaries
      parameters:
      - name: currency
        in: query
        description: Optional beneficiary currency code filter.
        required: false
        schema:
          type: string
        example: ZAR
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Beneficiaries returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/BeneficiaryResponse"
  "/api/v1/beneficiaries/{beneficiaryId}":
    get:
      tags:
      - Beneficiaries
      summary: Get beneficiary
      description: Returns a confirmed beneficiary belonging to the authenticated
        API key owner.
      operationId: getBeneficiary
      parameters:
      - name: beneficiaryId
        in: path
        description: Beneficiary id returned by the beneficiary list endpoint.
        required: true
        schema:
          type: string
        example: ben_7K9Q2M
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Beneficiary returned successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BeneficiaryResponse"
        '404':
          description: Beneficiary was not found for the authenticated user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/BeneficiaryResponse"
  "/api/v1/accounts/{accountId}":
    get:
      tags:
      - Accounts
      summary: Get account
      description: Returns one account belonging to the authenticated API key owner
        when its currency is enabled in the owner's effective jurisdiction.
      operationId: getAccount
      parameters:
      - name: accountId
        in: path
        description: Account id returned by the account list endpoint.
        required: true
        schema:
          type: string
        example: acc_8F4J2N
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Account returned successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExternalAccountResponse"
        '404':
          description: Account was not found for the authenticated user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExternalAccountResponse"
  "/api/v1/accounts/currency/{currency}":
    get:
      tags:
      - Accounts
      summary: Get account by currency
      description: Returns one account belonging to the authenticated API key owner
        for the requested currency when that currency is enabled in the owner's effective
        jurisdiction.
      operationId: getAccountByCurrency
      parameters:
      - name: currency
        in: path
        description: Currency for the account lookup.
        required: true
        schema:
          type: string
        example: ZAR
      - name: X-API-KEY
        in: header
        description: Public API key issued from the Lumetrade API key management flow.
        required: true
        schema:
          type: string
      - name: X-API-SECRET
        in: header
        description: API secret paired with the public API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Account returned successfully
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExternalAccountResponse"
        '404':
          description: Account or currency was not found for the authenticated user
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ExternalAccountResponse"
components:
  schemas:
    ExternalRequestRFQQuoteRequest:
      type: object
      properties:
        fromAmount:
          type: number
          description: How much the customer wants to send or pay. Provide either
            fromAmount or toAmount, not both.
          example: 100
        toAmount:
          type: number
          description: How much the customer wants to receive. Provide either toAmount
            or fromAmount, not both.
          example: 1840
        fromCurrency:
          type: string
          description: Currency the customer is sending or paying with.
          example: USDT
        toCurrency:
          type: string
          description: Currency the customer wants to receive.
          example: ZAR
        quoteIntent:
          type: string
          description: Use client_linked when the customer may confirm this quote.
            Use indicative when the customer only needs a preview price.
          enum:
          - indicative
          - client_linked
          example: client_linked
          pattern: "(?i)indicative|client_linked"
    ExternalAcceptRFQQuoteRequest:
      type: object
      properties:
        fromAmount:
          type: number
          description: Amount the customer sends or pays from the quote response.
            Provide either fromAmount or toAmount, not both.
          example: 100
        toAmount:
          type: number
          description: Amount the customer receives from the quote response. Provide
            either toAmount or fromAmount, not both.
          example: 1840
        fromCurrency:
          type: string
          description: Currency the customer sends or pays with.
          example: USDT
        quoteStr:
          type: string
          description: Quote reference returned by /api/v1/trades/quote.
          example: rfq_quote_7K9Q2M
        toCurrency:
          type: string
          description: Currency the customer receives.
          example: ZAR
    CreateBeneficiaryWithdrawalRequest:
      type: object
      description: Request to create a withdrawal from a beneficiary.
      properties:
        beneficiaryId:
          type: string
          description: Beneficiary id returned by the beneficiary endpoints.
          example: ben_7K9Q2M
        amount:
          type: number
          description: Withdrawal amount in the beneficiary currency.
          example: 101
      required:
      - amount
    CreateWithdrawalResponse:
      type: object
      description: Withdrawal creation response returned by the API.
      properties:
        transactionId:
          type: string
          description: Created withdrawal transaction id.
          example: WD5M8Q1P
        status:
          type: string
          description: Created withdrawal status.
          enum:
          - PENDING
          - ACCEPTED
          - AWAITING_CONFIRMATION
          - PROCESSING
          - COMPLIANCE_PENDING
          - COMPLETED
          - FAILED
          - CANCELLED
          - REVERSED
          example: PENDING
    ExternalCreateAccountRequest:
      type: object
      properties:
        currency:
          type: string
          description: Currency code for the account to create.
          example: ZAR
    ExternalAccountResponse:
      type: object
      properties:
        id:
          type: string
          description: Account id used by external account endpoints.
          example: acc_8F4J2N
        currency:
          type: string
          description: Account currency.
          example: ZAR
        balance:
          type: number
          description: Available account balance.
          example: 2500
        lockedBalance:
          type: number
          description: Locked account balance.
          example: 0
    JsonNode:
      type: object
      additionalProperties: true
      description: Raw withdrawal details stored as JSON object.
      example:
        bankName: FNB
        accountNumber: '1234567890'
      properties:
        pojo:
          type: boolean
        int:
          type: boolean
        double:
          type: boolean
        bigDecimal:
          type: boolean
        bigInteger:
          type: boolean
        nodeType:
          type: string
          enum:
          - ARRAY
          - BINARY
          - BOOLEAN
          - MISSING
          - 'NULL'
          - NUMBER
          - OBJECT
          - POJO
          - STRING
        container:
          type: boolean
        short:
          type: boolean
        long:
          type: boolean
        valueNode:
          type: boolean
        missingNode:
          type: boolean
        floatingPointNumber:
          type: boolean
        integralNumber:
          type: boolean
        string:
          type: boolean
        boolean:
          type: boolean
        object:
          type: boolean
        textual:
          type: boolean
          deprecated: true
        binary:
          type: boolean
        number:
          type: boolean
        array:
          type: boolean
        empty:
          type: boolean
        'null':
          type: boolean
        float:
          type: boolean
        embeddedValue:
          type: boolean
    WithdrawResponse:
      type: object
      description: Withdrawal transaction returned by the API.
      properties:
        amount:
          type: number
          description: Withdrawal amount.
          example: 101
        fee:
          type: number
          description: Withdrawal fee.
          example: 1
        currency:
          type: string
          description: Withdrawal currency code.
          example: ZAR
        withdrawDetails:
          "$ref": "#/components/schemas/JsonNode"
          additionalProperties: true
          description: Raw withdrawal details stored as JSON object.
          example:
            bankName: FNB
            accountNumber: '1234567890'
        status:
          type: string
          description: Withdrawal status.
          enum:
          - PENDING
          - ACCEPTED
          - AWAITING_CONFIRMATION
          - PROCESSING
          - COMPLIANCE_PENDING
          - COMPLETED
          - FAILED
          - CANCELLED
          - REVERSED
          example: COMPLETED
        transactionId:
          type: string
          description: Transaction id for withdrawal lookups.
          example: wd_5M8Q1P
        createdAt:
          type: string
          format: date-time
          description: Withdrawal creation timestamp.
          example: '2026-05-11T10:15:30Z'
        completedAt:
          type: string
          format: date-time
          description: Completion timestamp.
          example: '2026-05-11T10:20:30'
        isFiat:
          type: boolean
          description: Whether this withdrawal used a fiat route.
          example: true
    WalletResponse:
      type: object
      description: Wallet owned by the authenticated API key user.
      properties:
        id:
          type: string
          description: Stable wallet id used by external wallet endpoints.
          example: wal_3Q8M1K
        currency:
          type: string
          description: Wallet currency code.
          example: BTC
        depositDetails:
          "$ref": "#/components/schemas/JsonNode"
          additionalProperties: true
          description: Raw wallet deposit details stored as JSON object.
          example:
            address: bc1qexample...
            address_tag: '123456'
        networkName:
          type: string
          description: Crypto network name when available.
          example: Bitcoin
        paymentMethodType:
          type: string
          description: Fiat payment method type when available.
          example: EFT
    FillResponse:
      type: object
      description: Trade fill returned by the API.
      properties:
        fromCurrency:
          type: string
          description: Currency sent for this fill.
          example: USDT
        fromCurrencyAmount:
          type: number
          description: Amount sent for this fill.
          example: 100
        toCurrency:
          type: string
          description: Currency received for this fill.
          example: ZAR
        toCurrencyAmount:
          type: number
          description: Amount received for this fill.
          example: 1840
        status:
          type: string
          description: Fill status.
          enum:
          - COMPLETED
          - REVERSED
          example: COMPLETED
        transactionId:
          type: string
          description: Transaction id for this fill.
          example: fil_2N8K4Q
        modifiedAt:
          type: string
          format: date-time
          description: Last modified timestamp.
          example: '2026-05-11T10:15:35Z'
        createdAt:
          type: string
          format: date-time
          description: Fill creation timestamp.
          example: '2026-05-11T10:15:30Z'
    TradeResponse:
      type: object
      description: Trade transaction returned by the API.
      properties:
        fromCurrency:
          type: string
          description: Currency sold/sent.
          example: USDT
        toCurrency:
          type: string
          description: Currency bought/received.
          example: ZAR
        fromAmount:
          type: number
          description: Amount sold/sent.
          example: 100
        toAmount:
          type: number
          description: Amount bought/received.
          example: 1840
        rate:
          type: number
          description: Executed trade rate.
          example: 18.4
        isRateInverted:
          type: boolean
          description: Whether the displayed rate is inverted.
          example: false
        isRfq:
          type: boolean
          description: Whether this trade was created from RFQ.
          example: true
        status:
          type: string
          description: Trade status.
          enum:
          - PENDING
          - COMPLETED
          - CANCELLED
          - REVERSED
          example: COMPLETED
        transactionId:
          type: string
          description: Transaction id for trade lookups.
          example: trd_4J7K2N
        createdAt:
          type: string
          format: date-time
          description: Trade creation timestamp.
          example: '2026-05-11T10:15:30Z'
        completedAt:
          type: string
          format: date-time
          description: Completion timestamp.
          example: '2026-05-11T10:15:35'
        fills:
          type: array
          description: Trade fills. Omitted from RFQ quote confirmation responses.
          items:
            "$ref": "#/components/schemas/FillResponse"
    DepositResponse:
      type: object
      description: Deposit transaction returned by the API.
      properties:
        currency:
          type: string
          description: Deposit currency code.
          example: USDT
        transactionId:
          type: string
          description: Transaction id for deposit lookups.
          example: DP9H2K7P
        amount:
          type: number
          description: Deposit amount.
          example: 100
        fee:
          type: number
          description: Deposit fee.
          example: 0
        status:
          type: string
          description: Deposit status.
          enum:
          - SUBMITTED
          - PENDING
          - PROCESSING
          - COMPLIANCE_PENDING
          - COMPLETED
          - FAILED
          - CANCELLED
          - REVERSED
          example: COMPLETED
        completedAt:
          type: string
          format: date-time
          description: Completion timestamp.
          example: '2026-05-11T10:15:30'
    ExternalCurrencyResponse:
      type: object
      properties:
        currency:
          type: string
          description: Currency code.
          example: ZAR
        name:
          type: string
          description: Currency display name.
          example: South African Rand
    BeneficiaryResponse:
      type: object
      description: Beneficiary available to the authenticated API key user.
      properties:
        id:
          type: string
          description: Beneficiary id used by external beneficiary endpoints.
          example: ben_7K9Q2M
        currency:
          type: string
          description: Saved beneficiary currency.
          example: ZAR
        nickname:
          type: string
          description: Beneficiary nickname.
          example: FNB Savings
        withdrawFormDetails:
          "$ref": "#/components/schemas/JsonNode"
          additionalProperties: true
          description: Saved withdrawal form details for the beneficiary.
          example:
            bankName: FNB
            accountNumber: '1234567890'
            accountHolderName: Jane Example
        createdAt:
          type: string
          format: date-time
          description: Beneficiary creation timestamp.
          example: '2026-05-11T10:15:30Z'