Rate Quotes & Spread

All deposit and withdrawal quotes include a spread applied on top of the live market FX rate. The spread is agreed during onboarding and configured on your program.

effective_rate = market_rate × (1 + spread_bps / 10000)

• On deposits: the spread reduces the USDC amount the user receives.
• On withdrawals: the spread reduces the KES amount the user receives.

The spread_bps field is included in every quote response so you can display it to your users.

---

Quote lifecycle

Property	Value
Validity	10 minutes from issue
Reuse	Single-use — consumed on a successful deposit or withdrawal
Expiry	RATE_EXPIRED error if used after 10 minutes or after first use

---

Spread guard (max_spread_bps)

Both deposit and withdrawal endpoints accept an optional max_spread_bps parameter. If the effective spread at execution time exceeds this threshold, the request is rejected with SPREAD_EXCEEDED before any M-Pesa call is made.

Use this to protect your users from unexpectedly wide spreads during periods of FX volatility.

{
  "amount_kes": 5000,
  "auto_confirm_rate": true,
  "max_spread_bps": 50
}