> ## 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.

# List routes for a currency

> Active payout routes that can deliver to this destination currency, default first. A route carries the `routeId` and the exact field descriptors you need to build a payment detail or an external destination.

## An unknown currency is not an error

The code is not checked against the currency list. A currency Sakawave does not serve simply matches no routes and returns `[]` — so an empty array means "nothing delivers there", not "you asked wrongly".

## Country filtering

A route can be scoped to one country, or serve many through its scheme — `sepa` and `cemac` both cover a set. Passing `country` keeps only the routes that actually serve it, whichever way they are scoped.

## Prefer corridors for building a form

This endpoint returns the route row as stored, including internal routing detail. [`GET /v1/transfer-corridors`](/api-reference/currencies-and-countries/discover-transfer-corridors) answers the same question in a provider-neutral shape, with the currency and its countries resolved alongside each route. Use corridors to drive a UI; use this when you already know the currency and only need its `routeId` values.

<Warning>`provider` and `serviceCode` are internal routing detail that this endpoint currently returns. They are not part of the supported contract and may be withdrawn — do not branch on them.</Warning>

## Error codes

| Status | `code` | Cause |
| - | - | - |
| `400` | `validation_failed` | `code` is not three characters, or `country` is not two. |
| `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. |


## OpenAPI

````yaml /openapi.json get /v1/currencies/{code}/routes
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/currencies/{code}/routes:
    get:
      tags:
        - Currencies and countries
      summary: List routes for a currency
      description: >-
        Active payout routes that can deliver to this destination currency,
        default first. A route carries the `routeId` and the exact field
        descriptors you need to build a payment detail or an external
        destination.
      operationId: listCurrencyRoutes
      parameters:
        - name: code
          in: path
          required: true
          description: >-
            Destination currency code. Case-insensitive; uppercased before
            matching.
          schema:
            type: string
            minLength: 3
            maxLength: 10
          example: KES
        - name: country
          in: query
          required: false
          description: >-
            ISO 3166-1 alpha-2 destination country. Keeps only routes that serve
            it.
          schema:
            type: string
            minLength: 2
            maxLength: 2
          example: KE
      responses:
        '200':
          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:
                type: array
                items:
                  $ref: '#/components/schemas/TransferRouteResponse'
              example:
                - id: 01K2Z3AB4M5N6P7Q8RSTVWXYZA
                  name: Kenya bank transfer
                  destinationCurrency: KES
                  destinationCountry: KE
                  scheme: pesalink
                  paymentMethod: bank-transfer
                  provider: provider-a
                  serviceCode: KE_BANK_TRANSFER
                  requiredFields:
                    - bankCode
                    - accountNumber
                  fieldDescriptors:
                    - key: bankCode
                      label: Bank
                      type: select
                      required: true
                      options:
                        - value: '001'
                          label: Example Bank
                    - key: accountNumber
                      label: Account number
                      type: text
                      required: true
                      minLength: 6
                      maxLength: 20
                      placeholder: '0123456789'
                  settlementTiming: same_day
                  minimumAmount: '10000'
                  maximumAmount: '100000000'
                  institutionDirectoryEnabled: true
                  isDefault: true
                  isActive: true
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    TransferRouteResponse:
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/Ulid'
          description: >-
            The routeId to send when creating a payment detail or an external
            destination.
        name:
          type: string
          maxLength: 80
        destinationCurrency:
          anyOf:
            - type: string
              minLength: 3
              maxLength: 10
              description: Null for a route that is not currency-scoped.
            - type: 'null'
        destinationCountry:
          anyOf:
            - type: string
              maxLength: 16
              description: >-
                ISO 3166-1 alpha-2 when the route serves one country. Null for a
                scheme that spans several.
            - type: 'null'
        scheme:
          type: string
          maxLength: 40
          description: The settlement scheme, such as nip, sepa, or cemac.
        paymentMethod:
          type: string
          maxLength: 40
          description: >-
            `bank-transfer`, `momo-transfer`, or `stablecoin-transfer` for a
            route that pays a wallet address; its `scheme` is the chain.
        provider:
          type: string
          maxLength: 40
          description: >-
            Internal routing detail. Not part of the supported contract — do not
            branch on it.
        serviceCode:
          type: string
          maxLength: 60
          description: Internal routing detail. Not part of the supported contract.
        requiredFields:
          type: array
          items:
            type: string
          description: Keys of fieldDescriptors that must be supplied.
        fieldDescriptors:
          type: array
          items:
            $ref: '#/components/schemas/TransferFieldDescriptor'
        settlementTiming:
          anyOf:
            - type: string
              maxLength: 80
            - type: 'null'
        minimumAmount:
          anyOf:
            - $ref: '#/components/schemas/MinorUnits'
            - type: 'null'
        maximumAmount:
          anyOf:
            - $ref: '#/components/schemas/MinorUnits'
            - type: 'null'
        institutionDirectoryEnabled:
          type: boolean
          description: Whether Sakawave resolves institution codes to names for this route.
        isDefault:
          type: boolean
          description: The route chosen when you do not name one. Listed first.
        isActive:
          type: boolean
          description: 'Always true in this response: inactive routes are not returned.'
      required:
        - id
        - name
        - destinationCurrency
        - destinationCountry
        - scheme
        - paymentMethod
        - provider
        - serviceCode
        - requiredFields
        - fieldDescriptors
        - settlementTiming
        - minimumAmount
        - maximumAmount
        - institutionDirectoryEnabled
        - isDefault
        - isActive
    Ulid:
      type: string
      minLength: 26
      maxLength: 26
      pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
      example: 01K2Z3AB4C5D6E7F8G9HJKMNPQ
      description: A 26-character ULID.
    TransferFieldDescriptor:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
        label:
          type: string
        type:
          type: string
          enum:
            - text
            - select
            - tel
        required:
          type: boolean
        minLength:
          type: integer
        maxLength:
          type: integer
        pattern:
          type: string
        placeholder:
          type: string
        options:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              value:
                type: string
              label:
                type: string
            required:
              - value
              - label
      required:
        - key
        - label
        - type
        - required
    MinorUnits:
      type: string
      pattern: ^-?\d+$
      example: '2500000'
      description: >-
        An integer number of the asset’s smallest unit. Use this value for
        arithmetic.
    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.
    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.
  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.