BLACK ROOM — API Documentation

Desktop API

Public API

WebSocket

Tiers & Limits

🔒 Authentication

All Desktop API endpoints require a per-user API key via header:

X-API-Key: brk_your_personal_api_key

Generate your key in the Telegram bot: /settings → API Key. Keys are hashed (SHA-256) — we never store the plain key.

Requests without a valid key receive 401 Unauthorized. Banned/deactivated accounts receive 403 Forbidden.

👤

Profile

GET/desktop/me ALL User profile, tier, features▶

Returns your profile, active subscription, and available features based on tier.

{
  "id": 42,
  "telegram_id": 123456789,
  "username": "trader_joe",
  "tier": "pro",
  "subscription": { "expires_at": "2026-05-01T00:00:00", "auto_renew": true },
  "features": {
    "signals_full_access": true,
    "alerts_limit": 20,
    "watchlist_limit": 30,
    "real_time_updates": true
  }
}

📡

System Status

GET/desktop/status ALL System health, exchanges, scheduler▶

Returns system health: database, Redis, scheduler status, exchange scores, last scan time, active WebSocket connections.

{
  "db_ok": true,
  "redis_ok": true,
  "scheduler_running": true,
  "scheduler_jobs": 12,
  "last_scan": "2026-04-03T12:30:00Z",
  "active_signals": 8,
  "exchanges": {
    "binance": { "score": 0.95, "success_rate": 0.99 },
    "bybit": { "score": 0.91, "success_rate": 0.97 }
  }
}

📈

Signals

GET/desktop/signals ALL Paginated signals list▶

Paginated signals. FREE users see limited details on PRO/ELITE signals. FREE users only see last 7 days of closed signals.

Query parameters

Param	Type		Description
`status`	string	opt	active, closed, all
`coin`	string	opt	Filter by coin (e.g. BTC)
`direction`	string	opt	long / short
`page`	int	opt	Page number (default 1)
`limit`	int	opt	1-100 (default 20)

GET/desktop/signals/active ALL Active signals only▶

Returns all currently active signals. Optimized for dashboard view — no pagination needed.

GET/desktop/signals/{id} ALL Signal detail + update history▶

Full signal with TP/SL levels, AI reasoning, PnL stats, and chronological update history. ELITE users also see factors breakdown (regime, ML gate, indicators, correlation data).

📊

Stats

GET/desktop/stats ALL Performance: win rate, PnL, user data▶

Global performance stats (total signals, win rate, average PnL, total PnL, 30-day count) plus user-specific data (alerts count, watchlist count).

{
  "global": {
    "total_signals": 580,
    "win_rate": 68.5,
    "average_pnl": 3.42,
    "total_pnl": 1540.50
  },
  "user": {
    "tier": "pro",
    "alerts_active": 5,
    "watchlist_size": 12
  }
}

💰

Market Data

GET/desktop/market ALL Top coins by volume with prices▶

Top coins ranked by 24h volume. Includes latest price, volume, 1h/24h/7d change, market cap, and logo.

Query parameters

Param	Type		Description
`limit`	int	opt	1-200 (default 50)

GET/desktop/market/{coin} ALL Coin detail: multi-exchange prices + history▶

Single coin with prices across all exchanges, price history chart data, and active signals for this coin.

Query parameters

Param	Type		Description
`hours`	int	opt	Price history window, 1-168h (default 24)

GET/desktop/candles/{coin} ALL OHLCV candle data for charting▶

Historical OHLCV candle data. Tier-gated: FREE (1h+4h, last 24h), PRO (all timeframes, 7 days), ELITE (full history).

Query parameters

Param	Type		Description
`exchange`	string	opt	e.g. binance, bybit
`timeframe`	string	opt	15m, 1h, 4h, 1d (default 1h)
`limit`	int	opt	1-1000 (default 200)
`from_ts`	ISO date	opt	Start date
`to_ts`	ISO date	opt	End date

{
  "coin": "BTC",
  "timeframe": "1h",
  "candles": [
    { "t": "2026-04-03T00:00:00", "o": 67500, "h": 68200, "l": 67100, "c": 67900, "v": 1250000 }
  ]
}

GET/desktop/candles/{coin}/exchanges ALL Available exchanges for a coin▶

Returns available exchanges and timeframes with data range for a specific coin.

🪙

Coins

GET/desktop/coins ALL Coin list with metadata & logos▶

Paginated coin list with logos, market cap, rank. PRO+ gets ATH/ATL, supply data. ELITE gets categories, description, CoinGecko ID.

Query parameters

Param	Type		Description
`search`	string	opt	Search by symbol or name
`limit`	int	opt	1-500 (default 100)
`offset`	int	opt	Pagination offset

GET/desktop/coins/{symbol} ALL Detailed coin metadata▶

Full coin metadata: logo, name, market cap, rank, supply, ATH/ATL, exchanges where available.

🧠

AI Analysis

GET/desktop/analysis ALL AI market analysis reports▶

AI-generated market analysis. FREE: today only. PRO: 7 days. ELITE: 90 days + all analysis types.

Query parameters

Param	Type		Description
`analysis_type`	string	opt	market_overview, coin_analysis, trend_report
`coin`	string	opt	Filter by coin
`days`	int	opt	1-90 (default 7)

GET/desktop/analysis/latest ALL Latest daily analysis▶

Latest overview, trend report, and coin analyses. FREE users see overview + 3 coin analyses only.

📰

News

GET/desktop/news ALL Crypto news feed▶

Latest crypto news with sentiment and importance scoring. FREE: last 24h only. PRO/ELITE: full history.

Query parameters

Param	Type		Description
`coin`	string	opt	Filter by mentioned coin
`page`	int	opt	Page number
`limit`	int	opt	1-50 (default 20)

🔔

Alerts

GET/desktop/alerts ALL Your active alerts▶

Returns your alerts with trigger count, last triggered time, cooldown settings, and tier limit.

POST/desktop/alerts ALL Create alert▶

Create a price or signal alert. Limits: FREE=3, PRO=20, ELITE=100.

JSON body

Param	Type		Description
`coin`	string	req	Coin symbol (e.g. BTC)
`alert_type`	string	req	price_above, price_below, new_signal, etc.
`params`	JSON	opt	Alert parameters
`cooldown`	int	opt	Cooldown minutes (5-1440, default 60)

DELETE/desktop/alerts/{id} ALL Deactivate alert▶

Deactivates the specified alert. Only your own alerts can be deleted.

⭐

Watchlist

GET/desktop/watchlist ALL Your watched coins with prices▶

Returns watched coins with latest prices, 24h change, and volume. Limits: FREE=5, PRO=30, ELITE=100.

POST/desktop/watchlist ALL Add coin to watchlist▶

JSON body

Param	Type		Description
`coin`	string	req	Coin symbol

DELETE/desktop/watchlist/{coin} ALL Remove from watchlist▶

Removes the coin from your watchlist.

🔓 No Authentication Required

Public API endpoints are open to everyone. Designed for marketing websites and third-party integrations.

All signal data is delayed by 4 hours to protect paying subscribers. Active signals are never exposed.

📊

Public Stats

GET/public/stats Aggregate performance for website▶

Total signals, win rate, average PnL, total PnL, TP1/2/3 hit rates, total users. Safe for marketing website.

{
  "total_signals": 580,
  "win_rate": 68.5,
  "avg_pnl_percent": 3.42,
  "total_pnl_percent": 1540.50,
  "tp1_hit_rate": 62.3,
  "tp2_hit_rate": 38.1,
  "tp3_hit_rate": 15.7,
  "total_users": 1580
}

📈

Delayed Signals

GET/public/signals Closed signals (4h delay)▶

Recent closed signals delayed by 4 hours. Filter by coin, direction, or result (win/loss).

Query parameters

Param	Type		Description
`coin`	string	opt	Filter by coin
`direction`	string	opt	long / short
`result`	string	opt	win, loss, or all
`limit`	int	opt	1-100 (default 20)
`offset`	int	opt	Pagination offset

🏆

Top Coins & Streaks

GET/public/top-coins Best performing coins by win rate▶

Top coins ranked by win rate (minimum 3 closed signals). Returns win/loss counts, avg PnL, best trade.

Query parameters

Param	Type		Description
`limit`	int	opt	1-50 (default 10)

GET/public/streak Current win/loss streak▶

Current winning or losing streak, plus last 10 trades summary (wins, losses, avg PnL).

{
  "current_streak": 5,
  "streak_type": "win",
  "last_10_wins": 7,
  "last_10_losses": 3,
  "last_10_avg_pnl": 4.21
}

⚡ WebSocket Protocol

Connect to wss://your-domain/desktop/ws

Send an auth message as the first message within 10 seconds:

{ "type": "auth", "key": "brk_your_api_key" }

On success, server responds with:

{ "type": "auth_ok", "tier": "pro", "features": { ... } }

⬇️

Server → Client Messages

Type	When	Data
`signal_new`	New signal generated	signal: {id, coin, direction, entry_price, ...}
`signal_update`	TP/SL hit, status change	signal: {id, coin, status, pnl, peak_profit, is_final}
`price_alert`	User alert triggered	alert: {coin, type, price, ...}
`heartbeat`	Every 30 seconds	ts: ISO timestamp
`pong`	Response to ping	ts: ISO timestamp

⬆️

Client → Server Messages

Type	Purpose	Example
`subscribe`	Filter updates by coins	`{"type":"subscribe","coins":["BTC","ETH"]}`
`ping`	Request heartbeat	`{"type":"ping"}`

Send an empty coins array to unsubscribe from coin filtering and receive all updates again.

🛡️

Broadcast Rules

Tier gating: Signal updates respect the signal's min_tier. If a signal is PRO-only, FREE users will not receive its updates via WebSocket.

Coin filtering: After sending a subscribe message, you only receive updates for the specified coins. Unfiltered users receive all updates.

Connection limits: Multiple connections per user are allowed. Each connection shares the same coin filter.

👑 Tier Feature Matrix

Feature	FREE	PRO	ELITE
Signal coin + direction + confidence	✅	✅	✅
Full signal details (entry/TP/SL)	❌	✅	✅
AI reasoning & factors	❌	❌	✅
Signal history	7 days	Full	Full
Alerts limit	3	20	100
Watchlist limit	5	30	100
Real-time WebSocket	❌	✅	✅
Candle data	1h+4h, 24h	All TF, 7d	All TF, full
News access	24h	Full	Full
AI analysis	Today only	7 days	90 days
Coin metadata detail	Basic	+ Supply, ATH/ATL	+ Categories, CoinGecko ID
Data export	❌	❌	✅

🛠️ Rate Limits

Resource	Limit
REST API requests	60 requests/minute per API key
WebSocket messages	10 messages/second per connection
Signal poll interval	Recommended: 10s (use WebSocket for real-time)

🌐 Supported Exchanges

Data sourced from 8 exchanges via CCXT:

Binance

Bybit

OKX

KuCoin

Gate.io

MEXC

Bitget

HTX

● BLACK ROOM

🔒 Authentication

🔓 No Authentication Required

⚡ WebSocket Protocol

👑 Tier Feature Matrix

🛠️ Rate Limits

🌐 Supported Exchanges