# StableLens — Complete API Documentation

> StableLens is a real-time stablecoin peg stability monitoring platform that tracks 180+ stablecoins across multiple blockchains. It provides stability scores, depeg event detection, price history, and multi-coin comparison through both a web dashboard and a REST API.

Key information:
- Base URL: https://stablelens.io/api/v1
- Authentication: Public endpoints require no key; protected endpoints use the `X-API-Key` header
- Rate Limits: 30 requests/min (public), 60 requests/min (API key, configurable per key)
- Response Format: JSON over HTTPS
- Data Coverage: 180+ stablecoins with minute-level price tracking
- Depeg Detection: Automatic severity classification (minor, moderate, major, critical)

## Authentication

StableLens uses two authentication tiers:

### Free (No Key Required)
Two endpoints are available without any authentication:
- `GET /api/v1/health` — Check API and database status
- `GET /api/v1/tokens/:symbol` — Look up a single stablecoin by symbol

### API Key Required
All other endpoints require an API key passed via the `X-API-Key` HTTP header:

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

Protected endpoints:
- `GET /api/v1/tokens` — List all tokens
- `GET /api/v1/tokens/:symbol/history` — Price history
- `GET /api/v1/events` — Depeg events list
- `GET /api/v1/events/:id` — Single depeg event detail
- `GET /api/v1/compare` — Multi-coin comparison
- `POST /api/v1/webhooks` — Register webhook

## Endpoints

### GET /api/v1/health

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

**Authentication:** None required

**Example request:**
```bash
curl https://stablelens.io/api/v1/health
```

**Example response:**
```json
{
  "status": "ok"
}
```

---

### GET /api/v1/tokens/:symbol

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

**Authentication:** None required

**Parameters:**
| Parameter | Type   | Required | Description              |
|-----------|--------|----------|--------------------------|
| :symbol   | string | Yes      | Token symbol, e.g. USDT  |

**Example request:**
```bash
curl https://stablelens.io/api/v1/tokens/USDT
```

**Example response:**
```json
{
  "status": "ok",
  "data": {
    "symbol": "USDT",
    "pegType": "usd",
    "pegTarget": 1.0,
    "stabilityScore": 98.5,
    "pegStreak": 120,
    "daysSinceDepeg": 45,
    "severity": "minor"
  }
}
```

---

### GET /api/v1/tokens

List all active stablecoins with their current stability metrics.

**Authentication:** API Key required (X-API-Key header)

**Example request:**
```bash
curl -H "X-API-Key: pw_your_key_here" \
     https://stablelens.io/api/v1/tokens
```

**Example 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/history

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

**Authentication:** API Key required (X-API-Key header)

**Parameters:**
| Parameter | Type   | Required | Description                         |
|-----------|--------|----------|-------------------------------------|
| :symbol   | string | Yes      | Token symbol                        |
| days      | number | No       | Days of history (default 30, max 30)|
| limit     | number | No       | Max results (default 500, max 500)  |

**Example request:**
```bash
curl -H "X-API-Key: pw_your_key_here" \
     "https://stablelens.io/api/v1/tokens/USDT/history?days=7"
```

**Example 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/events

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

**Authentication:** API Key required (X-API-Key header)

**Parameters:**
| Parameter | Type    | Required | Description                               |
|-----------|---------|----------|-------------------------------------------|
| symbol    | string  | No       | Filter by symbol                          |
| severity  | string  | No       | minor, moderate, major, critical          |
| resolved  | boolean | No       | Filter by resolution status               |
| limit     | number  | No       | Results per page (default 20, max 50)     |
| offset    | number  | No       | Pagination offset (max 500)               |
| sort      | string  | No       | asc or desc (default desc)                |

**Example request:**
```bash
curl -H "X-API-Key: pw_your_key_here" \
     "https://stablelens.io/api/v1/events?severity=major&limit=5"
```

**Example 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/:id

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

**Authentication:** API Key required (X-API-Key header)

**Parameters:**
| Parameter | Type   | Required | Description                |
|-----------|--------|----------|----------------------------|
| :id       | string | Yes      | Event ID (CUID format)     |

**Example request:**
```bash
curl -H "X-API-Key: pw_your_key_here" \
     https://stablelens.io/api/v1/events/cm1abc
```

**Example 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/compare

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

**Authentication:** API Key required (X-API-Key header)

**Parameters:**
| Parameter | Type   | Required | Description                                     |
|-----------|--------|----------|-------------------------------------------------|
| symbols   | string | Yes      | Comma-separated, max 5 (e.g. USDT,USDC,DAI)    |

**Example request:**
```bash
curl -H "X-API-Key: pw_your_key_here" \
     "https://stablelens.io/api/v1/compare?symbols=USDT,USDC,DAI"
```

**Example 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/webhooks

Register a webhook to receive depeg alerts. HTTPS URLs only. Max 10 per API key.

**Authentication:** API Key required (X-API-Key header)

**Parameters:**
| Parameter  | Type     | Required | Description                       |
|------------|----------|----------|-----------------------------------|
| url        | string   | Yes      | HTTPS webhook URL                 |
| symbols    | string[] | No       | Filter by symbols (default: all)  |
| severities | string[] | No       | Filter by severity levels         |

**Example request:**
```bash
curl -X POST \
     -H "X-API-Key: pw_your_key_here" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://example.com/hook","symbols":["USDT","USDC"]}' \
     https://stablelens.io/api/v1/webhooks
```

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

## Error Handling

All error responses include a JSON body with a `status` field set to `"error"` and a `message` describing the issue.

### HTTP 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                 |

### Common Error Response Format
```json
{
  "status": "error",
  "message": "Invalid API key"
}
```

### Troubleshooting

- **401 Unauthorized**: Verify your API key is correct and passed in the `X-API-Key` header
- **429 Too Many Requests**: Wait and retry. The response includes `Retry-After` header
- **404 Not Found**: Check the token symbol is valid (e.g. USDT, not Tether)
- **503 Service Unavailable**: The database is temporarily unreachable; retry after a short delay

## Rate Limits

### Public (No Key)
- 30 requests per minute per IP address
- Exceeding this limit returns HTTP 429 with retry information

### API Key
- Configurable per key (default: 60 requests per minute)
- Usage is tracked per API key

### Data Export Limits
To protect data integrity, all endpoints enforce strict limits:
- **Price History**: Maximum 30 days, 500 snapshots per request
- **Depeg Events**: Maximum 90 days, 50 results per page, offset capped at 500
- **Compare**: Maximum 5 symbols per request, 30-day price window

## Integrations

StableLens integrates with:
- **Webhook Alerts**: Receive real-time depeg notifications via HTTPS webhooks
- **REST API**: Full programmatic access to all stablecoin data
- **Web Dashboard**: Interactive charts and comparison tools at https://stablelens.io
- **Telegram**: Daily pulse reports via @StableLensBot (coming soon)

## Examples

### Quick Start: Check USDT Stability
```bash
# No API key needed
curl https://stablelens.io/api/v1/tokens/USDT
```

### Compare Multiple Stablecoins
```bash
curl -H "X-API-Key: pw_your_key_here" \
     "https://stablelens.io/api/v1/compare?symbols=USDT,USDC,DAI"
```

### Get Recent Depeg Events
```bash
curl -H "X-API-Key: pw_your_key_here" \
     "https://stablelens.io/api/v1/events?severity=major&limit=10"
```

### Register a Webhook for Critical Alerts
```bash
curl -X POST \
     -H "X-API-Key: pw_your_key_here" \
     -H "Content-Type: application/json" \
     -d '{"url":"https://your-server.com/depeg-alert","severities":["critical","major"]}' \
     https://stablelens.io/api/v1/webhooks
```

### Python Example
```python
import requests

# Public endpoint — no key needed
response = requests.get("https://stablelens.io/api/v1/tokens/USDT")
data = response.json()
print(f"USDT stability score: {data['data']['stabilityScore']}")

# Protected endpoint — API key required
headers = {"X-API-Key": "pw_your_key_here"}
response = requests.get(
    "https://stablelens.io/api/v1/events",
    headers=headers,
    params={"severity": "critical", "limit": 5}
)
events = response.json()
for event in events["data"]:
    print(f"{event['symbol']}: {event['severity']} depeg on {event['startDate']}")
```

### JavaScript/Node.js Example
```javascript
// Public endpoint — no key needed
const res = await fetch("https://stablelens.io/api/v1/tokens/USDC");
const { data } = await res.json();
console.log(`USDC stability: ${data.stabilityScore}`);

// Protected endpoint — API key required
const eventsRes = await fetch("https://stablelens.io/api/v1/events?limit=5", {
  headers: { "X-API-Key": "pw_your_key_here" }
});
const events = await eventsRes.json();
events.data.forEach(e => console.log(`${e.symbol}: ${e.severity}`));
```