API Docs

REST. JSON in, JSON out. Auth via wallet cookie or X-API-Key header.

1. Access tiers

Tier	Asset	Window	LLM	Rate
anonymous	BTC, ETH	1h, 4h	5 LLM/min	10/min/IP
wallet	all (13)	all (5m–1d)	enabled	60/min/wallet
api_key	per-key allowlist	all	enabled	per-key

2. Authentication

Three options, resolved by the server in this order:

X-API-Key header → api_key tier
wallet_session cookie (signed) → wallet tier
none → anonymous tier

3. POST /api/predict

The core endpoint. Minimum input: asset. Everything else has defaults.

curl -X POST https://foxsight.xyz/api/predict \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: <your-key>' \
  -d '{"asset":"BTC","window":"15m","persona":"chartist","use_llm":true}'

Optional fields: higher_tf (default ["1h","4h"]), limit (default 100), apply_guard (default true).

4. GET /api/me

Identity of the caller. Used by the frontend to render the tier badge.

{ "tier": "wallet", "address": "0xabc…123", "rate_limit_per_min": 60 }

5. GET /api/options

List of assets, windows, and personas allowed for the current tier.

{ "assets":["BTC","ETH",…], "windows":["5m","15m",…], "personas":["chartist",…], "llm_allowed": true }

6. Wallet flow (SIWE-lite)

GET /api/wallet/nonce?address=0x… → server returns the message to sign.
User signs the message with their wallet (no gas).
POST /api/wallet/verify body { address, signature } → server recovers the signer and sets an HttpOnly cookie.
POST /api/wallet/disconnect → cookie cleared.

7. Response schema

{
  "asset": "BTC", "symbol": "BTCUSDT", "window": "15m",
  "persona": "chartist", "used_llm": true,
  "regime": "trending_up | trending_down | ranging",
  "direction": "UP | DOWN | FLAT",
  "probability_up": 0.58,
  "confidence": "low | medium | high",
  "key_signals": ["RSI 57.2 (neutral)", "EMA9 > EMA21 > EMA50", …],
  "reasoning": "free-form text from the LLM",
  "indicators": { "rsi14":…, "ema9":…, "macd_hist":…, "atr14":…, "bb_pct_b":… },
  "higher_timeframes": { "1h": {"regime":"trending_up", "pct_change_20_candles": 1.42}, … },
  "guard_applied": false
}

8. Errors

401 — session expired or cookie missing
403 — asset / window not allowed for this tier
429 — rate limit hit; the body includes retry in Ns
502 — every exchange failed to return klines

Interactive Swagger is also available at /docs.