API endpoints for viewing or calculating exchange rates.
Orbital provides a way to check exchange rates between cryptocurrencies and fiat currencies (e.g., BTC to USD). This can be used:
- Before a transaction: Show customers the approximate amount of crypto they need to pay or will receive.
- After a transaction: View the rates that were actually applied so you can audit and reconcile payments.
Here's how to use rates in different in your payment process:
1. Indicative Rate API (Crypto Rate API)
This is an API endpoint designed to help you, the merchant, show real-time exchange rates to your customers before they pay or withdraw funds. This makes it easier for them to understand how much cryptocurrency (or fiat) they’re sending or receiving.
Rate for Payins
When your customer wants to deposit funds using cryptocurrency, you'll use the indicative rate to show them how much crypto (Currency
) they need to send to match the amount you want to credit them in your cashierCurrency
(the currency your platform uses internally).
Example:
- Your
cashierCurrency
is GBP. - Your customer wants to pay with USDT.
- You call
/crypto/rate
withticker: USDT_GBP
and the amount of USDT they plan to send (or calculate based on the GBP amount you want to receive).
The API returns the exchange rate and the equivalent GBP amount so you can show them:
"To pay £100 GBP, you need to send 135 USDT."
This helps the customer know exactly how much crypto to send so their account is credited with the right amount of cashier currency.
Rate for Payouts
When your customer wants to withdraw funds from your platform, you might offer to pay them in cryptocurrency (targetCurrency
) even though your system balances or payouts are usually denominated in your cashierCurrency
.
Example:
- Your
cashierCurrency
is USD (you keep balances in USD). - The customer wants to receive their withdrawal in USDT (target currency).
- You call
/crypto/rate
withticker: USDT_USD
and the USD amount you’re paying out.
The API returns the exchange rate and the equivalent USDT amount so you can show them:
"Your withdrawal of $500 USD equals 499.00 USDT."
This helps your customer know exactly how much crypto they’ll receive and lets them double-check that before you send it.
2. Transaction Rate in API Responses
When you initiate a Payin transaction, the API response will contain a rates array that shows the conversion that took place. This is different from the indicative rate you fetch using /crypto/rate
. These are the actual rates applied to the transaction. Each entry in this array shows:
- The currencies being converted
- The exact amount converted
- The precise exchange rate used
Example
"rates": [
{
"ticker": "GBP_USD",
"amount": "1.00",
"price": "1.35",
"rate": "1.3468194858"
}
]
Field | Description | |
---|---|---|
ticker | The currency pair being converted | |
amount | Amount of cryptocurrency that the payer sends. | |
price | The equivalent amount in the cashierCurrency that is displayed on the merchant platform. | |
rate | The exact rate used in calculations |