Tokens and rates

Live source of truth: always call GET /meta/tokens for the supported tokens/addresses in your current environment (Sandbox vs Production). The list below is a snapshot for reference.

​

Supported tokens (snapshot)

Note: addresses can differ by environment. Always use /meta/tokens in the target environment to get the canonical list (and decimals).

​

Environment & token mismatch

• Testnet tokens will not work in Production. Use testnet tokens strictly in Sandbox.
• If a token isn’t configured for the current environment, the server should return a 400 explaining the mismatch instead of failing later.

{
  "status": "error",
  "message": "Token not supported in env=live",
  "data": {
    "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "hint": "Call /meta/tokens for supported tokens in this environment"
  }
}

{
  "status": "error",
  "message": "No USDC configured for env=live",
  "data": { "token": "USDC" }
}

​

Preview a quote (no auth)

• amount_fiat (KES): positive number
• token: USDC | USDT | WXM
• order_type: OnRamp|OffRamp or 0|1 (defaults to OnRamp)

• rate: KES per token after markup
• token_amount: tokens the user would receive (OnRamp) or must send (OffRamp)
• fiat_paid: echo of input
• symbol, decimals: metadata

curl -G "$BASE_URL/quote" \
--data-urlencode "amount_fiat=100" \
--data-urlencode "token=USDC" \
--data-urlencode "order_type=OnRamp"

curl -G "$BASE_URL/quote" \
--data-urlencode "amount_fiat=1750" \
--data-urlencode "token=USDT" \
--data-urlencode "order_type=OffRamp"

{
  "status": "success",
  "message": "Quote computed",
  "data": {
    "rate": 132.712345,
    "token_amount": 0.753621,
    "fiat_paid": 100,
    "symbol": "USDC",
    "decimals": 6
  }
}

• 400 bad_order_type → order_type must be 0|1 or OnRamp|OffRamp
• 400 unknown_token / token_env_mismatch
• 429 rate limited; respect Retry-After
• 502 upstream price provider error

​

Units & decimals

• Fields like token_amount and amount_sent are human units (e.g., 12.34 USDC).
• ERC-20 approvals must be in base units (integers), using the token’s decimals.

import { parseUnits } from "ethers";
const amountHuman = "12.34";   // 12.34 USDC
const decimals = 6;            // from /meta/tokens or the /quote response
const amountBase = parseUnits(amountHuman, decimals); // 12340000

​

Off-ramp approvals (ERC-20)

{
  "status": "error",
  "message": "Approve the contract to spend your tokens before OffRamp.",
  "data": { "required": 79218430, "current": 0 }
}

import { Contract, parseUnits } from "ethers";
import erc20 from "./erc20.json" assert { type: "json" };

const token = new Contract(TOKEN_ADDRESS, erc20, signer);
const amountBase = parseUnits("50", 6); // e.g., approve 50.0 for USDC (6 decimals)

// Replace with the Element Pay spender for your environment
await token.approve(ELEMENTPAY_SPENDER_ADDRESS, amountBase);

• Approve just-enough (or a reasonable buffer), not unlimited.
• Reuse allowance across multiple off-ramp orders until depleted.
• Handle insufficient_balance similarly (you’ll get required vs current in data).

​

Putting it together

1. Call /meta/tokens to get supported tokens, addresses, and decimals (for your environment).
2. Call /quote to preview rate and token_amount before creating an order.
3. For OffRamp, ensure allowance ≥ required amount (approve if needed).
4. Create the order via POST /orders/create and track via webhooks or GET /orders/tx/{tx_hash}.

• API Reference → Quote
• API Reference → Create Order
• API Reference → Webhooks