Quickstart
Make an authenticated read, request a quote and follow an instruction without losing its original references.
1. Configure access
Store the base URL, public credential ID and secret provided to your institution in your backend secret store. Do not expose API keys in browser code, mobile bundles, URLs or logs. Confirm enabled currencies and workflows before sending instructions.
curl "$OSAI_API_BASE_URL/v1/balances" \
-H "Authorization: ApiKey $OSAI_PUBLIC_ID:$OSAI_API_SECRET" \
-H "X-Osai-Correlation-Id: balance-read-1042"2. Prepare your event receiver
Configure an HTTPS receiver and the event types needed by your workflow. Verify signatures against the raw body and record events durably before acknowledging them. Use event IDs for deduplication.
3. Request a quote
This example fixes an all-in NGN source debit of 100000 minor units: ₦1,000.00, including fees. It illustrates request format; price and availability depend on the configured route. Review expiry, fees, total debit and beneficiary requirements before accepting.
curl -X POST "$OSAI_API_BASE_URL/v1/quotes" \
-H "Authorization: ApiKey $OSAI_PUBLIC_ID:$OSAI_API_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quote-order-1042" \
-d '{"quote_mode":"FIXED_SOURCE","base_amount_minor":100000,"base_currency":"NGN","quote_currency":"USD","customer_reference":"order-1042"}'4. Accept the selected terms
Use the returned quote ID in the path and body. Include an approved beneficiary where required by the settlement route. Use a distinct stable idempotency key for acceptance and retain the trade ID.
curl -X POST "$OSAI_API_BASE_URL/v1/quotes/$QUOTE_ID/accept" \
-H "Authorization: ApiKey $OSAI_PUBLIC_ID:$OSAI_API_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: accept-order-1042" \
-d "{\"quote_id\":\"$QUOTE_ID\",\"beneficiary_id\":\"$BENEFICIARY_ID\"}"5. Track and reconcile
Read GET /v1/trades/{trade_id} and consume agreed event subscriptions. Use settlement reports and transaction history to reconcile. A successful HTTP response alone does not confirm settlement. After a timeout, look up the original instruction before retrying it.