Conversion Rates

Use the Rates API to preview exact fees, exchange rates, and net amounts before initiating any transfer or collection. This lets you show your customers a transparent cost breakdown and validate amounts on your end without creating a real transaction.

Base path: /v1/rates Authentication: API Key (Authorization: <secret-key>)

---

Endpoints

Method	Path	Description
GET	/v1/rates/fiat-transfer	Preview fees for sending fiat to a bank account
GET	/v1/rates/crypto-transfer	Preview fees for sending crypto to a wallet address
GET	/v1/rates/fiat-collection	Preview fees for collecting a fiat payment
GET	/v1/rates/crypto-collection	Preview fees for collecting a crypto payment

All four endpoints are read-only — no funds are moved, no transaction is created.

---

Response Fields

All endpoints return the same base shape. Fields specific to an endpoint are noted inline.

Field	Type	Description
platformFeeInFiat	number	IvoryPay platform fee expressed in the fiat currency
platformFeeInCrypto	number	IvoryPay platform fee expressed in the crypto token
totalAmountInFiat	number	Total fiat amount including all fees
amountInFiatLessFee	number	Net fiat amount after fees are deducted
fiatCurrency	string	Resolved fiat currency code (e.g. NGN)
totalAmountInCrypto	number	Total crypto amount including all fees
amountInCryptoLessFee	number	Net crypto amount after fees are deducted
minimumAmountInFiat	number	Minimum fiat amount accepted for this operation
minimumAmountInCrypto	number	Minimum crypto amount accepted for this operation
rate	number	Current fiat exchange rate for the token (e.g. USDT/NGN)
token	string	The crypto token used for the quote
gasFeeInCrypto	number	On-chain gas fee in crypto. Crypto transfer only.
minimumAmountInFiatCurrency	string	Currency code for the minimum fiat amount. Fiat transfer only.

---

GET /v1/rates/fiat-transfer

Returns a fee and rate breakdown for a fiat bank transfer (crypto-to-fiat payout). Use this to show the recipient amount before calling POST /v1/fiat-transfer.

Query Parameters

Parameter	Type	Required	Description
amount	number	Yes	Amount in crypto to quote against. Must be positive.
token	string	Yes	Crypto token to debit (e.g. USDT, USDC).
fiatCurrency	string	Yes	Target fiat currency for the recipient (e.g. NGN).

Request

GET /api/v1/rates/fiat-transfer?amount=100&token=USDT&fiatCurrency=NGN
Authorization: <your-secret-api-key>

Response

{
  "status": true,
  "message": "Fiat transfer rates fetched successfully",
  "data": {
    "platformFeeInFiat": 250.00,
    "platformFeeInCrypto": 0.163,
    "totalAmountInFiat": 155250.00,
    "amountInFiatLessFee": 155000.00,
    "fiatCurrency": "NGN",
    "totalAmountInCrypto": 100,
    "amountInCryptoLessFee": 99.837,
    "minimumAmountInFiat": 5000.00,
    "minimumAmountInFiatCurrency": "NGN",
    "minimumAmountInCrypto": 3.22,
    "rate": 1550,
    "token": "USDT"
  }
}

---

GET /v1/rates/crypto-transfer

Returns a fee and rate breakdown for a crypto payout to a blockchain wallet address. Includes on-chain gas fees. Use this before calling POST /v1/crypto-transfer.

Query Parameters

Parameter	Type	Required	Description
amount	number	Yes	Amount in crypto to send. Must be positive.
token	string	Yes	Crypto token to send (e.g. USDT, USDC).
network	string	Yes	Blockchain network (e.g. BSC_TESTNET, ETH). See networks.
fiatCurrency	string	Yes	Your fiat currency used to calculate fee equivalents (e.g. NGN).
address	string	Yes	Recipient's wallet address. Used to estimate gas for the specific destination.

Request

GET /api/v1/rates/crypto-transfer?amount=50&token=USDT&network=BSC_TESTNET&fiatCurrency=NGN&address=0xAbC123...
Authorization: <your-secret-api-key>

Response

{
  "status": true,
  "message": "Crypto transfer rates fetched successfully",
  "data": {
    "platformFeeInFiat": 125.00,
    "platformFeeInCrypto": 0.081,
    "totalAmountInFiat": 77625.00,
    "amountInFiatLessFee": 77500.00,
    "gasFeeInCrypto": 0.002,
    "fiatCurrency": "NGN",
    "totalAmountInCrypto": 50,
    "amountInCryptoLessFee": 49.917,
    "minimumAmountInFiat": 5000.00,
    "minimumAmountInCrypto": 3.22,
    "rate": 1550,
    "token": "USDT"
  }
}

---

GET /v1/rates/fiat-collection

Returns a fee and rate breakdown for accepting a fiat payment from a customer (e.g. a customer paying by bank transfer). Use this to show customers exactly how much they need to pay and what you will receive.

Query Parameters

Parameter	Type	Required	Description
amount	number	Yes	Amount in fiat the customer will pay. Must be positive.
token	string	Yes	Crypto token you want to receive (e.g. USDT, USDC).
fiatCurrency	string	Yes	Fiat currency of the payment (e.g. NGN).

Request

GET /api/v1/rates/fiat-collection?amount=50000&token=USDT&fiatCurrency=NGN
Authorization: <your-secret-api-key>

Response

{
  "status": true,
  "message": "Collection rates fetched successfully",
  "data": {
    "platformFeeInFiat": 250.00,
    "platformFeeInCrypto": 0.163,
    "totalAmountInFiat": 50250.00,
    "amountInFiatLessFee": 50000.00,
    "fiatCurrency": "NGN",
    "totalAmountInCrypto": 32.42,
    "amountInCryptoLessFee": 32.26,
    "minimumAmountInFiat": 5000.00,
    "minimumAmountInCrypto": 3.22,
    "rate": 1550,
    "token": "USDT"
  }
}

---

GET /v1/rates/crypto-collection

Returns a fee and rate breakdown for accepting a crypto payment directly from a customer's wallet on a specific blockchain network.

Query Parameters

Parameter	Type	Required	Description
amount	number	Yes	Amount in crypto the customer will send. Must be positive.
token	string	Yes	Crypto token the customer will send (e.g. USDT, USDC).
network	string	Yes	Blockchain network the payment will arrive on. See networks.
fiatCurrency	string	Yes	Your fiat currency used to calculate fee equivalents (e.g. NGN).

Request

GET /api/v1/rates/crypto-collection?amount=30&token=USDT&network=BSC_TESTNET&fiatCurrency=NGN
Authorization: <your-secret-api-key>

Response

{
  "status": true,
  "message": "Collection rates fetched successfully",
  "data": {
    "platformFeeInFiat": 150.00,
    "platformFeeInCrypto": 0.097,
    "totalAmountInFiat": 46650.00,
    "amountInFiatLessFee": 46500.00,
    "fiatCurrency": "NGN",
    "totalAmountInCrypto": 30,
    "amountInCryptoLessFee": 29.903,
    "minimumAmountInFiat": 5000.00,
    "minimumAmountInCrypto": 3.22,
    "rate": 1550,
    "token": "USDT"
  }
}

---

Error Responses

Status	Message	Cause
400	Your provided fiat currency is currently not supported	fiatCurrency is not active on IvoryPay
400	Currencies are currently not activated for conversion	No active currencies configured on the platform
400	token must be a supported crypto currency	token is not a valid enum value
400	network must be a supported blockchain network	network is not a valid enum value
400	amount must be a positive number	amount is zero or negative
401	Unauthorized	Missing or invalid API key

---

Supported Values

token

Value	Name
USDT	Tether USD
USDC	USD Coin

fiatCurrency

Value	Currency
NGN	Nigerian Naira
KES	Kenyan Shilling
GHS	Ghanaian Cedi
ZAR	South African Rand
USD	US Dollar

Networks

Value	Chain
BSC_TESTNET	BNB Smart Chain Testnet
ETH	Ethereum
TRON	Tron
MATIC	Polygon

---

Code Examples

Node.js

const axios = require('axios');

const BASE_URL = 'https://api.ivorypay.io/api/v1';
const API_KEY = process.env.IVORYPAY_SECRET_KEY;

// Preview fiat transfer cost before initiating
const { data } = await axios.get(`${BASE_URL}/rates/fiat-transfer`, {
  params: {
    amount: 100,
    token: 'USDT',
    fiatCurrency: 'NGN',
  },
  headers: { Authorization: API_KEY },
});

const rates = data.data;
console.log(`Rate: 1 USDT = ${rates.rate} NGN`);
console.log(`Platform fee: ${rates.platformFeeInFiat} NGN`);
console.log(`Recipient gets: ${rates.amountInFiatLessFee} NGN`);

cURL

BASE_URL="https://api.ivorypay.io/api/v1"

# Fiat transfer rates
curl -G "$BASE_URL/rates/fiat-transfer" \
  -H "Authorization: live_sk_xxxxxxxxxxxx" \
  --data-urlencode "amount=100" \
  --data-urlencode "token=USDT" \
  --data-urlencode "fiatCurrency=NGN"

# Crypto transfer rates (with recipient address for gas estimate)
curl -G "$BASE_URL/rates/crypto-transfer" \
  -H "Authorization: live_sk_xxxxxxxxxxxx" \
  --data-urlencode "amount=50" \
  --data-urlencode "token=USDT" \
  --data-urlencode "network=BSC_TESTNET" \
  --data-urlencode "fiatCurrency=NGN" \
  --data-urlencode "address=0xAbC123..."

# Fiat collection rates
curl -G "$BASE_URL/rates/fiat-collection" \
  -H "Authorization: live_sk_xxxxxxxxxxxx" \
  --data-urlencode "amount=50000" \
  --data-urlencode "token=USDT" \
  --data-urlencode "fiatCurrency=NGN"

# Crypto collection rates
curl -G "$BASE_URL/rates/crypto-collection" \
  -H "Authorization: live_sk_xxxxxxxxxxxx" \
  --data-urlencode "amount=30" \
  --data-urlencode "token=USDT" \
  --data-urlencode "network=BSC_TESTNET" \
  --data-urlencode "fiatCurrency=NGN"

Python

import requests

BASE_URL = 'https://api.ivorypay.io/api/v1'
HEADERS = {'Authorization': 'live_sk_xxxxxxxxxxxx'}

# Preview crypto collection rates
resp = requests.get(
    f'{BASE_URL}/rates/crypto-collection',
    params={
        'amount': 30,
        'token': 'USDT',
        'network': 'BSC_TESTNET',
        'fiatCurrency': 'NGN',
    },
    headers=HEADERS,
)

rates = resp.json()['data']
print(f"Rate: 1 USDT = {rates['rate']} NGN")
print(f"You receive: {rates['amountInCryptoLessFee']} USDT")
print(f"Minimum: {rates['minimumAmountInCrypto']} USDT")

---

Best Practices

1. Always call rates before initiating. Lock the rate and display the breakdown to your user. Rates are live and will change between calls.

2. Respect the minimum amounts. If the user's amount is below minimumAmountInFiat or minimumAmountInCrypto, reject it on your side before calling the transfer endpoint — it will fail otherwise.

3. Use gasFeeInCrypto for crypto transfers. Account for this in your UI so users understand the total deduction from their crypto balance.

4. Do not cache rate responses. Exchange rates are volatile. Always fetch a fresh quote immediately before displaying to a user or initiating a transaction.