REST API overview
The base URL is operator-configured for this milestone — there is no fixed
public production origin (PORT/host are set by whoever runs the
service). Every request and response body is JSON.
Credentials
Two independent, header-only schemes (see Authentication / API keys for the full flow):
Authorization: ApiKey <key>— required for every data-plane endpoint (rates, convert, assets).Authorization: Session <token>— required for account/API-key/usage management endpoints.
Request id
Every response echoes X-Request-Id. Include it when reporting an issue —
it also appears in every error body (below).
Errors
Every non-2xx response uses the same envelope:
{ "code": "unauthorized", "message": "A valid API key is required.", "request_id": "..." }code is the only machine-readable discriminator; message is a display
string and must never be pattern-matched by client code. See Errors
for the full reference table.
Endpoint reference
Data plane — Authorization: ApiKey <key>:
| Method | Path | Billable | Purpose |
|---|---|---|---|
GET | /v1/rates/{base}/{quote} | 1 unit | Current rate |
GET | /v1/rates/{base}?quote=… | 1 unit | Multiple quotes |
GET | /v1/convert | 1 unit | Convert an amount |
GET | /v1/assets[/fiat|/crypto] | free | Asset catalog |
Control plane — Authorization: Session <token>:
| Method | Path | Purpose |
|---|---|---|
GET | /v1/account/usage | Usage & quotas |
GET | /v1/account/usage/history | Usage history |
GET/POST/DELETE | /v1/account/api-keys[…] | API key management |
POST | /v1/account/api-keys/{id}/rotate | Rotate a key |
POST | /v1/account/api-keys/{id}/remove, /remove-revoked | Delete revoked keys |
POST | /v1/account/password | Change password |
GET/POST | /v1/account/2fa[…] | Two-factor authentication |
GET/DELETE | /v1/account/identities[…] | Linked sign-in providers |
GET/POST | /v1/account/billing, /payments, /invoices, /subscription/* | Plans & billing |
Unauthenticated or mixed:
| Method | Path | Purpose |
|---|---|---|
POST/GET | /v1/auth/* | register/login/logout/session/verify/reset |
POST | /v1/auth/login/mfa | Complete a second-factor login |
GET | /v1/pricing | Public price list |
GET/POST | /v1/auth/oauth/* | Federated sign-in |
Every data-plane capability is also available as a hosted MCP tool, using the same API key and the same quota.
Rate limits
Two limits apply: a per-billing-period request-unit quota and a per-second request rate. See Rate limits.