API route reference

This page lists every endpoint in the CashXChain API. Routes are grouped by the authentication tier they belong to.

Base URL: https://api.sandbox.cashxchain.com (sandbox) / https://api.cashxchain.com (production)

---

Auth tiers

Tier	Accepts	Rejects
Public	No credential required	—
Unified	JWT (any aud), sk_, pk_ (read-only), rk_ (scoped), mk_	—
Elevated	JWT (aud=internal or aud=admin), mk_	sk_, pk_, rk_ → 401
HMAC	HMAC-SHA-256 (AUTH_PORTAL_WEBHOOK_SECRET)	Everything else
Bearer secret	AUTH_PORTAL_REPLAY_SECRET or JWT	—

---

Public routes (no authentication)

Method	Path	Description
GET	/	Service info and version
GET	/health	Liveness probe
GET	/ready	Readiness probe (database connectivity)
POST	/webhooks/{partner}/{env}	Receive partner webhook events (HMAC-verified internally)
POST	/v1/fx/quotes	Stateless FX quote — no auth, no persistence

---

Unified auth — Developer API

These routes accept any valid credential (JWT, sk_, pk_, rk_, or mk_). Publishable keys are limited to read-only methods. Restricted keys are gated by the scope column.

Accounts

Method	Path	Write	Scope (RK)	Description
POST	/v1/accounts	✅	—	Create account. Requires api_tier=platform_ready JWT when ?acting_as= is set.
POST	/v1/customers	✅	—	Create customer (legacy alias). Idempotent on email.

Transfers

Method	Path	Write	Scope (RK)	Description
POST	/v1/transfers	✅	transfers:write	Create internal (email-to-email) or external (bank) transfer. Requires Idempotency-Key header.
GET	/v1/transfers	—	transfers:read	List transfers for the caller's account.
GET	/v1/transfers/{id}	—	transfers:read	Retrieve a single transfer by UUID.

Payments (low-level)

Method	Path	Write	Scope (RK)	Description
POST	/v1/payments/add-funds	✅	payments:write	Add funds to a customer wallet via a partner. Requires Idempotency-Key header.
POST	/v1/payments/send	✅	payments:write	Send a claimless payment to an external payee via a partner. Requires Idempotency-Key header.
GET	/v1/payments	—	payments:read	List payments. Filter by customer_id, status, limit.
GET	/v1/payments/{id}	—	payments:read	Retrieve a single payment by UUID.

FX

Method	Path	Write	Scope (RK)	Description
POST	/v1/fx/quotes	—	—	Public. Stateless, non-persisted FX quote.
POST	/v1/fx/quote	✅	fx:read	Persisted FX quote with 30-second TTL. Returns quote_id for execute step. Sandbox only.
POST	/v1/fx/execute	✅	payments:write	Execute a persisted FX quote. Atomic DB transaction — debit/credit + transfers row. Sandbox only.

Transactions

Method	Path	Write	Scope (RK)	Description
GET	/v1/transactions	—	transactions:read	List transactions for the caller's account.
GET	/v1/transactions/{id}	—	transactions:read	Retrieve a single transaction by UUID.

Contacts

Method	Path	Write	Scope (RK)	Description
GET	/v1/contacts	—	contacts:read	List payment beneficiaries / contacts.

API keys

Method	Path	Write	Scope (RK)	Description
POST	/v1/api-keys	✅	api_keys:write	Create a new API key. Full token returned once only.
GET	/v1/api-keys	—	api_keys:read	List all API keys for the account. No tokens returned.
DELETE	/v1/api-keys/{id}	✅	api_keys:write	Revoke an API key. Returns 204.

Request logs

Method	Path	Write	Scope (RK)	Description
GET	/v1/request-logs	—	request_logs:read	List request logs. Supports limit, before (cursor).
GET	/v1/request-logs/{id}	—	request_logs:read	Retrieve a single request log with full request/response bodies.

Usage analytics

Method	Path	Write	Scope (RK)	Description
GET	/v1/usage/summary	—	usage:read	Summary stats: request count, error rate, volume, avg settlement.
GET	/v1/usage/timeseries	—	usage:read	Time-series data. Query param `?window=7d

Utility

Method	Path	Write	Scope (RK)	Description
GET	/v1/utility/validate-address	—	—	Validate a blockchain address. Params: address, chain, asset (optional). Solana: checks ATA existence.

Identity

Method	Path	Write	Scope (RK)	Description
GET	/v1/me	—	—	Returns the caller's identity and account info from the auth token.

---

Elevated auth — Dashboard / Platform

These routes require JWT with aud=internal or aud=admin, or a master key (mk_). Regular API keys (sk_, pk_, rk_) are rejected with 401 before any database lookup — they cannot access these routes under any circumstance.

Accounts (dashboard)

Method	Path	Description
GET	/v1/accounts	List accounts. Filter by tenant_id, managed_by, limit, offset.
GET	/v1/accounts/{id}	Retrieve a single account by UUID.
GET	/v1/accounts/me	Caller's own account. Elevated context.
GET	/v1/accounts/me/balance	Caller's balance breakdown by currency.
GET	/v1/accounts/me/vibans	Caller's virtual IBANs.
GET	/v1/accounts/{id}/statements	Account statement.

Customers (dashboard)

Method	Path	Description
GET	/v1/customers	List customers for the caller's account.
GET	/v1/customers/{id}	Retrieve a single customer.
POST	/v1/customers/{id}/partner-link	Enroll a customer with a payment partner.
GET	/v1/customers/{id}/partner-link	List all partner links for a customer.
GET	/v1/customers/{id}/partner-link/{partner}	Retrieve a specific partner link.

vIBANs (dashboard)

Method	Path	Description
POST	/v1/customers/{id}/vibans	Create a vIBAN for a customer. Requires Idempotency-Key.
GET	/v1/customers/{id}/vibans	List vIBANs for a customer.
GET	/v1/customers/{id}/vibans/{viban_id}	Retrieve a vIBAN.
GET	/v1/customers/{id}/vibans/{viban_id}/balance	vIBAN balance.
GET	/v1/customers/{id}/vibans/{viban_id}/transactions	vIBAN transaction history.
GET	/v1/customers/{id}/wallet	Customer's crypto wallet info.

Platform permissions (dashboard)

Method	Path	Description
DELETE	/v1/platform-permissions/{id}	Revoke a platform permission (managed account link).

Notifications (dashboard)

Method	Path	Description
GET	/v1/notifications	Server-sent events stream. JWT via ?access_token= for EventSource clients.

Crypto addresses (dashboard)

Method	Path	Description
GET	/v1/crypto-addresses/me	Caller's on-chain addresses.

---

Internal — HMAC service-to-service

Not accessible from developer or platform API keys. Authenticated via HMAC-SHA-256 (AUTH_PORTAL_WEBHOOK_SECRET).

Method	Path	Events
POST	/internal/webhooks/auth	user.created, user.kyc.approved, user.kyc_status_changed, user.updated

---

Sandbox-only routes

These routes are only available when APP_ENV=sandbox. They do not exist in production.

Faucet

Method	Path	Auth	Description
POST	/v1/sandbox/faucet	JWT	Credit sandbox balances for testing.

Admin

Method	Path	Auth	Description
POST	/v1/sandbox/admin/wipe	Bearer secret (AUTH_PORTAL_REPLAY_SECRET)	Reset all sandbox data.
POST	/v1/sandbox/admin/replay	Bearer secret	Replay a set of seed events.
POST	/v1/sandbox/admin/reprovision/{account_id}	JWT	Re-run provisioning for an account.
GET	/v1/sandbox/admin/whoami	JWT	Debug identity endpoint.

---

API documentation (sandbox only)

Method	Path	Description
GET	/v1/openapi.json	OpenAPI 3.0 spec (sandbox only — not exposed in production)
GET	/v1/docs	Swagger UI (sandbox only)

---

Common request headers

Header	Required	Description
Authorization	Yes (protected routes)	Bearer <token>
Content-Type	Yes (POST/PUT/PATCH)	application/json
Idempotency-Key	Yes (all write routes)	Unique key per distinct request. Repeating the same key returns the cached response.
X-Request-ID	Optional	Client-supplied request correlation ID. Echoed back in X-CXC-Request-ID.