API Reference

Access real-time stablecoin peg stability data. Get stability scores, depeg event history, price snapshots, and multi-coin comparisons for 180+ stablecoins.

Base URL

stablelens.io/api/v1

Format

JSON over HTTPS

Rate Limit

30 req/min (public)

bash

# Quick start — no API key needed
curl https://stablelens.io/api/v1/tokens/USDT

Authentication

Free (No Key)

Two endpoints available without authentication:

GET /api/v1/health
GET /api/v1/tokens/:symbol

API Key Required

Pass your key via the X-API-Key header:

/tokens · /tokens/:symbol/history
/events · /events/:id
/compare · /webhooks

bash

curl -H "X-API-Key: pw_your_key_here" \
     https://stablelens.io/api/v1/tokens

Endpoints

Free Tier

GET/api/v1/healthPublic

Check API and database status. Returns 503 if the database is unreachable.

No parameters

Response

json

{
  "status": "ok"
}

GET/api/v1/tokens/:symbolPublic

Look up a single stablecoin by symbol. Returns current price, stability score, peg streak, and depeg history.

Parameters

:symbolstringreqToken symbol, e.g. USDT

Response

json

{
  "status": "ok",
  "data": {
    "symbol": "USDT",
    "pegType": "usd",
    "pegTarget": 1,
    "stabilityScore": 98.5,
    "pegStreak": 120,
    "daysSinceDepeg": 45,
    "severity": "minor"
  }
}

API Key Required

GET/api/v1/tokensAPI Key

List all active stablecoins with their current stability metrics.

No parameters

Response

json

{
  "status": "ok",
  "count": 189,
  "data": [
    {
      "symbol": "USDT",
      "pegType": "usd",
      "stabilityScore": 98.5,
      "pegStreak": 120
    },
    {
      "symbol": "USDC",
      "pegType": "usd",
      "stabilityScore": 99.2,
      "pegStreak": 120
    }
  ]
}

GET/api/v1/tokens/:symbol/historyAPI Key

Historical price snapshots for charting. Capped at 30 days, 500 data points.

Parameters

:symbolstringreqToken symbol

daysnumberDays of history (default 30, max 30)

limitnumberMax results (default 500, max 500)

Response

json

{
  "status": "ok",
  "symbol": "USDT",
  "days": 30,
  "count": 120,
  "data": [
    {
      "timestamp": "2026-02-15T00:00:00Z",
      "price": 0.9998,
      "marketCap": 142000000000,
      "volume24h": 89000000000
    }
  ]
}

GET/api/v1/eventsAPI Key

Depeg events from the last 90 days with filtering and pagination.

Parameters

symbolstringFilter by symbol

severitystringminor, moderate, major, critical

resolvedbooleanFilter by resolution status

limitnumberResults per page (default 20, max 50)

offsetnumberPagination offset (max 500)

sortstringasc or desc (default desc)

Response

json

{
  "status": "ok",
  "count": 3,
  "total": 12,
  "data": [
    {
      "id": "cm1abc...",
      "symbol": "USDT",
      "severity": "minor",
      "startDate": "2026-01-15T08:00:00Z",
      "resolved": true,
      "durationHours": 6
    }
  ]
}

GET/api/v1/events/:idAPI Key

Full details for a single depeg event including coin metadata and sources.

Parameters

:idstringreqEvent ID (CUID format)

Response

json

{
  "status": "ok",
  "data": {
    "id": "cm1abc...",
    "symbol": "USDT",
    "severity": "minor",
    "startDate": "2026-01-15T08:00:00Z",
    "endDate": "2026-01-15T14:00:00Z",
    "lowestPrice": 0.997,
    "resolved": true,
    "durationHours": 6
  }
}

GET/api/v1/compareAPI Key

Multi-coin comparison with stability scores, statistical metrics, and 30-day price history.

Parameters

symbolsstringreqComma-separated, max 5 (e.g. USDT,USDC,DAI)

Response

json

{
  "status": "ok",
  "count": 2,
  "data": [
    {
      "symbol": "USDT",
      "stabilityScore": 98.5,
      "stats": {
        "avgPrice": 1.0001,
        "stdDeviation": 0.00023,
        "depegEventCount": 3
      },
      "priceHistory": [
        {
          "timestamp": "2026-02-22T00:00:00Z",
          "price": 0.9999
        }
      ]
    }
  ]
}

POST/api/v1/webhooksAPI Key

Parameters

urlstringreqHTTPS webhook URL

symbolsstring[]Filter by symbols (default: all)

severitiesstring[]Filter by severity levels

Response

json

{
  "status": "ok",
  "message": "Webhook registered",
  "data": {
    "id": "cm1xyz...",
    "url": "https://example.com/hook",
    "isActive": true
  }
}

Status Codes

Code	Meaning
200	OK — Successful request
201	Created — Webhook registered successfully
400	Bad Request — Invalid parameters or missing required fields
401	Unauthorized — Missing or invalid API key
404	Not Found — Token or event not found
405	Method Not Allowed — Use the correct HTTP method
409	Conflict — Webhook URL already registered
429	Too Many Requests — Rate limit exceeded
503	Service Unavailable — Database unreachable

Error Responses

All error responses follow a consistent JSON structure. Use the status field to check for errors programmatically.

429Rate Limit Exceeded

json

{
  "status": "error",
  "error": "Rate limit exceeded. Please wait before making more requests.",
  "retryAfter": 32
}

401Missing or Invalid API Key

json

{
  "status": "error",
  "error": "Invalid or missing API key. Pass your key via the X-API-Key header."
}

404Resource Not Found

json

{
  "status": "error",
  "error": "Token not found: FAKEUSD"
}

400Bad Request

json

{
  "status": "error",
  "error": "Missing required parameter: symbols"
}

Rate Limits

Public (No Key)

• 30 requests per minute per IP
• Exceeded → 429 with retry info

API Key

• Configurable per key
• Default: 60 requests per minute
• Usage tracked per key

Data Export Limits

To protect the integrity of our data, all endpoints enforce strict limits:

Price History

30 days, 500 snapshots

Depeg Events

90 days, 50/page, offset ≤ 500

Compare

5 symbols, 30-day price window

Questions? Contact support<@>stablelens<.>io