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 a decimal string in whole units of its currency, with two decimal places: "49.00" with EUR is €49.00. Every supported currency has two decimal places, so every fiat amount in a response is written that way, "0.00" for nothing and "-3.00" below zero. When you send a price, "49.00", "49.5" and "49" are all accepted; a JSON number, or more than two decimal places, returns 400 invalid_request. 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 decimal strings in its currency too.

Read an amount with a decimal type, such as Python's Decimal or a numeric column, rather than a binary float, so sums stay exact to the cent.

Everything you add up is in US dollars, as decimal strings: a payment's reporting, with its amount, fee, customer_fee and net, a link's volume, a customer's stats, metrics (whose values are JSON numbers in whole dollars), and every *_usd field on the wallet. A price becomes US dollars at its currency's usd_rate, rounded to the nearest cent: €49.00 is 49.00 × 1.08 = "52.92", or $52.92.

{
  "amount": "49.00",
  "currency": "EUR",
  "fee_payer": "business",
  "customer_fee": "0.00",
  "amount_received": "0.00",
  "reporting": {
    "currency": "USD",
    "amount": "52.92",
    "fee": "0.00",
    "transaction_fee": "0.00",
    "customer_fee": "0.00",
    "net": "0.00"
  }
}

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 the price's currency, as a decimal string. Stablecoins count as one US dollar each.

{
  "asset": "USDC",
  "network": "ethereum",
  "amount": "52.92",
  "rate": {
    "amount": "0.93",
    "currency": "EUR"
  }
}

{
  "asset": "BTC",
  "network": "bitcoin",
  "amount": "0.00053780",
  "rate": {
    "amount": "91111.11",
    "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.
• 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, a decimal string in US dollars, and each currency's usd_rate, a number of US dollars. It's public, so a page you build can show a price in coins before the customer opens a checkout.