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

# Create an FX quote

> Locks a rate for one cross-currency transfer. A quote is bound to the account, destination, side, and amount it was created for, expires at a time the provider sets, and can be spent once.

## Minor units in, decimals out

You send `sourceAmount` as a positive integer of minor units — `"2500000"` for ₦25,000 — and the response returns `"25000.00"`. The request and the response are not in the same form. Never feed a response amount back into a request.

## A quote is bound to one transfer

Five things are fixed when the quote is created: `sourceAccountId`, `destinationId`, `sourceCurrency`, `destinationCurrency`, and `amountSide` together with its amount. Spending it on a transfer that differs in any of them fails with `fx_quote_mismatch` or `fx_quote_amount_mismatch`.

Quote, preview, and transfer in one sequence, and do not cache a quote across user decisions.

## Expiry

`expiresAt` comes from the FX provider, not from a fixed Sakawave window — read it rather than assuming a duration. A quote is also single-use: `used` becomes true when a transfer spends it.

## Error codes

| Status | `code` | Cause |
| - | - | - |
| `400` | `validation_failed` | A field failed validation, both amounts were sent, neither was, or the two currencies are the same. |
| `409` | `transfer_source_account_ineligible` | The source account is missing, inactive, not debitable, a customer wallet, or in a different currency. |
| `409` | `destination_currency_mismatch` | The destination was resolved for a different currency. |
| `409` | `transfer_destination_expired` | The destination has expired or has already been spent. |
| `409` | `currency_capability_unavailable` | One of the currencies is closed for this kind of transfer or for FX. |
| `409` | `fx_corridor_unavailable` | No active corridor exists for this ordered currency pair. |
| `409` | `fx_quote_amount_out_of_range` | The amount is outside the supported range. |
| `409` | `fx_quote_amount_too_small` | The converted amount rounds to nothing on the destination side. |
| `409` | `conversion_amount_not_whole_cents` | A USDC amount finer than a cent, converting to or from USD, which converts one for one in whole cents. |
| `503` | `fx_provider_unavailable` | The FX provider could not be reached, or returned a quote that had already expired. |
| `401` | `INVALID_API_KEY` | The key is missing, invalid, inactive, expired, from the other environment, or blocked by its IP allowlist. |
| `429` | `api_key_rate_limit_exceeded` | The per-minute limit for this key was exceeded. Transfers, quotes, destinations, and recipients share one 120-per-minute allowance. |


## OpenAPI

````yaml /openapi.json post /v1/fx-quotes
openapi: 3.1.0
info:
  title: Sakawave Business API
  version: 1.0.0-draft
  summary: >-
    Accounts, transfers, FX quotes, and transaction reconciliation for Sakawave
    businesses.
  description: >-
    Generated from the public NestJS controllers and their Zod request schemas.
    Public URLs and policy statements remain draft until the Phase 1 contract
    checklist is approved.
  contact:
    name: Sakawave API Support
    email: api-support@sakawave.example
servers:
  - url: https://sandbox-api.sakawave.example
    description: Sandbox (default)
  - url: https://api.sakawave.example
    description: Live
security:
  - bearerAuth: []
tags:
  - name: Bill payments
    description: Browse the biller catalog, validate a customer, and pay a bill.
  - name: Cards
    description: Issue, fund, and control USD virtual and disposable cards.
  - name: eSIM
    description: >-
      Sell mobile data abroad: browse the catalog, buy an eSIM, and manage it
      once installed.
  - name: Currencies and countries
    description: >-
      Reference data: what may be held, what may be sent where, and which
      jurisdictions are served.
  - name: Customers
    description: Create and manage customers of your business.
  - name: Accounts
    description: >-
      Open business and customer accounts, and issue the destinations that fund
      them.
  - name: Transfer destinations
    description: Resolve temporary destinations and saved recipients.
  - name: FX quotes
    description: Create and retrieve time-limited cross-currency quotes.
  - name: Transfers
    description: Preview, create, and monitor transfers.
  - name: Transactions
    description: Read ledger entries for reconciliation.
paths:
  /v1/fx-quotes:
    post:
      tags:
        - FX quotes
      summary: Create an FX quote
      description: >-
        Locks a rate for one cross-currency transfer. A quote is bound to the
        account, destination, side, and amount it was created for, expires at a
        time the provider sets, and can be spent once.
      operationId: createFxQuote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FxQuoteRequest'
            example:
              sourceAccountId: 01K2Z3AB4D5E6F7G8H9JKMNPQR
              destinationId: 01K2Z3AB4F5G6H7J8KMNPQRSTV
              sourceCurrency: NGN
              destinationCurrency: USD
              amountSide: source
              sourceAmount: '2500000'
      responses:
        '201':
          description: Successful response.
          headers:
            X-Request-ID:
              description: >-
                The request identifier assigned by Sakawave. Include it in
                support requests.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FxQuoteResponse'
              example:
                id: 01K2Z3AB4H5J6K7M8NPQRSTVWX
                sourceAccountId: 01K2Z3AB4D5E6F7G8H9JKMNPQR
                destinationId: 01K2Z3AB4F5G6H7J8KMNPQRSTV
                sourceCurrency: NGN
                destinationCurrency: USD
                amountSide: source
                sourceAmount: '25000.00'
                destinationAmount: '15.63'
                rate: '0.000625'
                expiresAt: '2026-08-14T09:20:00.000Z'
                used: false
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/ProviderUnavailableError'
      security:
        - bearerAuth: []
components:
  schemas:
    FxQuoteRequest:
      type: object
      additionalProperties: false
      properties:
        sourceAccountId:
          $ref: '#/components/schemas/Ulid'
          description: >-
            The account the money leaves. Must be active, debitable, and in
            sourceCurrency.
        destinationId:
          $ref: '#/components/schemas/Ulid'
          description: >-
            An unexpired, unspent destination. Its currency must equal
            destinationCurrency.
        sourceCurrency:
          $ref: '#/components/schemas/Currency'
        destinationCurrency:
          $ref: '#/components/schemas/DestinationCurrency'
        amountSide:
          type: string
          enum:
            - source
            - destination
          description: >-
            Which side you are fixing. Send the matching amount and only that
            one.
        sourceAmount:
          $ref: '#/components/schemas/PositiveMinorUnits'
        destinationAmount:
          $ref: '#/components/schemas/PositiveMinorUnits'
      required:
        - sourceAccountId
        - destinationId
        - sourceCurrency
        - destinationCurrency
        - amountSide
      description: Provide only the amount matching amountSide. The currencies must differ.
      oneOf:
        - required:
            - sourceAmount
          not:
            required:
              - destinationAmount
        - required:
            - destinationAmount
          not:
            required:
              - sourceAmount
    FxQuoteResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Ulid'
        sourceAccountId:
          $ref: '#/components/schemas/Ulid'
        destinationId:
          $ref: '#/components/schemas/Ulid'
        sourceCurrency:
          $ref: '#/components/schemas/Currency'
        destinationCurrency:
          $ref: '#/components/schemas/DestinationCurrency'
        amountSide:
          type: string
          enum:
            - source
            - destination
        sourceAmount:
          $ref: '#/components/schemas/DecimalAmount'
        destinationAmount:
          $ref: '#/components/schemas/DecimalAmount'
        rate:
          type: string
        expiresAt:
          $ref: '#/components/schemas/IsoTimestamp'
        used:
          type: boolean
      required:
        - id
        - sourceAccountId
        - destinationId
        - sourceCurrency
        - destinationCurrency
        - amountSide
        - sourceAmount
        - destinationAmount
        - rate
        - expiresAt
        - used
    Ulid:
      type: string
      minLength: 26
      maxLength: 26
      pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
      example: 01K2Z3AB4C5D6E7F8G9HJKMNPQ
      description: A 26-character ULID.
    Currency:
      type: string
      enum:
        - NGN
        - USD
        - GBP
        - EUR
        - GHS
        - ZAR
        - UGX
        - CAD
        - MXN
        - AED
    DestinationCurrency:
      type: string
      enum:
        - NGN
        - USD
        - GBP
        - EUR
        - GHS
        - ZAR
        - UGX
        - CAD
        - MXN
        - AED
        - AUD
        - SGD
        - HKD
        - KES
        - TZS
        - BRL
        - CNY
        - XAF
        - PHP
        - USDC
    PositiveMinorUnits:
      type: string
      pattern: ^[1-9]\d*$
      example: '2500000'
      description: A positive integer number of minor units.
    DecimalAmount:
      type: string
      pattern: ^-?\d+(?:\.\d+)?$
      example: '25000.00'
      description: >-
        A decimal display amount returned by transfer APIs. Preserve it as a
        string.
    IsoTimestamp:
      type: string
      format: date-time
      example: '2026-08-14T09:00:00.000Z'
    RequestError:
      anyOf:
        - $ref: '#/components/schemas/ValidationError'
        - $ref: '#/components/schemas/Error'
      description: >-
        Either a field-level validation failure carrying an errors array, or a
        rule the request broke, identified by code.
    Error:
      type: object
      additionalProperties: true
      properties:
        statusCode:
          type: integer
        message:
          type: string
          description: >-
            A sentence suitable for a log or a support conversation, not for a
            user interface.
        code:
          type: string
          description: >-
            The stable machine-readable reason. Branch on this, never on the
            message.
      required:
        - message
        - code
      description: >-
        An error body. Individual errors may add context fields alongside these
        three.
    RateLimitError:
      type: object
      additionalProperties: false
      properties:
        statusCode:
          const: 429
        message:
          type: string
        code:
          const: api_key_rate_limit_exceeded
        retryAfterSeconds:
          type: integer
          minimum: 1
      required:
        - statusCode
        - message
        - code
        - retryAfterSeconds
    ValidationError:
      type: object
      additionalProperties: false
      properties:
        statusCode:
          const: 400
        message:
          type: string
          description: The single failure, or a count when more than one field failed.
        code:
          const: validation_failed
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationFailure'
      required:
        - statusCode
        - message
        - code
        - errors
    ValidationFailure:
      type: object
      additionalProperties: false
      properties:
        message:
          type: string
        field:
          type: string
        code:
          type: string
        path:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
      required:
        - message
        - field
        - code
        - path
  responses:
    ValidationError:
      description: >-
        The request was rejected before it was acted on. Field failures list
        every failing field.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
          example:
            statusCode: 400
            message: Must be a valid identifier.
            code: validation_failed
            errors:
              - message: Must be a valid identifier.
                field: accountId
                code: custom
                path:
                  - accountId
    AuthenticationError:
      description: >-
        The API key is missing, invalid, inactive, expired, for another
        environment, or blocked by its IP allowlist.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            code: INVALID_API_KEY
            message: Invalid or inactive API credentials.
    NotFoundError:
      description: The requested resource was not found for this business.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 404
            code: resource_not_found
            message: Resource not found.
    ConflictError:
      description: The request conflicts with the current resource state.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 409
            code: resource_conflict
            message: The request conflicts with the current resource state.
    RateLimitError:
      description: The API key rate limit was exceeded.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            statusCode: 429
            message: Too many API requests. Try again later.
            code: api_key_rate_limit_exceeded
            retryAfterSeconds: 17
    ServerError:
      description: An unexpected server error occurred.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 500
            code: internal_server_error
            message: An unexpected error occurred.
    ProviderUnavailableError:
      description: >-
        A payment provider could not be reached. The request had no effect;
        retry shortly.
      headers:
        X-Request-ID:
          description: >-
            The request identifier assigned by Sakawave. Include it in support
            requests.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 503
            code: provider_unavailable
            message: We could not issue an account number just now. Try again shortly.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sakawave API key
      description: >-
        A secret API key, sent as `Authorization: Bearer sk_test_…` in sandbox
        or `Bearer sk_live_…` in live.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.