API Documentation — Stablecoin Atlas

Base URL: https://api.stablecoinlens.liveVersion: v1Format: JSONTLS only

Overview

The Stablecoin Atlas API is organized around predictable, resource-oriented URLs and uses standard HTTP verbs and status codes. All requests must be made over HTTPS — calls over plain HTTP are rejected.

All timestamps are ISO-8601 in UTC.
All monetary fees are expressed in basis points (`bps`).
Resource ids are lowercase, hyphen-separated, and stable across versions.
Unknown fields are ignored — safe for forward compatibility.

Authentication

Authenticate every request with a bearer token in the Authorization header. Keys are environment-scoped: sk_test_… for sandbox and sk_live_… for production.

Request enterprise access via the API & Data Feeds page.
You'll receive a sandbox key (sk_test_…) within 1 business day. Test against https://api.stablecoinlens.live using sandbox data.
Once your integration is reviewed, you'll be issued a production key (sk_live_…) and a signing secret for webhooks.
Store keys as environment variables — never commit them to source control or ship them in client-side code.

Example: authenticated request

curl https://api.stablecoinlens.live/v1/models \
  -H "Authorization: Bearer sk_live_abc123…" \
  -H "Accept: application/json"

Rotating a key

# Issue a new key (old key remains valid for 24h grace period)
curl -X POST https://api.stablecoinlens.live/v1/keys/rotate \
  -H "Authorization: Bearer sk_live_abc123…"

Requests & responses

Successful responses return 2xx with a JSON body. Every response includes an X-Request-Id header — quote it when contacting support.

Successful response envelope

{
  "data": { /* resource or array of resources */ },
  "meta": {
    "request_id": "req_01HXYZ…",
    "api_version": "2026-05-01"
  }
}

Pagination

List endpoints use cursor-based pagination. Pass limit (1–100, default 25) and follow the next_cursor returned in meta to fetch subsequent pages. When next_cursor is null, you've reached the end.

First page

GET https://api.stablecoinlens.live/v1/models?limit=25
Authorization: Bearer sk_live_…

200 OK
{
  "data": [ /* 25 models */ ],
  "meta": {
    "request_id": "req_01HXYZ…",
    "limit": 25,
    "next_cursor": "eyJpZCI6InVzZGMifQ",
    "has_more": true
  }
}

GET https://api.stablecoinlens.live/v1/models?limit=25&cursor=eyJpZCI6InVzZGMifQ

Iterating in JavaScript

async function* listAllModels(apiKey) {
  let cursor = null;
  do {
    const url = new URL("https://api.stablecoinlens.live/v1/models");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    if (!res.ok) throw new Error(`API error: ${res.status}`);

    const { data, meta } = await res.json();
    for (const model of data) yield model;
    cursor = meta.next_cursor;
  } while (cursor);
}

Filtering & sorting

Most list endpoints accept query-parameter filters. Combine multiple filters with & — they are ANDed together. Repeat a parameter to OR values within the same field.

Examples

# Fiat-backed models on Ethereum, sorted by most recently updated
GET /v1/models?category=fiat-backed&chain=Ethereum&sort=-updated_at

# MiCA-EMT or NYDFS regulated
GET /v1/models?regime=EU-MiCA-EMT&regime=US-NYDFS

# Changes in the last 24 hours
GET /v1/changes?since=2026-05-29T00:00:00Z

Rate limits

Rate limits are enforced per API key. Every response includes these headers:

X-RateLimit-Limit — requests allowed in the window
X-RateLimit-Remaining — requests left in the window
X-RateLimit-Reset — UNIX timestamp when the window resets
Retry-After — seconds to wait (only on 429)

Plan	Requests / min	Burst
Sandbox	60	120
Analyst	600	1,200
Enterprise	6,000	12,000

Error codes

Errors use conventional HTTP status codes and a consistent JSON shape. Always inspect error.code programmatically rather than the human-readable message.

Error response

{
  "error": {
    "code": "validation_failed",
    "message": "limit must be between 1 and 100",
    "fields": [
      { "name": "limit", "reason": "out_of_range" }
    ],
    "request_id": "req_01HXYZ…",
    "docs_url": "https://stablecoinlens.live/api-docs#errors"
  }
}

Status	Code	Meaning	What to do
400	bad_request	Malformed query, missing required parameter, or invalid filter value.	Check the `error.fields` array and fix the offending parameter.
401	unauthorized	Missing, malformed, or revoked API key.	Send `Authorization: Bearer sk_live_…`. Rotate the key if it was leaked.
403	forbidden	Your plan does not include access to this endpoint or dataset.	Upgrade your plan or request access at /api-access.
404	not_found	The resource (e.g. model id) does not exist.	Verify the id against `GET /v1/models`.
409	conflict	The request conflicts with the current state (e.g. duplicate webhook).	Fetch the existing resource and reconcile.
422	validation_failed	Request was well-formed but failed semantic validation.	Inspect `error.fields[].reason` and adjust the payload.
429	rate_limited	You exceeded the rate limit for your plan.	Back off using the `Retry-After` header. Consider upgrading.
500	internal_error	Unexpected server-side failure. Always safe to retry idempotent GETs.	Retry with exponential backoff. Contact support with `request_id`.
503	service_unavailable	Temporary overload or scheduled maintenance.	Retry after the `Retry-After` window.

Recommended retry strategy

async function fetchWithRetry(url, init, attempt = 0) {
  const res = await fetch(url, init);
  if (res.status === 429 || res.status >= 500) {
    if (attempt >= 5) throw new Error("Max retries exceeded");
    const retryAfter =
      Number(res.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return fetchWithRetry(url, init, attempt + 1);
  }
  return res;
}

Endpoint reference

GET/v1/models

List all stablecoin models. Supports pagination, filtering, and sorting.

Parameter	Type	Description
category	string	Filter by category (fiat-backed, crypto-backed, algorithmic, rwa).
regime	string	Filter by regulatory regime code (e.g. EU-MiCA-EMT).
chain	string	Filter by supported chain (e.g. Ethereum).
limit	integer	Page size, 1–100. Default 25.
cursor	string	Opaque pagination cursor from previous response.
sort	string	Field to sort by, prefix `-` for descending. e.g. `-updated_at`.

GET/v1/models/{id}

Retrieve a single model by its stable id (e.g. `usdc`).

GET/v1/regimes

List regulatory regimes with jurisdiction, issuer mappings, and `updated_at` timestamps.

GET/v1/changes

Append-only change feed of model and regime updates. Ideal for compliance alerting.

Parameter	Type	Description
since	ISO-8601	Return changes after this timestamp.
type	string	Filter by `model.updated`, `regime.updated`, `model.created`.

POST/v1/webhooks

Webhooks

Subscribe to change events and receive signed POST callbacks. Verify the X-Atlas-Signature header using your webhook signing secret before processing the payload.

Verifying a webhook (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(req, secret) {
  const sig = req.headers["x-atlas-signature"];
  const expected = createHmac("sha256", secret)
    .update(req.rawBody)
    .digest("hex");
  return (
    sig &&
    timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
  );
}

OpenAPI spec

The API is fully described by an OpenAPI 3.1 document. Point any compatible generator (openapi-generator, oapi-codegen, openapi-typescript, Kiota, etc.) at the URL below to scaffold a client in your stack of choice.

Generate a client locally

# Inspect the spec
curl -O https://stablecoinlens.live/openapi.json

# Example: TypeScript types via openapi-typescript
npx openapi-typescript https://stablecoinlens.live/openapi.json -o atlas.d.ts

# Example: full client via openapi-generator
openapi-generator-cli generate \
  -i https://stablecoinlens.live/openapi.json \
  -g python \
  -o ./atlas-python

The spec is the source of truth — our reference SDKs below are regenerated from it on every release via npm run sdk:generate.

SDKs & examples

Reference clients are auto-generated from openapi.json and published alongside a signed manifest. The download buttons below always serve the latest build — no need to bookmark a version.

Loading latest SDK manifest…

Both clients handle bearer auth, cursor pagination, the Atlas-Version header, and automatic retry on 429 / 5xx with the Retry-After header. Verify the SHA-256 shown next to each download against the file you receive.

Versioning

The API is versioned by URL path (/v1) and by a dated api_version returned in every response. Breaking changes ship under a new path; additive changes are deployed continuously. Pin a date by sending an Atlas-Version header.

Pinning an API version

curl https://api.stablecoinlens.live/v1/models \
  -H "Authorization: Bearer sk_live_…" \
  -H "Atlas-Version: 2026-05-01"

Ready to integrate?

Request a sandbox key and we'll send credentials within 1 business day.

Request API access →