Money & currency
Amounts are integers in the minor unit
Every monetary amount in every request, response, and webhook is an integer in the smallest unit of the currency.
| Currency | Example display | API value |
|---|---|---|
| USD | $12.50 | 1250 |
| USD | $0.01 | 1 |
| LRD | LRD 100.00 | 10000 |
| LRD | LRD 1.00 | 100 |
Never use floats for money. Don’t try to be clever with division. If the value is 1250 cents USD, it’s 1250 — the API will reject 12.50 as a VALIDATION_ERROR.
If your language doesn’t have a non-float integer type for currency, use a decimal library (Python decimal, JavaScript bignumber.js, Java BigDecimal). Convert to/from cents at the API boundary, not in the middle of your code.
Supported currencies
Phase 1 (current):
| Code | Currency | Notes |
|---|---|---|
USD | US Dollar | Primary settlement currency. Cards, Stripe, USD wallets, USD merchant payouts. |
LRD | Liberian Dollar | MoMo deposits/withdrawals, LRD wallets, LRD merchant payouts. |
The two currencies share infrastructure but are separate balances. A user has a USD wallet AND an LRD wallet, not one wallet with two currencies. Cross-currency moves (USD ↔ LRD swap) lock a rate for 60 seconds before executing.
Currency codes always required
Even when there’s only one plausible currency for an endpoint, requests must specify the currency. There is no “default currency” anywhere in the API. The currency is part of the operation’s identity.
# Always include "currency"
curl -X POST "$SOXARA_BASE/v1/payments" \
-H "Authorization: Bearer $SOXARA_KEY" \
-d '{"amount": 1250, "currency": "USD", "description": "..."}'Exchange rates
Soxara quotes USD↔LRD via the fx service. Rates are sourced from multiple FX providers, mid-rate, with a small bid-ask spread Soxara captures as revenue.
Rate quotes are returned from GET /v1/fx/quote and are valid for 60 seconds. After 60 seconds the quote expires and you must request a new one. This is a hard constraint — you cannot execute a swap against an expired quote.
Rounding
When converting between currencies, Soxara rounds down on the customer-facing amount and absorbs the partial cent on the platform side. This protects the customer from off-by-one disputes.
A swap from 1234 USD cents at rate 181 LRD/USD wouldn’t return 1234 × 181 = 223354 LRD minor units — it would return 223300 (rounded down to the nearest LRD 1.00) and the remaining 54 minor units stay with the platform.
You’ll see the actual rounded amounts in the FX quote response — there’s no math to do on your end.