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

# Create a conversion or payment quote

> Confirm the rate, fees, destination amount and expiry before sending.

**Required scope:** `quotes:write`

Send sourceAmount; Ledig calculates destinationAmount. For a same-currency payment, include payOut. payIn with temporary\_bank\_account is not supported and returns 501. A quote can be used once through POST /v1/transfers. Check conversion limits in GET /v1/liquidity/routes, measured in the source currency, and payout limits in GET /v1/payouts/catalogue, measured in the destination currency. Quote creation checks the amount, current availability and your source balance including fees. Handle 404 RATE\_NOT\_FOUND, 422 RATE\_ROUTE\_AMOUNT\_OUT\_OF\_RANGE and 409 INSUFFICIENT\_BALANCE separately. Your business's per-payment and monthly payout allowances are separate limits measured in USD equivalent and are checked when you create the transfer. Both new and replayed responses use HTTP 201: replayed=false means a new quote, and replayed=true returns the original quote for the same reference without renewing its expiry. An expired or accepted quote may be returned by a replay; use a fresh reference when you deliberately request a fresh quote. This endpoint does not use Idempotency-Key.


## OpenAPI

````yaml /openapi/public.yaml post /v1/quotes
openapi: 3.1.0
info:
  title: Ledig payments API
  version: 0.1.0
  description: >-
    Use the Ledig payments engine to receive funds, view balances, convert
    currencies and send payments.


    Choose Sandbox to test your integration or Live for production payments.
    Each endpoint explains the fields, permissions and errors you need to
    handle.


    Sign API requests with your business API key and HMAC-SHA256. Endpoints
    listing BearerAuth also accept a user access token. Follow
    https://docs.ledig.io/auth/authentication to sign your requests.
  contact:
    name: Ledig
    email: support@ledig.io
    url: https://docs.ledig.io
servers:
  - url: https://api-sandbox.ledig.io
    description: Sandbox
  - url: https://api.ledig.io
    description: Live
security:
  - LedigApiKey: []
    LedigTimestamp: []
    LedigSignature: []
tags:
  - name: Managed businesses
    description: Onboarding for businesses you manage.
  - name: System
    description: Health and availability.
  - name: Balances
    description: Your available and reserved funds by currency.
  - name: Currencies and rates
    description: Supported currencies, networks and indicative rates.
  - name: Funding accounts
    description: Fiat accounts that receive customer deposits.
  - name: Deposit wallets
    description: Crypto addresses that receive customer deposits.
  - name: Recipients
    description: Saved payout destinations.
  - name: Ledig businesses
    description: Find a business before paying through the Ledig network.
  - name: Payment options
    description: Available payout methods, fees and limits.
  - name: Quotes
    description: Confirm rates, fees and amounts before sending.
  - name: Transfers
    description: Start and track conversions and payments.
  - name: Transactions
    description: Customer transaction history.
paths:
  /v1/quotes:
    post:
      tags:
        - Quotes
      summary: Create a conversion or payment quote
      description: Confirm the rate, fees, destination amount and expiry before sending.
      operationId: createQuote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQuoteRequest'
            example:
              sourceCurrency: USDT
              destinationCurrency: USD
              sourceAmount: '100.00'
              reference: invoice-example-001
      responses:
        '201':
          description: >-
            Quote created or the original quote recovered. replayed
            distinguishes an existing result.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Success'
                  - type: object
                    required:
                      - data
                      - replayed
                    properties:
                      replayed:
                        type: boolean
                        description: >-
                          True when the original resource is returned without
                          creating another operation.
                      data:
                        $ref: '#/components/schemas/ClientQuote'
              example:
                status: success
                data:
                  id: quote_example_001
                  profileId: profile_example_001
                  reference: invoice-example-001
                  sourceCurrency: USDT
                  destinationCurrency: USD
                  sourceAmount: '100.00'
                  destinationAmount: '100.00'
                  rate: '1.00'
                  createdAt: '2026-01-15T10:00:00.000Z'
                  updatedAt: '2026-01-15T10:00:00.000Z'
                  feeAmount: '0.50'
                  feeCurrency: USDT
                  sourceDebitAmount: '100.50'
                  payoutFeeAmount: '0'
                  payoutFeeCurrency: USD
                  payoutFeeSourceAmount: '0'
                  totalFeeAmount: '0.50'
                  totalFeeCurrency: USDT
                  totalSourceDebitAmount: '100.50'
                  meta:
                    rate:
                      product: USDTUSD
                      sourceCurrency: USDT
                      destinationCurrency: USD
                      rate: '1.00'
                      side: sell
                      type: fixed
                  expiresAt: '2026-01-15T10:05:00.000Z'
                  status: pending
                replayed: false
        '400':
          description: >-
            Invalid request, too many decimal places or an unsupported mobile
            money network.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingRecipient:
                  value:
                    status: error
                    code: BAD_REQUEST
                    message: payOut.recipientId is required.
                amountPrecision:
                  summary: >-
                    A zero-decimal currency received a non-zero fractional
                    amount.
                  value:
                    status: error
                    code: BAD_REQUEST
                    message: Amount exceeds the currency's 0-decimal precision.
                mobileNetwork:
                  summary: >-
                    Example network choices. Use a supported mobile money
                    network for the destination country.
                  value:
                    status: error
                    code: PROVIDER_NETWORK_INVALID
                    message: >-
                      Mobile-money network is invalid for KE. Accepted values:
                      Mpesa.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >-
            No active conversion route or executable price exists for the
            requested currency direction. A missing recipient or payout method
            can also return NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                priceUnavailable:
                  value:
                    status: error
                    code: RATE_NOT_FOUND
                    message: >-
                      A price is currently unavailable for this pair. Try again
                      later.
        '409':
          description: >-
            The source balance cannot cover the amount and fees
            (INSUFFICIENT_BALANCE), the conversion is unavailable, pricing
            conflicts, or your conversion allowance is exceeded.
            INSTANT_CONVERSION_LIMIT_EXCEEDED includes daily or monthly
            allowance details in the source currency. Resolve the reported cause
            before requesting another quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficientBalance:
                  value:
                    status: error
                    code: INSUFFICIENT_BALANCE
                    message: Available balance is not sufficient for this action.
                conversionUnavailable:
                  value:
                    status: error
                    code: RATE_PROVIDER_CONVERSION_UNAVAILABLE
                    message: Conversion is not available for this route.
        '422':
          description: >-
            The amount is outside this conversion's limits
            (RATE_ROUTE_AMOUNT_OUT_OF_RANGE), the amount cannot currently be
            converted (RATE_ROUTE_CAPACITY_EXCEEDED), or the rate is not
            currently available for a confirmed quote. Range details use the
            source currency. A displayed conversion or rate is checked again
            when you create the quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                conversionAmountOutsideRange:
                  value:
                    status: error
                    code: RATE_ROUTE_AMOUNT_OUT_OF_RANGE
                    message: >-
                      The amount you convert must be between 10 and 50000 USDT
                      for this conversion direction.
                    details:
                      sourceCurrency: USDT
                      minimumAmount: '10'
                      maximumAmount: '50000'
                conversionAmountUnavailable:
                  value:
                    status: error
                    code: RATE_ROUTE_CAPACITY_EXCEEDED
                    message: >-
                      The requested conversion amount is not currently
                      available. Try a smaller amount or try again later.
                expiredPrice:
                  value:
                    status: error
                    code: RATE_EXPIRED
                    message: This price has expired. Request a new quote.
        '423':
          description: >-
            COMPLIANCE_REVIEW_REQUIRED: this payment needs review before it can
            proceed. Check its status or contact support@ledig.io.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: error
                code: COMPLIANCE_REVIEW_REQUIRED
                message: This action requires a review before it can continue.
        '429':
          $ref: '#/components/responses/RateLimited'
        '501':
          description: temporary_bank_account is not currently supported for payIn.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: error
                code: NOT_IMPLEMENTED
                message: Temporary-bank-account quotes are not implemented.
        '503':
          description: >-
            The service is temporarily unavailable, or the chosen payout method
            or network cannot support this amount or destination. For an amount
            error, check the payout bands in the destination currency. These are
            separate from conversion limits and do not apply to every payment in
            that currency.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                payoutAmountOutsideLimits:
                  value:
                    status: error
                    code: PROVIDER_UNAVAILABLE
                    message: >-
                      The amount sent to the recipient is outside the limits for
                      this payout method or network. Check the payout limits in
                      the recipient's currency.
      x-codeSamples:
        - lang: javascript
          label: Node.js
          source: >-
            import { createHmac } from "node:crypto";


            // Node.js 18+. Set credentials and resource values on your server.

            function required(name) {
              const value = process.env[name];
              if (!value) throw new Error(`Set ${name} before running this example.`);
              return value;
            }


            const baseUrl = process.env.LEDIG_API_BASE_URL ??
            "https://api-sandbox.ledig.io";

            const method = "POST";

            const path = `/v1/quotes`;

            const pathWithQuery = path;

            const body = {
              "sourceCurrency": "USDT",
              "destinationCurrency": "USD",
              "sourceAmount": "100.00",
              "reference": required("LEDIG_REFERENCE")
            };

            const rawBody = JSON.stringify(body);

            const headers = { "Accept": "application/json" };

            headers["Content-Type"] = "application/json";

            const timestamp = Math.floor(Date.now() / 1000).toString();

            const payload =
            `${timestamp}.${method}.${pathWithQuery}.${rawBody}`;

            headers["x-ledig-key"] = required("LEDIG_API_KEY");

            headers["x-ledig-timestamp"] = timestamp;

            headers["x-ledig-signature"] = "v1=" + createHmac("sha256",
            required("LEDIG_API_SECRET"))
              .update(payload).digest("base64");

            const response = await fetch(`${baseUrl}${pathWithQuery}`, {
              method,
              headers,
              body: rawBody,
            });

            const result = await response.json();

            // Use result in your application; do not log credentials or upload
            links.

            console.log(response.status);
components:
  schemas:
    CreateQuoteRequest:
      type: object
      additionalProperties: false
      required:
        - sourceCurrency
        - destinationCurrency
        - sourceAmount
      properties:
        reference:
          type: string
          maxLength: 64
        sourceCurrency:
          type: string
          minLength: 2
          maxLength: 20
        destinationCurrency:
          type: string
          minLength: 2
          maxLength: 20
        sourceAmount:
          type: string
          description: >-
            A positive decimal amount within sourceCurrency's supported
            precision. Extra trailing zeroes are accepted, but extra non-zero
            decimal places are rejected without rounding. For a zero-decimal
            currency, 10 and 10.000 are accepted; 10.1 is rejected.
        payIn:
          type: object
          additionalProperties: false
          required:
            - type
          properties:
            type:
              type: string
              const: temporary_bank_account
        payOut:
          type: object
          additionalProperties: false
          required:
            - type
            - paymentMethodId
          description: >-
            Use recipientId for a saved destination. To pay another Ledig
            business, use businessId without saving a recipient. Existing ledig
            payments using recipientId remain supported; use businessId for new
            integrations. Business names are looked up by Ledig and are not
            accepted here.
          oneOf:
            - properties:
                type:
                  enum:
                    - fiat
                    - crypto
              required:
                - recipientId
              not:
                required:
                  - businessId
            - properties:
                type:
                  const: ledig
                paymentMethodId:
                  const: ledig
              required:
                - businessId
              not:
                anyOf:
                  - required:
                      - recipientId
                  - required:
                      - chain
            - deprecated: true
              properties:
                type:
                  const: ledig
                paymentMethodId:
                  const: ledig
              required:
                - recipientId
              not:
                anyOf:
                  - required:
                      - businessId
                  - required:
                      - chain
          properties:
            type:
              type: string
              enum:
                - fiat
                - crypto
                - ledig
            recipientId:
              type: string
            businessId:
              type: string
              minLength: 1
              maxLength: 200
            paymentMethodId:
              type: string
            chain:
              type: string
            narration:
              type: string
            transferPurpose:
              type: string
              minLength: 1
              maxLength: 100
              description: >-
                An optional description of why you are sending the payment.
                Free-text values are accepted.
            invoiceDocumentId:
              allOf:
                - $ref: '#/components/schemas/PayoutDocumentId'
              description: >-
                A verified invoice document uploaded by your business. Required
                only when the chosen payment option has invoiceRequired=true.
    Success:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          const: success
        message:
          type: string
    ClientQuote:
      type: object
      additionalProperties: false
      description: >-
        Confirmed conversion or payment terms. Amounts are decimal strings;
        totalSourceDebitAmount includes conversion and payout fees.
      required:
        - id
        - profileId
        - reference
        - sourceCurrency
        - destinationCurrency
        - sourceAmount
        - destinationAmount
        - rate
        - createdAt
        - updatedAt
        - feeAmount
        - feeCurrency
        - sourceDebitAmount
        - payoutFeeAmount
        - payoutFeeCurrency
        - payoutFeeSourceAmount
        - totalFeeAmount
        - totalFeeCurrency
        - totalSourceDebitAmount
        - meta
        - expiresAt
        - status
      properties:
        id:
          type: string
        profileId:
          type: string
        reference:
          type: string
        sourceCurrency:
          type: string
        destinationCurrency:
          type: string
        sourceAmount:
          type: string
        destinationAmount:
          type: string
        rate:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string
        feeAmount:
          type: string
        feeCurrency:
          type: string
        sourceDebitAmount:
          type: string
        payoutFeeAmount:
          type: string
        payoutFeeCurrency:
          type: string
        payoutFeeSourceAmount:
          type: string
        totalFeeAmount:
          type: string
        totalFeeCurrency:
          type: string
        totalSourceDebitAmount:
          type: string
        meta:
          $ref: '#/components/schemas/ClientMoneyMeta'
        expiresAt:
          type: string
        status:
          type: string
          enum:
            - pending
            - accepted
            - expired
    Error:
      type: object
      required:
        - status
        - message
        - code
      properties:
        status:
          type: string
          const: error
        message:
          type: string
        code:
          type: string
        details:
          description: >-
            Additional information to help resolve an error, such as a file
            problem, allowed amount range or remaining payment allowance. The
            fields depend on the error code.
          oneOf:
            - type: object
              additionalProperties: false
              description: >-
                File-validation details returned with HTTP 400, 413 or 422
                BAD_REQUEST.
              required:
                - validationCode
                - reasonCode
                - retryable
              properties:
                validationCode:
                  type: string
                  enum:
                    - document_unreadable
                    - document_type_mismatch
                    - document_password_protected
                    - document_limits_exceeded
                reasonCode:
                  type: string
                  enum:
                    - document_unreadable
                    - document_type_mismatch
                    - document_password_protected
                    - document_limits_exceeded
                retryable:
                  type: boolean
                  const: false
                documentId:
                  type: string
                  maxLength: 128
                requirementType:
                  type: string
                maxSizeBytes:
                  type: integer
                  minimum: 1
                  maximum: 1073741824
                  description: >-
                    Maximum accepted file size in bytes, when supplied with HTTP
                    413.
            - type: object
              additionalProperties: false
              required:
                - reason
              properties:
                reason:
                  type: string
                  enum:
                    - current_password_incorrect
                    - unsupported_asset_network
                    - recipient_unavailable
                    - recipient_incompatible
                    - payout_method_unavailable
                    - payout_method_incompatible
                    - network_unavailable
                    - quote_expired
                    - quote_already_used
                    - quote_changed
                    - invoice_required
                    - invoice_invalid
                    - amount_invalid
                    - amount_precision_invalid
                    - onboarding_revision_required
                    - onboarding_revision_changed
                    - onboarding_document_kind_mismatch
                precision:
                  type: integer
                  minimum: 0
                  maximum: 18
                  description: >-
                    Allowed number of decimal places when reason is
                    amount_precision_invalid.
            - type: object
              additionalProperties: false
              required:
                - period
                - sourceCurrency
                - requested
                - remaining
                - limit
                - resetsAt
                - timezone
              properties:
                period:
                  type: string
                  enum:
                    - daily
                    - monthly
                sourceCurrency:
                  type: string
                  pattern: ^[A-Z][A-Z0-9]{1,19}$
                requested:
                  type: string
                  pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
                remaining:
                  type: string
                  pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
                limit:
                  type: string
                  pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$
                resetsAt:
                  type: string
                  format: date-time
                timezone:
                  type: string
                  const: UTC
            - type: object
              additionalProperties: false
              required:
                - sourceCurrency
                - minimumAmount
                - maximumAmount
              properties:
                sourceCurrency:
                  type: string
                minimumAmount:
                  type: string
                maximumAmount:
                  type: string
              description: >-
                Returned with HTTP 422 RATE_ROUTE_AMOUNT_OUT_OF_RANGE. These
                limits apply to the amount being converted, in the source
                currency.
            - type: object
              additionalProperties: false
              required:
                - currency
                - requestedUsd
                - limitUsd
              properties:
                currency:
                  type: string
                  const: USD
                requestedUsd:
                  type: string
                limitUsd:
                  type: string
              description: >-
                Returned with HTTP 422 PAYOUT_TRANSACTION_LIMIT_EXCEEDED. This
                per-payment limit uses USD equivalent and is separate from the
                payout method's currency limits.
            - type: object
              additionalProperties: false
              required:
                - currency
                - requestedUsd
                - remainingUsd
                - resetsAt
                - timezone
              properties:
                currency:
                  type: string
                  const: USD
                requestedUsd:
                  type: string
                remainingUsd:
                  type: string
                resetsAt:
                  type: string
                  format: date-time
                timezone:
                  type: string
                  const: UTC
              description: >-
                Returned with HTTP 422 PAYOUT_MONTHLY_LIMIT_EXCEEDED. Shows your
                business's remaining monthly allowance and when it resets.
    PayoutDocumentId:
      type: string
      pattern: ^pdoc_[A-Za-z0-9_-]{24}$
      description: >-
        The ID of an invoice document uploaded by your business. Supply the ID,
        not a file URL.
    ClientMoneyMeta:
      type: object
      additionalProperties: false
      description: The pricing and payment instructions accepted for this transaction.
      properties:
        rate:
          type: object
          additionalProperties: false
          required:
            - product
            - sourceCurrency
            - destinationCurrency
            - rate
            - side
            - type
          properties:
            product:
              type: string
            sourceCurrency:
              type: string
            destinationCurrency:
              type: string
            rate:
              type: string
            side:
              type: string
              enum:
                - buy
                - sell
            type:
              type: string
              const: fixed
        payIn:
          type: object
          additionalProperties: false
          description: >-
            Receiving instructions accepted for this transaction. New
            temporary_bank_account requests are not supported.
          required:
            - type
          properties:
            type:
              type: string
              const: temporary_bank_account
        payOut:
          type: object
          additionalProperties: false
          description: The accepted destination and instructions for the payout.
          required:
            - type
            - paymentMethodId
          properties:
            paymentMethodId:
              type: string
            chain:
              type: string
            narration:
              type: string
            transferPurpose:
              type: string
            invoiceDocumentId:
              type: string
            recipientId:
              type: string
            businessId:
              type: string
            businessName:
              type: string
            type:
              type: string
              enum:
                - fiat
                - crypto
                - ledig
  responses:
    Unauthorized:
      description: >-
        Authentication is missing, invalid or expired. Check your credentials
        and request signature.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: UNAUTHORIZED
            message: Authentication is required.
    Forbidden:
      description: >-
        Your account is inactive, the business selection is missing, or your
        credentials do not have the required permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: FORBIDDEN
            message: You do not have permission to perform this action.
    RateLimited:
      description: >-
        A request or operation allowance has been reached. Wait before retrying.
        If the endpoint uses an idempotency key, keep the same key for the
        retry.
      headers:
        Retry-After:
          description: The number of seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
        Cache-Control:
          description: >-
            Responses use private, no-store or no-store. Do not cache this
            response.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            code: RATE_LIMITED
            message: Too many requests. Wait before trying again.
  securitySchemes:
    LedigApiKey:
      type: apiKey
      in: header
      name: x-ledig-key
      description: >-
        Your business API key ID. Keep its secret on your server and use that
        secret to sign each request.
    LedigTimestamp:
      type: apiKey
      in: header
      name: x-ledig-timestamp
      description: The current Unix timestamp in seconds, used in the signed request.
    LedigSignature:
      type: apiKey
      in: header
      name: x-ledig-signature
      description: >-
        The request's HMAC-SHA256 signature. Use the v1= prefix for supported
        own-business requests, or v2= when acting for a managed business with
        signed business-selection headers. Follow the authentication guide to
        construct and sign the exact request.

````

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