# SRUS Lifetime Signal API (v1)

Read-only access to normalized fleet trading signals for **Lifetime** members.

**Fair use, not unlimited.** Lifetime includes personal API access under rate limits (default 60 req/min per key, max 3 active keys). Not for redistribution or commercial products without a separate plan. Higher limits and paid tiers come as we scale.

This is a living API — more endpoints (history, streaming) may land later. v1 is one REST endpoint plus personal API keys.

---

## Get an API key

1. Unlock the dashboard with a **Lifetime** (or admin) pass.
2. Open **Creator Lab** in the left sidebar.
3. Scroll to **Signal API Keys**.
4. Click **Generate key**, copy the plaintext key immediately.
5. Store it somewhere safe — SRUS only keeps a hash. We cannot show the full key again.

Revoke a leaked key from the same panel anytime.

---

## Auth

Send the key in the `Authorization` header (never as a query param):

```http
Authorization: Bearer srus_live_YOUR_KEY_HERE
```

| Status | Meaning |
|--------|---------|
| `401` | Missing / invalid / revoked key |
| `403` | Key valid but membership is not lifetime (or wrong scope) |
| `429` | Rate limited — see `Retry-After` header |

---

## Endpoint

### `GET /api/v1/signals/live`

Most recent fleet signals, newest first, in a normalized shape.

**Query params**

| Param | Default | Notes |
|-------|---------|--------|
| `limit` | `50` | Max `200` |
| `offset` | `0` | Simple pagination |
| `symbol` | — | e.g. `BTCUSDT` |
| `bot` | — | e.g. `SniperBot`, `PaxGBot`, `WaveSniper` |

**Example**

```bash
curl -sS "https://YOUR_HOST/api/v1/signals/live?limit=20&symbol=BTCUSDT" \
  -H "Authorization: Bearer srus_live_YOUR_KEY_HERE"
```

**Example response**

```json
{
  "ok": true,
  "count": 1,
  "total_matched": 1,
  "limit": 20,
  "offset": 0,
  "next_offset": null,
  "signals": [
    {
      "id": "a1b2c3d4e5f67890",
      "symbol": "BTCUSDT",
      "direction": "long",
      "entry_price": 67450.5,
      "take_profit": 68200.0,
      "stop_loss": 66900.0,
      "confidence_score": 0.82,
      "source_bot": "SniperBot",
      "timestamp": "2026-07-19T06:00:00+00:00",
      "reasons": "GPS + S/R confluence"
    }
  ]
}
```

`source_bot` is always a fleet label (`SniperBot`, `PaxGBot`, …). Responses never name the underlying market-data pipeline.

---

## Rate limit & fair use

Lifetime includes Signal API access under **fair-use caps**. This is **not** an unlimited or commercial feed.

| Cap | Default |
|-----|---------|
| Requests | **60 / minute / key** |
| Active keys | **3 per Lifetime member** |
| Scope | `signals:read` only |
| Intended use | Personal alerts, journals, private bots, your own tooling |

- On breach: HTTP `429` + `Retry-After` (seconds)
- Server env: `SRUS_API_RATE_LIMIT`, `SRUS_API_MAX_KEYS`
- **Not allowed without a separate plan:** redistribution, resale, multi-tenant products, or running a public signal service on top of this API

Higher limits and paid Builder / Pro tiers will be offered as we scale. We’ll publish changes in this doc and in the API Keys panel first.

---

## Scope

Keys are issued with scope `signals:read` only.

This key is **read-only signal data**. It will never grant trade execution or account actions.

---

## What’s next

Planned (not in v1): `/api/v1/signals/history`, WebSocket live stream, paid higher-limit tiers. Schema and Bearer auth will stay compatible.