Skip to main content

Quotes and exchange rates

An indicative exchange rate is a current rate for display. To show the customer the cost of a transfer before they confirm it, use a quote. A quote fixes the amounts, fees and exchange rate of one transfer for a limited time.

Indicative exchange rates​

List exchange rates returns indicative rates between the currencies that Nodu supports for transfers.

  • rates is a map. Each key is a currency pair, such as eur/usdc. The value is the amount of the second currency that one unit of the first currency buys.
  • lastUpdatedAt is the time of the rates in the response.
  • The query parameter base limits the response to the pairs that start with one currency.

Use these rates to show an approximate rate, for example before the customer enters an amount. Do not use them to calculate what a customer pays or receives:

  • The response contains no fees. A transfer's exchange rate can differ from the indicative rate.
  • The rates are not specific to a customer. A pair in the response does not mean that the customer has payment channels for it.

Create a quote​

Call Create a quote with the customerId, the currency and rail of the source, the currency and rail of the destination, and one amount:

  • source.amount, when the customer chooses the amount to send.
  • destination.amount, when the customer chooses the amount that the recipient receives.

Send exactly one of the two. Nodu calculates the other one. The field basis in the response says which amount you sent: source or destination. How transfers work explains sources, destinations and rails.

In this example, the customer sends usdc on base, and the recipient receives exactly 100 eur by SEPA. The values are examples.

curl https://api.sandbox.nodu.fi/v1/quotes \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <new-uuid>' \
--data '{
"customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
"developerFee": "0.5",
"source": {"currency": "usdc", "paymentRail": "base"},
"destination": {"amount": "100", "currency": "eur", "paymentRail": "sepa"}
}'

An illustrative excerpt of the response; use the returned values for your transfer:

{
"id": "01963a52-6c1e-7b4f-a2d9-3e5c8f0b1a77",
"basis": "destination",
"source": {"amount": "125.75", "currency": "usdc", "paymentRail": "base"},
"destination": {"amount": "100", "currency": "eur", "paymentRail": "sepa"},
"breakdown": {
"initialAmount": "125.75",
"developerFee": "0.5",
"serviceFee": "0.25",
"subtotalAmount": "125",
"exchangeRate": "0.8",
"exchangedAmount": "100",
"finalAmount": "100"
},
"quotedAt": "2026-10-15T00:00:00+00:00",
"expiresAt": "2026-10-15T00:02:00+00:00",
"accepted": false
}

The customer pays source.amount: 125.75 usdc. A payout to a bank account has no networkFee, so the field is absent.

A quote has the same conditions as a transfer: the customer has status=active and an active payment channel on each side.

The breakdown and the fees​

The quote's breakdown shows each step from source.amount to destination.amount: the fees, the exchange rate and the amount that the recipient receives. A quote has up to three fees:

  • serviceFee is Nodu's fee.
  • developerFee is your own fee. You set it in the quote request as a fixed amount.
  • networkFee applies to a payout to a crypto wallet.

Fees and how amounts are calculated explains each fee and the calculation, with an example.

Show the customer the returned breakdown. Do not calculate fees yourself.

If the amount does not cover the fees, Nodu returns a business rule violation with rule=insufficient_transfer_amount. An amount outside the transfer limits also causes a business rule violation, for example with rule=transfer_amount_below_minimum. The detail field of the error states the amounts.

How long a quote is valid​

A quote fixes its fees and its exchange rate until the time in expiresAt. That time is 2 minutes after quotedAt, the time of the last calculation. Create the transfer before expiresAt. Use expiresAt in your code, not a timer of your own.

If the customer needs more time, or changes the amount, call Update a quote. You can send a new source.amount or destination.amount, and a new developerFee. A field that you leave out keeps its value. Nodu recalculates the quote. Read quotedAt and expiresAt from the response. Show the new figures to the customer.

  • To change the currencies or the rails, create a new quote.
  • An update within 30 seconds of quotedAt keeps the exchange rate, quotedAt and expiresAt. The amounts and the fees follow the values that you sent. A later update also returns a new exchange rate, a new quotedAt and a new expiresAt.

Use a quote in a transfer​

  1. Show the amounts and the fees to the customer. Obtain the customer's confirmation.
  2. Call Create a transfer with the id of the quote in quoteId, before expiresAt.
  3. Send values that match the quote:
    • amount equals the quote's source.amount. This is also true when you created the quote with destination.amount.
    • The source has the currency and rail of the quote's source.
    • The destination's external account has the currency and rail of the quote's destination.
    • developerFee equals the quote's developerFee. You can also leave it out: Nodu then takes the fee from the quote.

Nodu applies the fees and the exchange rate of the quote to the transfer. The quote then has accepted=true, and acceptedAt is the time of acceptance. A quote serves one transfer. If you later update the unfunded transfer, Nodu rebuilds its receipt; read the new figures before requesting payment.

quoteId is optional. Without a quote, Nodu fixes no exchange rate in advance. The receipt of the transfer shows the rate after Nodu converts the funds.

How long a transfer keeps the quoted rate​

Nodu holds the exchange rate and the network fee of an accepted quote for 15 minutes after the quote's acceptedAt. What the recipient receives depends on when Nodu starts to convert the funds:

  • Within the 15 minutes. The recipient receives the quote's destination.amount.
  • After the 15 minutes. Nodu recalculates the transfer from its source amount. developerFee and serviceFee stay as quoted. Nodu takes a new exchange rate and a new network fee, and calculates a new amount for the recipient. This also applies to a quote that you created with destination.amount: the customer has paid the source amount, so the amount that the recipient receives changes.

Nodu starts to convert the funds after the customer's payment arrives and the transfer passes its checks. A bank payment that arrives later than 15 minutes after acceptedAt therefore leads to a recalculation. Tell the customer, before they confirm, how long the quoted amount applies.

After a recalculation, the transfer's receipt shows the new exchangeRate, networkFee and finalAmount. Retrieve a transfer returns them, and so do the transfer's later webhook events. Show the customer the figures of the receipt, not the figures of the quote.

When Nodu refuses a transfer with a quote​

What you receiveMeaningWhat you do
The rule quote_expiredexpiresAt has passed.Call Update a quote. Show the new figures to the customer. Ask the customer to confirm them again. Then create the transfer.
The rule quote_already_acceptedThe quote was already used for a transfer.Create a new quote.
The rule quote_mismatchA value in the transfer request differs from the quote. detail names the value.Send the values listed in Use a quote in a transfer.
The status 404The quote does not exist for this customer. A quote that expired without being used can also return 404.Create a new quote.

Next steps​