Amounts, currencies and exchange rates

Three kinds of amount appear in the API: the price, in the currency you set; its value in US dollars, for reporting; and coin amounts, for what customers send and what reaches your wallet.

A price is an integer in minor units with its currency: 4900 with EUR is €49.00. Links and payments take any of these currencies, from the equivalent of $1.00 up to 1,000,000.00 in the currency. Card payment limits depend on the available route, currency and customer region.

These rates and minimums are examples. The backend uses its current exchange rate to enforce the minimum price when you create or update a link.

The customer pays the price in its own currency, and the receipt shows it that way. A payment's customer_fee and amount_received are in minor units of its currency too: any fee passed on to the customer, and how much of the price and that fee has arrived.

Everything you add up is in US cents: a payment's reporting, with its amount, fee, customer_fee and net, a link's volume, a customer's stats, metrics, and every *_usd field on the wallet. A price becomes US cents at its currency's usd_rate, rounded to the nearest cent: €49.00 is 4900 × 1.08 = 5292, or $52.92.

Fees are taken on that US dollar value at the rail's fee_rate_bps: 0 for crypto and 300 for cards, in hundredths of a percent. A payment shows a fee once it succeeds. When you pass fees on, the customer's share is worked out in the price's currency, with the flat fee converted from US cents at its usd_rate and rounded to the nearest minor unit.

{  "amount": 4900,  "currency": "EUR",  "fee_payer": "business",  "customer_fee": 0,  "amount_received": 0,  "reporting": {    "currency": "USD",    "amount": 5292,    "fee": 0,    "transaction_fee": 0,    "customer_fee": 0,    "net": 0  }}

Coin amounts are decimal strings, such as "52.92", so no precision is lost. Each coin is quoted to a fixed number of decimal places.

A checkout works out the coin amount from the price's US dollar value and the coin's price, rounded to the coin's decimal places, and shows the rate it used in crypto.rate: one coin in minor units of the price's currency. Stablecoins count as one US dollar each.

{  "asset": "USDC",  "network": "polygon",  "amount": "52.92",  "rate": {    "amount": 93,    "currency": "EUR"  }}

• The checkout locks the amount and rate when it opens, for the quote window in your checkout settings, 15 minutes unless you change it.
• A payment's method.amount is what arrived in the coin, and settlement.amount what reached your wallet after the fee.
• A card payment reaches your wallet in the selected coin and network. Read its deposit insettlement for the delivered asset, network and amount, whatever the price's currency.

GET /exchange-rates returns the rates checkout quotes with: each coin's price_usd in US cents, and each currency's usd_rate in US dollars. It's public, so a page you build can show a price in coins before the customer opens a checkout.