Exchange Rates

Get real-time conversion rates between supported cryptocurrencies and fiat currencies.

Endpoint: GET /ratesAuthentication: Required (x-api-key header)

Quick Examples

curl -X GET "https://staging.elementpay.net/api/v1/rates?currency=usdc" \
  -H "x-api-key: YOUR_API_KEY"

Query Parameters

currency

string

default:"usdc"

Token symbol to get rates for. Supported: usdc, eth, wxm, usdt_lisk

fiat

string

default:"kes"

Fiat currency code. Supported: kes, ugx, tzs, ngn, ghs

amount

number

Optional amount to calculate conversion for (returns converted amount)

Response Format

{
  "currency": "usdc",
  "fiat": "kes",
  "base_rate": 144.97,
  "marked_up_rate": 148.59,
  "markup_percentage": 2.5,
  "last_updated": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-15T10:35:00Z"
}

Response Fields

base_rate

number

Raw market rate without markup

marked_up_rate

number

Final rate including platform markup (use this for calculations)

markup_percentage

number

Platform fee percentage applied to the base rate

expires_at

string

When this rate quote expires (ISO 8601 format)

Rate Calculation Examples

Calculate Token Amount for Offramp

When creating an offramp order, calculate how many tokens to approve:

// Get current rate
const rateResponse = await fetch('/api/v1/rates?currency=usdc');
const { marked_up_rate } = await rateResponse.json();

// Calculate tokens needed for 1000 KES
const fiatAmount = 1000;
const tokensNeeded = fiatAmount / marked_up_rate;

console.log(`Need ${tokensNeeded} USDC for ${fiatAmount} KES`);

// Approve tokens before creating order
const approveAmount = ethers.parseUnits(
  tokensNeeded.toString(), 
  6 // USDC decimals
);

Calculate Fiat Amount for Onramp

For onramp orders, calculate how much crypto user will receive:

// Get current rate
const rateResponse = await fetch('/api/v1/rates?currency=usdc');
const { marked_up_rate } = await rateResponse.json();

// Calculate crypto for 1000 KES payment
const fiatAmount = 1000;
const cryptoAmount = fiatAmount / marked_up_rate;

console.log(`${fiatAmount} KES = ${cryptoAmount} USDC`);

Multi-Currency Rate Comparison

Compare rates across different tokens:

const tokens = ['usdc', 'eth', 'wxm'];
const rates = {};

for (const token of tokens) {
  const response = await fetch(`/api/v1/rates?currency=${token}`);
  const data = await response.json();
  rates[token] = data.marked_up_rate;
}

console.log('Current rates:', rates);

Rate Validity

Rate Expiration: Rates are valid for 5 minutes. Always fetch fresh rates before creating orders.Slippage Protection: Rates may change between fetching and order creation. Consider adding slippage tolerance.

Supported Token Pairs

Token	Networks	Fiat Currencies
USDC	Base, Arbitrum, Ethereum, Scroll	KES, UGX, TZS, NGN, GHS
USDT	Lisk, Tron, BNB Chain, Polygon	KES, UGX, TZS, NGN, GHS
ETH	Ethereum	KES, UGX, TZS, NGN, GHS
WXM	Arbitrum	KES, UGX, TZS, NGN, GHS
CUSD	Celo	KES, UGX, TZS, NGN, GHS
CNGN	Celo	NGN

Error Handling

{
  "status": "error",
  "message": "Unsupported currency pair",
  "code": "UNSUPPORTED_PAIR",
  "details": {
    "currency": "btc",
    "fiat": "kes",
    "supported_currencies": ["usdc", "eth", "wxm", "usdt_lisk"]
  }
}

API documentation

Core Endpoints

Testing & Integration

Exchange Rates

Exchange Rates

Quick Examples

Query Parameters

Response Format

Response Fields

Rate Calculation Examples

Rate Validity

Supported Token Pairs

Error Handling

Next Steps

Create Order

Track Order

API documentation

Core Endpoints

Testing & Integration

​Exchange Rates

​Quick Examples

​Query Parameters

​Response Format

​Response Fields

​Rate Calculation Examples

​Rate Validity

​Supported Token Pairs

​Error Handling

​Next Steps

Create Order

Track Order

Exchange Rates

Quick Examples

Query Parameters

Response Format

Response Fields

Rate Calculation Examples

Rate Validity

Supported Token Pairs

Error Handling

Next Steps