Making requests

Base URLs, headers, JSON, idempotency and pagination.

A few conventions apply to every endpoint.

Base URLs

Product	Base URL
Payments	https://api.rach.finance/api/v1/
CaaS	https://api.rach.finance/caas/api/v1/

Headers

X-API-Key: <your key>            # every service endpoint
Content-Type: application/json   # on any request with a body

Always send Content-Type: application/json when you include a body, and read/write JSON.

Idempotency

Value-moving endpoints accept an idempotency key so a retry never double-executes. On CaaS transfers and withdrawals, pass idempotency_key in the body:

{
  "idempotency_key": "a-unique-id-you-generate",
  "sender_phone": "[phone]",
  "recipient_phone": "[phone]",
  "quote_id": "qt_...",
  "local_fiat_amount": "5000",
  "target_token": "USDC"
}

On Payments, send a stable reference on create operations (e.g. checkout) and reconcile against it. Reusing the same reference lets you safely retry.

Amounts

• Payments checkout amounts are decimal numbers in the stated currency.
• WaaS transfers take amount as a string plus a unit: "decimal" (whole coins, the default) or "base" (smallest unit, e.g. wei/satoshi).
• CaaS amounts are decimal strings; stablecoin vs fiat fields are named explicitly (stablecoin_amount, local_fiat_amount).

Always send money amounts as strings where the API asks for a string, to avoid floating-point rounding.

Pagination

List endpoints accept page and limit query parameters:

curl "https://api.rach.finance/api/v1/checkout/list?page=1&limit=25" \
  -H "X-API-Key: $RACH_KEY"

Timeouts & retries

Retry 429 and 5xx with exponential backoff and jitter. Never retry a non-idempotent write without an idempotency_key or a stable reference. See Errors.