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

# FX Rate

> Returns a live indicative exchange rate and fee breakdown.




## OpenAPI

````yaml GET /v1/fx/convert
openapi: 3.0.3
info:
  title: Stablepay Money API
  description: >
    The Stablepay Money API enables wallet issuers to execute stablecoin-to-fiat

    payouts across Sub-Saharan Africa via M-Pesa, mobile money, and bank
    transfers.
  version: 0.5.0
  contact:
    name: Stablepay Engineering
    email: hello@stablepay.io
servers:
  - url: https://api.stablepay.ai
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Health
    description: Service liveness check.
  - name: FX
    description: Live FX rate conversion between USDC and local fiat currencies.
  - name: Payments
    description: Submit and track stablecoin-to-fiat payout requests.
  - name: Balances
    description: >-
      Live on-chain USDC and native token balances for the tenant's custody
      wallets.
  - name: Analytics
    description: >-
      Pre-aggregated payment analytics — volume, success rates, corridor
      breakdowns, and daily time series.
  - name: Customers
    description: |
      KYC API for DeFi wallets. Onboard and verify your end-users, then link
      their wallet addresses so verified identity travels with their on-chain
      activity.
  - name: Webhooks
    description: Register endpoints and manage outbound event delivery.
  - name: Admin
    description: >-
      Ops-only endpoints for tenant management and payment operations. Requires
      an admin-scoped API key.
paths:
  /v1/fx/convert:
    get:
      tags:
        - FX
      summary: Get a live FX rate (informational)
      description: |
        Returns a live indicative exchange rate and fee breakdown.
      operationId: fxConvert
      parameters:
        - name: amount
          in: query
          required: true
          schema:
            type: number
            example: 1000
          description: Amount to convert
        - name: sourceCurrency
          in: query
          required: true
          schema:
            type: string
            description: |
              The currency to convert from (fiat or stablecoin).
            enum:
              - CDF
              - GHS
              - KES
              - NGN
              - TZS
              - UGX
              - XAF
              - XOF
              - ZAR
              - ZMW
              - USDC
              - USDT
          example: KES
        - name: destinationCurrency
          in: query
          required: true
          schema:
            type: string
            description: |
              The currency to convert to.
            enum:
              - USDC
              - USDT
              - CDF
              - GHS
              - KES
              - NGN
              - TZS
              - UGX
              - XAF
              - XOF
              - ZAR
              - ZMW
          example: USDC
        - name: paymentMethod
          in: query
          required: true
          schema:
            type: string
            enum:
              - MOMO
              - BANK
              - PAYBILL
              - TILL
          example: MOMO
        - name: direction
          in: query
          required: true
          schema:
            type: string
            enum:
              - payout
              - payin
          description: |
            payout: issuer sends stablecoin → recipient receives fiat.
            payin: customer pays fiat → issuer receives stablecoin.
          example: payout
        - name: optionalIssuerFee
          in: query
          required: true
          schema:
            type: string
            enum:
              - 'YES'
              - 'NO'
          example: 'NO'
        - name: country
          in: query
          required: false
          description: |
            For XOF payments, the recipient country must be specified.
          schema:
            $ref: '#/components/schemas/XOFCountries'
          example: SN
      responses:
        '200':
          description: Indicative FX rate and fee breakdown for the requested corridor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxConvertResponse'
              examples:
                moneyoutKes:
                  summary: Money-out — KES via M-Pesa
                  value:
                    convertedAmount: '10.680'
                    exchangeRate: '128.218000'
                    paymentFee: '20'
                    expiresAt: '2024-01-15T10:31:30.000Z'
                moneyoutXaf:
                  summary: Money-out — XAF via MTN
                  value:
                    convertedAmount: '8.120'
                    exchangeRate: '622.500000'
                    paymentFee: '50'
                    expiresAt: '2024-01-15T10:31:00.000Z'
                moneyinGhs:
                  summary: Money-in — customer pays GHS, issuer receives USDC
                  value:
                    convertedAmount: '6.062'
                    exchangeRate: '12.866920'
                    paymentFee: '2'
                    expiresAt: '2024-01-15T10:31:30.000Z'
                moneyinXaf:
                  summary: Money-in — customer pays XAF, issuer receives USDC
                  value:
                    convertedAmount: '0.441'
                    exchangeRate: '666.600000'
                    paymentFee: '6'
                    expiresAt: '2024-01-15T10:31:00.000Z'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Validation error — invalid currency pair, unsupported corridor, or
            missing parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 422
                message: >-
                  Moneyin is only supported for GHS, KES, NGN, TZS, UGX, ZMW,
                  XAF, XOF, CDF.
components:
  schemas:
    XOFCountries:
      type: string
      enum:
        - BJ
        - BF
        - CD
        - CI
        - SN
      description: |
        For XOF payments, the recipient country must be specified.
    FxConvertResponse:
      type: object
      properties:
        convertedAmount:
          type: string
          description: >-
            Total converted amount in the destination currency (inclusive of
            network fee, optional issuer fee and payment fee).
          example: '10.680'
        exchangeRate:
          type: string
          description: >-
            Market exchange rate sourced from local liquidity partners
            (inclusive of network fee and optional issuer fee)
          example: '128.218000'
        paymentFee:
          type: string
          description: >
            The fee comprises the mobile network operator or bank processing
            fee.
          example: '20'
        expiryTimestamp:
          type: integer
          format: int64
          description: Unix timestamp (seconds) after which this rate expires.
          example: 1750334460
      required:
        - convertedAmount
        - exchangeRate
        - paymentFee
        - expiryTimestamp
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        code:
          type: string
          description: Machine-readable error code.
          example: validation_error
        message:
          type: string
          description: Human-readable error message.
          example: fiatAmount must be a positive number.
      required:
        - statusCode
        - message
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Stablepay API key. Include as `Authorization: Bearer <key>`.

````