Discover currencies and rates
CallGET /v1/currencies for currency codes, decimal precision and supported networks. Call GET /v1/rates for indicative exchange rates. Indicative rates are useful for estimates; a quote gives you the rate you can use for a transaction.
Send amounts as decimal strings using the currency’s supported precision. For example, use "100.00" where two decimal places are supported. Do not assume that every currency uses two decimals.
Use GET /v1/liquidity/routes to check which conversions are available and their minimum and maximum amounts. See Limits for the difference between conversion, payout and account limits.
Discover payment methods and fees
These operations require the
quotes:read scope.
For a payout, request payment options with type=withdraw, the destination currency and the approved recipientId. Include amount to find methods that support the amount the recipient will receive. For crypto, include the destination’s chain.
For a payment to a Ledig business, use businessId instead of recipientId. Do not send both.
Select a value from paymentMethodIds and use it as payOut.paymentMethodId. The option’s own id is a different value. An empty list means no payment method is available for that request.
External payout options include amountBands. Their minimum and maximum are outer bounds; amounts in gaps remain unsupported. See Limits.
Payment options are read-only and do not approve a payment. 423 COMPLIANCE_REVIEW_REQUIRED means the recipient needs review; keep the recipient and wait instead of retrying automatically. 404 NOT_FOUND means the requested recipient was not found.
If the selected option has invoiceRequired: true, upload the invoice through your dashboard or the upload process agreed for your integration, then include payOut.invoiceDocumentId. Contact support@ledig.io if you need help with invoice uploads. payOut.transferPurpose is optional and does not replace a required invoice.
To discover receiving methods instead, use type=deposit. Receiving funds follows the funding flow; it does not use a deposit quote.
Estimate a payout fee
POST /v1/payouts/fee-estimate requires currency, payoutType and a positive decimal amount. Crypto payouts also require the exact network. If more than one fee band matches, include the bandId from the catalogue.
This request does not create a quote or move funds. You can call it with a Read Only key that has quotes:read.
Check the returned availability and amountWithinLimits along with the fee. A fee may be listed even when sending is temporarily unavailable. Missing pricing does not mean a zero fee. Use a quote to confirm the final cost, and do not cache these responses.
Create the quote
This example converts 100 USDT to NGN and sends the result to a bank recipient. Replace the recipient and payment method IDs with values from your API responses:
For a conversion that stays in your Ledig balance, omit
payOut. For an external payment, use payOut.type: "fiat" or "crypto", an approved recipientId and an available paymentMethodId. Include chain for crypto when required by the destination.
Read fees and the total debit
Use the amounts in the response to show your customer the cost:
For example, a source amount of 100 USDT, conversion fee of 1 USDT and payout fee equivalent to 0.5 USDT would produce:
totalSourceDebitAmount already includes both fees. Do not add a payout fee to it again or add amounts in different currencies.
Show totalSourceDebitAmount before confirmation. Save the quote ID and expiresAt.
Pay a Ledig business
CallGET /v1/ledig-businesses/{businessId} with the recipient business’s exact ID. Confirm the returned business name before continuing.
Use this payOut shape in your quote:
recipientId or chain for this payment. You do not need a saved recipient. You cannot use this flow to pay the same business account you are sending from.
Expiry and readback
Use the quote beforeexpiresAt. Read it with GET /v1/quotes/{id}, or list quotes with GET /v1/quotes and cursor pagination.
Each quote can create one transfer. Both new and replayed quote responses use HTTP 201. Top-level replayed: false means a new quote; true means the original quote was returned for the same reference without refreshing its expiry. A replay may return an accepted or expired quote.
If an unused quote expires, request a new quote with a fresh reference. If you already submitted a transfer but did not receive the response, follow transfer retries using the original identifiers before requesting another quote.
Handle quote failures
A rejected quote does not move funds. If a request times out, follow the retry rules. See example error responses.