Skip to main content
The REST API is the default integration path. Public, no auth, soft per-IP rate limit (~300 req/min in production; repo default is 60/min). Every dashboard, embed widget, and the Telegram bot read through it. Base URL: https://api.pegana.xyz

​
Endpoints at a glance

The full schema lives in the API Reference.

​
Read one asset’s state

This is the single most-used endpoint. It returns the current peg state with the two underlying values. Use it for dashboards, pre-flight checks, automation gates.

​
List all assets

Returns an array of AssetCard objects with optional series_24h (hourly avg discount). Filter by class or peg query params. class is a case-sensitive exact match — valid values are lst, stable_fiat, stable_dn, stable_cdp, stable_yield, stable_fx, and synth_lev. An unknown value (e.g. stablecoin) returns an empty array with HTTP 200.

​
Asset history

  • bucket=raw — discount snapshots as recorded by the engine
  • bucket=1m — 1-minute aggregate (use for charts; smaller payload)
  • from, to — ISO 8601 timestamps; default last 24h
  • limit — clamped 1–5000, default 500

​
Pagination

We do not paginate /v1/assets (a few dozen rows). For /v1/alerts and /history, use the since / from + limit parameters and walk forward by adjusting the lower bound.

​
Errors

We return standard HTTP status codes: Error bodies are {"error": "...", "message": "..."} (plus an optional asset) — short, machine-readable. Branch on error, never on message.

​
CORS

https://pegana.xyz, https://www.pegana.xyz, and http://localhost:3000 are allowed by default. Add more origins via the CORS_EXTRA_ORIGINS env var on self-hosted instances.

​
Rate limit

Soft per-IP sliding-window: ~300 req/min in production (the repo default is 60 req/min — the production host raises it). The limit resets on a 60-second sliding window. /v1/audit.csv is stricter at 10 req/min. /healthz and /readyz are exempt. The 429 response includes a Retry-After: 60 header (the sliding-window upper bound) so clients know when to retry, but the API does not emit X-RateLimit-* headers — your remaining budget is not client-discoverable, so handle 429 defensively and back off. If you hit 429, slow down or contact raffxweb3@gmail.com for a higher limit.

​
What about authenticated routes?

The /v1/me/*, /v1/auth/*, and webhook management endpoints require a JWT — see authentication. These are user-scoped routes (your subscriptions, your delivery history, your webhook configuration).

​
Next

WebSocket stream

Sub-second push for state changes — better than polling.

API Reference

Full OpenAPI spec with try-it-now.