WatchCrypto API Docs

REST and WebSocket APIs for market data and alerts. Backend is built on Axum (Rust).

Base URL/api/v1

WebSocket/ws

AuthAlerts and notifications endpoints require Authorization: Bearer <token>, the access token a sign-in returns.

REST API

GET /api/v1/exchanges

List supported exchanges and their current connection status.

GET /api/v1/exchange-status

Per-stream connection status for each exchange.

{
  "exchange": "binance",
  "status": "Connected",
  "streams": [
    {
      "stream": "trades",
      "status": "Connected",
      "last_connected": 1700000000000,
      "last_disconnected": 1699990000000,
      "reconnects": 2
    }
  ]
}

GET /api/v1/klines

Fetch historical candlesticks.

Query params:
- exchange (default: binance)
- symbol (default: BTC/USDT)
- interval (default: 1m)
- limit (default: 1000, max: 2000)
- endTime (optional, ms since epoch)

GET /api/v1/depth

Order book snapshot (top levels).

Query params:
- exchange (default: binance)
- symbol (default: BTC/USDT)

GET /api/v1/trades

Recent trades for a symbol.

Query params:
- exchange (default: binance)
- symbol (default: BTC/USDT)
- limit (default: 1000, max: 2000)

GET /api/v1/tickers

Watchlist tickers (price, 24h change, high/low, volume).

WebSocket API

Send JSON messages with op and channel to subscribe or unsubscribe.

{
  "op": "subscribe",
  "channel": "klines",
  "exchange": "binance",
  "symbol": "BTC/USDT",
  "interval": "1m"
}

{
  "op": "subscribe",
  "channel": "ticker",
  "exchange": "*",
  "symbol": "*"
}

Supported channels: klines, depth, trades, ticker. Ticker supports wildcard subscription with *.

If the server drops messages, it can send {"type":"resync","missed":N}.

Rate limits

Public market-data endpoints allow 100 requests per 10 seconds per IP; over that you get 429. Pace scripted probing (~0.4 s apart) rather than firing in parallel. Batch endpoints count each requested pair against the budget.

Sign-in, sign-up, password-reset and wallet-nonce endpoints carry their own, tighter budgets and answer 429 with an error field when exceeded.

Alerts API

Server-side price alerts delivered by Web Push. All alert endpoints require a signed-in session: send Authorization: Bearer <token>.

GET /api/v1/alerts

List the alerts on your account. Each carries reach, how it would reach you if it fired now (push, email, or none: only a page open when it fires can show it), and delivered_at, when its last firing reached you (null if it reached no one, or has not fired).

POST /api/v1/alerts

Create an alert. condition is one of above, below, volume_above, volume_below, rsi_above, rsi_below; target_price is the threshold for that condition (a price, a 24h volume, or an RSI level). The answer carries reach, as in the list.

{
  "symbol": "BTC/USDT",
  "exchange": "binance",
  "condition": "above",
  "target_price": 100000
}

PATCH /api/v1/alerts/:id

Update an alert (partial).

{
  "enabled": true,
  "condition": "below",
  "target_price": 90000
}

DELETE /api/v1/alerts/:id

Delete an alert.

POST /api/v1/alerts/:id/rearm

Re-arm a triggered alert so it can fire again.

POST /api/v1/alerts/:id/ack

Acknowledge a triggered alert (clears it from the triggered list without re-arming).

POST /api/v1/alerts/:id/shown

Record that a page open in front of you showed this alert as it fired. It counts as reaching you only within five minutes of the firing and only if nothing else reached you; the answer's recorded says whether it did.

Push notifications

Alerts are delivered as Web Push notifications to browsers that have subscribed. The terminal and the alerts page handle this for you; the endpoints are documented for completeness.

GET /api/v1/push/vapid-public-key

The VAPID public key to pass as applicationServerKey when subscribing. Public.

POST /api/v1/push/subscriptions

{
  "endpoint": "https://…",
  "p256dh": "…",
  "auth": "…",
  "channel": "webpush",
  "platform": "web"
}

DELETE /api/v1/push/subscriptions

Remove a subscription by endpoint (signed in).

POST /api/v1/push/test

Send a test notification to your subscribed browsers (signed in).