> ## 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 a card FX quote > Locks a rate for funding a card from a non-USD account, or for withdrawing to one. Amounts are always expressed in USD minor units, whichever direction you are going. ## When you need one Only when the account on your side is **not** USD. A USD account moves money to and from a card without a quote, and asking for one anyway is refused with `409 card_fx_quote_not_required`. ## Funding and withdrawal quotes are not interchangeable A quote is bound to its `operation`, its `accountId`, and its `cardId`. Using a funding quote for a withdrawal, or a quote made for another card, fails with `card_fx_quote_invalid`. `cardId` is optional for a funding quote — you may not have a card yet when issuing one — and required for a withdrawal. `expiresAt` comes from the FX provider, not from a fixed Sakawave window. Read it rather than assuming a duration, and quote immediately before the movement. ## Error codes | Status | `code` | Cause | | - | - | - | | `400` | `validation_failed` | A field failed validation, or `cardId` was omitted on a withdrawal quote. | | `403` | `card_client_account_required` | The account is a customer wallet. | | `409` | `card_account_ineligible` | The account is missing or not active. | | `409` | `card_fx_quote_not_required` | The account is already USD. | | `409` | `card_account_unavailable` | The card balance is not ready at the provider. | | `503` | `invalid_card_fx_quote` | The provider returned an incomplete or already-expired quote. | | `401` | `INVALID_API_KEY` | The key is missing, invalid, inactive, expired, from the other environment, or blocked by its IP allowlist. | | `404` | `card_not_found` | No such card for this business. | | `429` | `api_key_rate_limit_exceeded` | The per-minute limit for this key was exceeded. | ## OpenAPI ````yaml /openapi.json post /v1/card-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/card-fx-quotes: post: tags: - Cards summary: Create a card FX quote description: >- Locks a rate for funding a card from a non-USD account, or for withdrawing to one. Amounts are always expressed in USD minor units, whichever direction you are going. operationId: createCardFxQuote requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CardFxQuoteRequest' example: operation: funding accountId: 01K2Z3AB4D5E6F7G8H9JKMNPQR amountUsd: '5000' 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/CardFxQuoteResponse' example: id: 01K2Z3AB4V5W6X7Y8ZABCDEFGH operation: funding sourceCurrency: NGN destinationCurrency: USD sourceAmount: '8000000' destinationAmount: '5000' rate: '0.000625' expiresAt: '2026-08-14T09:26:00.000Z' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/AuthenticationError' '403': $ref: '#/components/responses/ForbiddenError' '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: CardFxQuoteRequest: oneOf: - $ref: '#/components/schemas/CardFundingQuoteRequest' - $ref: '#/components/schemas/CardWithdrawalQuoteRequest' discriminator: propertyName: operation mapping: funding: '#/components/schemas/CardFundingQuoteRequest' withdrawal: '#/components/schemas/CardWithdrawalQuoteRequest' CardFxQuoteResponse: type: object additionalProperties: false properties: id: $ref: '#/components/schemas/Ulid' operation: type: string enum: - funding - withdrawal sourceCurrency: $ref: '#/components/schemas/AssetCode' destinationCurrency: $ref: '#/components/schemas/AssetCode' sourceAmount: $ref: '#/components/schemas/MinorUnits' destinationAmount: $ref: '#/components/schemas/MinorUnits' rate: type: string expiresAt: $ref: '#/components/schemas/IsoTimestamp' required: - id - operation - sourceCurrency - destinationCurrency - sourceAmount - destinationAmount - rate - expiresAt CardFundingQuoteRequest: type: object additionalProperties: false properties: operation: const: funding accountId: $ref: '#/components/schemas/Ulid' cardId: $ref: '#/components/schemas/Ulid' amountUsd: $ref: '#/components/schemas/PositiveMinorUnits' required: - operation - accountId - amountUsd CardWithdrawalQuoteRequest: type: object additionalProperties: false properties: operation: const: withdrawal accountId: $ref: '#/components/schemas/Ulid' cardId: $ref: '#/components/schemas/Ulid' amountUsd: $ref: '#/components/schemas/PositiveMinorUnits' required: - operation - accountId - cardId - amountUsd Ulid: type: string minLength: 26 maxLength: 26 pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$ example: 01K2Z3AB4C5D6E7F8G9HJKMNPQ description: A 26-character ULID. AssetCode: type: string enum: - NGN - USD - GBP - EUR - GHS - ZAR - UGX - CAD - MXN - AED - BTC - ETH - USDT - USDC MinorUnits: type: string pattern: ^-?\d+$ example: '2500000' description: >- An integer number of the asset’s smallest unit. Use this value for arithmetic. 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. ForbiddenError: type: object additionalProperties: false properties: statusCode: const: 403 message: type: string code: type: string enum: - kyc_approval_required - international_questionnaire_required - international_account_approval_required - international_customer_wallet_not_supported description: >- Present on verification, international access, and customer wallet refusals. Absent on tier denials, which carry `reason` instead. reason: type: string enum: - currency_not_available - feature_not_available description: Present on tier denials. Absent on every other refusal. currency: $ref: '#/components/schemas/AssetCode' feature: type: string currentTier: type: integer enum: - 1 - 2 - 3 requiredTier: type: integer enum: - 1 - 2 - 3 required: - statusCode - message 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 PositiveMinorUnits: type: string pattern: ^[1-9]\d*$ example: '2500000' description: A positive integer number of minor units. 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. ForbiddenError: description: >- Authenticated, but not permitted to hold or use this currency. Entitlement refusals carry `code`; tier denials carry `reason`, `currentTier`, and `requiredTier` instead. 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/ForbiddenError' example: statusCode: 403 message: >- International wallets for your customers are not available yet. Your own approval cannot be used for a customer wallet. code: international_customer_wallet_not_supported currency: USD 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.