Skip to main content

​
Quote API

The Quote API allows you to get real-time conversion rates before creating a payment. This is useful for displaying the expected crypto amount to your users.

​
Get Quote

Returns the current conversion rate and calculated crypto amount for a given fiat amount, token, and network.
Authentication: Requires a Public Key (cp_pk_test_ or cp_pk_live_)
POST /api/v1/payments/quote

​
Request Body

ParameterTypeRequiredDescription
amountnumberYesThe fiat amount to convert
tokenstringYesThe cryptocurrency token (USDT or USDC)
networkstringYesThe blockchain network (see Supported Networks)
collectInUSDbooleanNoIf true, treat the amount as USD. Default: false

​
Example Request

curl -X POST https://api.chainpal.org/api/v1/payments/quote \
  -H "Authorization: Bearer cp_pk_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "token": "USDC",
    "network": "base"
  }'

​
Response

{
  "success": true,
  "message": "quote fetched successfully",
  "data": {
    "rate": "1650.50",
    "cryptoAmount": "3.029024",
    "fiatAmount": "5000.00",
    "currency": "NGN"
  }
}

​
Response Fields

FieldTypeDescription
ratestringThe conversion rate (1 crypto = X fiat)
cryptoAmountstringThe calculated crypto amount the customer needs to pay
fiatAmountstringThe fiat amount (formatted to 2 decimal places)
currencystringThe fiat currency code based on your account’s country

​
How Rates Work

​
Local Currency Collection

When collectInUSD is false (default), the amount is treated as your local currency (NGN, GHS, KES, or ZAR based on your account country). 
{
  "amount": 5000,
  "token": "USDC",
  "network": "base"
}
The API calculates: cryptoAmount = amount / rate

​
USD Collection

When collectInUSD is true, the amount is treated as USD regardless of your account’s country: 
{
  "amount": 100,
  "token": "USDC",
  "network": "base",
  "collectInUSD": true
}
For USD collection, the crypto amount is calculated using the token’s USD market price.

​
Rate Validity

Rates are indicative and subject to change. The actual rate applied will be determined when the customer completes the checkout. For the most accurate pricing, direct customers to checkout promptly after displaying a quote.

​
Supported Token/Network Combinations

The available token/network combinations depend on your account’s country. See Types & Enums for the complete list.

​
Example: Nigerian Merchant

# USDC on Base - Supported
curl -X POST https://api.chainpal.org/api/v1/payments/quote \
  -H "Authorization: Bearer cp_pk_test_abc123" \
  -d '{"amount": 5000, "token": "USDC", "network": "base"}'

# USDC on Celo - Supported
curl -X POST https://api.chainpal.org/api/v1/payments/quote \
  -H "Authorization: Bearer cp_pk_test_abc123" \
  -d '{"amount": 5000, "token": "USDC", "network": "celo"}'

# USDT on Polygon - Supported
curl -X POST https://api.chainpal.org/api/v1/payments/quote \
  -H "Authorization: Bearer cp_pk_test_abc123" \
  -d '{"amount": 5000, "token": "USDT", "network": "polygon"}'

​
Error Responses

StatusMessageDescription
400pair not supportedThe token/network combination is not available for your country
400amount must be at least XAmount is below the minimum limit
400amount cannot exceed XAmount is above the maximum limit