API Reference

REST API & WebSocket

120+ endpoints tersedia untuk tier Quant dan Institutional. Base URL: https://bandaralert.com/api/v1

Authentication

Dua metode autentikasi tersedia (dicek berurutan). Gunakan salah satu:

# Option 1: API Key (recommended)
X-API-Key: ba_live_xxxx_xxxx

# Option 2: JWT Bearer Token
Authorization: Bearer <JWT_TOKEN>

API key bisa di-generate di Settings → API Keys. Jaga keamanan API key Anda - jangan share di repository publik.

Rate Limits

Rate limit berlaku per API key. Response header X-RateLimit-Remaining menunjukkan sisa request.

Tier	Rate Limit	Burst	Concurrent
Free	60 req/jam	10 req/min	2
Pro	600 req/jam	30 req/min	5
Quant	6,000 req/jam	100 req/min	10
Institutional	Unlimited	Unlimited	50

Signals

Prefix: /api/v1/signals

Method	Endpoint	Description	Parameters
GET	/volume-anomaly	Anomali volume hari ini (semua saham)	severity=warning\|severe
GET	/broker-accumulation	Semua BASS scores terbaru	min_score=0&sort=desc
GET	/broker-accumulation/{ticker}	BASS detail per ticker dengan komponen breakdown	days=30
GET	/smart-money-v2	Smart Money Score semua saham	min_score=0
GET	/market-regime	Status regime saat ini (Bull/Neutral/Bear) + probabilitas
GET	/liquidity-stress	Liquidity shift scores per saham
GET	/sector-rotation	Sector rotation analysis + heatmap data	days=20
GET	/convergence	Saham dengan multiple sinyal converge	min_signals=2
GET	/insider-activity	Insider trading activity terbaru	days=30
GET	/multibagger-scan	Hasil multibagger scanner	min_bass=65

Market Data

Prefix: /api/v1/data

Method	Endpoint	Description	Parameters
GET	/ohlcv/{ticker}	Historical OHLCV data	days=30
GET	/broker-summary/{ticker}	Broker buy/sell per saham	days=5
GET	/earnings/{ticker}	Earnings data dan analyst consensus
GET	/fundamentals/{ticker}	Data fundamental (P/E, P/B, ROE, margins)
GET	/correlation	Correlation matrix antar saham	tickers=BBCA,BBRI&days=90
GET	/sectors	List semua sektor dan subsector IDX

Brokers

Prefix: /api/v1/brokers

Method	Endpoint	Description	Parameters
GET	/	List semua broker aktif (filterable by tier)	tier=foreign\|domestic\|retail
GET	/leaderboard	Top brokers by total flow	days=20&limit=20
GET	/{code}	Profil broker detail + batting average
GET	/{code}/holdings	Top holdings broker saat ini	limit=10
GET	/{code}/activity	Activity timeline broker	days=30

Portfolio & Tools

Prefix: /api/v1

Method	Endpoint	Description	Parameters
GET	/watchlist	Get user watchlist
POST	/watchlist	Add ticker ke watchlist	body: {ticker: string}
DELETE	/watchlist/{ticker}	Remove ticker dari watchlist
GET	/portfolio	Get user portfolio positions
POST	/portfolio	Add posisi ke portfolio	body: {ticker, lots, price}
GET	/risk-calculator	Calculate position sizing & risk-reward	entry=9200&sl=8900&tp=9800&capital=10000000
POST	/backtest	Run backtest strategi	body: {strategy config}

AI Agents

Prefix: /api/v1/ai

Method	Endpoint	Description	Parameters
POST	/stock-report	Generate AI Stock Report untuk 1 ticker	body: {ticker, timeframe, language}
POST	/bull-bear	Bull vs Bear debate + verdict	body: {ticker, timeframe, language}
GET	/daily-brief	Ringkasan pasar harian terbaru
POST	/generate-brief	Trigger generate daily brief (admin)
POST	/report-pdf	Download AI Stock Report sebagai PDF	body: {ticker, timeframe}
POST	/debate-pdf	Download Bull/Bear debate sebagai PDF	body: {ticker, timeframe}
GET	/brief-pdf	Download Daily Brief sebagai PDF	date=2026-04-18
POST	/portfolio-risk	AI analyze risiko portfolio user	body: {holdings: [{ticker, weight}]}
GET	/quota	Cek quota AI yang tersisa hari ini

Network (Broker Flow)

Prefix: /api/v1/network

Method	Endpoint	Description	Parameters
GET	/broker-graph	Bipartite graph broker↔ticker	days=20
GET	/broker-bubbles	Data untuk visualisasi bubble (ukuran + warna)	limit=30

Computed (Aggregates)

Prefix: /api/v1/computed

Method	Endpoint	Description	Parameters
GET	/enriched-list	Key ratios + BASS + flow untuk semua 874 saham
GET	/broker-leaderboard	Top broker berdasarkan aktivitas	days=1&limit=30 (max 200)
GET	/broker-portfolio/{code}	Komposisi portfolio broker
GET	/correlation	Correlation matrix untuk beberapa ticker	tickers=BBCA,BBRI&days=60
GET	/risk-reward/{ticker}	Auto risk-reward analysis dengan scenario	days=30&risk_percent=1
GET	/stock-enrichment/{ticker}	Mega endpoint: semua data untuk 1 ticker
GET	/financials/{ticker}	Laporan keuangan lengkap

Trail (Dana Tracking)

Prefix: /api/v1/trail

Method	Endpoint	Description	Parameters
GET	/stock/{ticker}	Jejak arus dana per saham	days=20
GET	/broker/{code}	Jejak arus dana per broker	days=20
GET	/reversals	Sinyal reversal dari tracking dana

Backtest

Prefix: /api/v1/backtest

Method	Endpoint	Description	Parameters
GET	/run	Jalankan backtest strategi	signal_type=bass&threshold=70&hold_days=10&ticker=BBCA

Watchlists

Prefix: /api/v1/watchlists

Method	Endpoint	Description	Parameters
GET	/	List semua watchlist user
POST	/	Create/update watchlist	body: {name, tickers: [...]}

Alerts

Prefix: /api/v1/alerts

Method	Endpoint	Description	Parameters
GET	/	Riwayat alert yang pernah dikirim	limit=50

Preferences

Prefix: /api/v1/preferences

Method	Endpoint	Description	Parameters
GET	/	Get user preferences (bahasa, theme, indicator settings)
PUT	/	Update user preferences	body: {language, theme, indicators}
GET	/presets	List preset indicator yang tersedia
POST	/apply-preset	Apply preset ke user settings	body: {preset_id}
GET	/impact-preview	Preview dampak perubahan indikator ke BASS score

Auth

Prefix: /api/v1/auth

Method	Endpoint	Description	Parameters
POST	/register	Register akun baru	body: {email, password, display_name, referral_code?}
POST	/login	Login email + password, returns JWT	body: {email, password}
POST	/google	Login via Google OAuth	body: {id_token}
POST	/forgot-password	Kirim link reset password ke email	body: {email}
POST	/reset-password	Reset password dengan token dari email	body: {token, new_password}
PUT	/password	Change password (harus login)	body: {current_password, new_password}
POST	/refresh	Refresh JWT access token	body: {refresh_token}
POST	/logout	Logout + revoke refresh token	body: {refresh_token}
GET	/me	Profile user + tier info

Billing & Payments

Prefix: /api/v1/billing

Method	Endpoint	Description	Parameters
GET	/plans	List subscription plans + harga
POST	/subscribe	Buat invoice subscribe + amount unik untuk QRIS	body: {plan_id}
GET	/invoices	Riwayat invoice user	page=1&limit=10
POST	/upload-proof	Upload bukti transfer QRIS (auto-verified by AI Vision)	multipart file

Referral Program

Prefix: /api/v1/referral

Method	Endpoint	Description	Parameters
GET	/code	Get kode referral user + statistik
GET	/credits	Balance kredit referral (20% first-sub, 5% renewal)
POST	/apply	Apply kode referral saat checkout (diskon 10%)	body: {referral_code}

Helpdesk

Prefix: /api/v1/helpdesk

Method	Endpoint	Description	Parameters
POST	/tickets	Buat tiket support (auto-forward ke Telegram admin)	body: {category, subject, message, screenshot?}
GET	/tickets	Riwayat tiket user
GET	/tickets/{id}	Detail tiket + replies
POST	/tickets/{id}/reply	Reply tiket	body: {message}

Response Format

Semua response menggunakan format JSON yang konsisten:

// Success response
{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2026-03-19T10:30:00Z",
    "count": 874,
    "page": 1,
    "total_pages": 1
  }
}

// Error response
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "retry_after": 60
  }
}

Contoh Penggunaan

import requests

API_KEY = "ba_live_xxxx_xxxx"
BASE = "https://bandaralert.com/api/v1"
headers = {"X-API-Key": API_KEY}

# 1. Get semua BASS scores
resp = requests.get(f"{BASE}/signals/broker-accumulation", headers=headers)
signals = resp.json()["data"]

for s in signals[:5]:
    print(f"{s['ticker']}: BASS={s['bass_score']:.0f}, Confidence={s['confidence']}")

# 2. Get OHLCV data untuk BBCA (30 hari)
ohlcv = requests.get(f"{BASE}/data/ohlcv/BBCA?days=30", headers=headers).json()
print(f"BBCA: {len(ohlcv['data'])} data points")

# 3. Get market regime
regime = requests.get(f"{BASE}/signals/market-regime", headers=headers).json()
print(f"Regime: {regime['state']} (prob: {regime['probability']:.0%})")

WebSocket API

Real-time streaming untuk tier Quant dan Institutional. Menerima update sinyal segera setelah pipeline harian selesai.

Channel	Description	Frequency
bass_updates	BASS score updates setelah pipeline harian	1x/hari (17:30 WIB)
volume_anomaly	Volume anomaly alerts real-time	Event-driven
regime_change	Market regime transitions	Event-driven
convergence	Multi-signal convergence alerts	1x/hari (17:30 WIB)

Contoh WebSocket

// WebSocket connection (Quant tier)
const ws = new WebSocket("wss://bandaralert.com/ws");

ws.onopen = () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: "auth",
    api_key: "ba_live_xxxx_xxxx",
  }));

  // Subscribe to channels
  ws.send(JSON.stringify({
    type: "subscribe",
    channels: ["bass_updates", "volume_anomaly", "regime_change"],
    tickers: ["BBCA", "BBRI", "TLKM"],  // optional filter
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  switch (data.type) {
    case "bass_update":
      console.log(`${data.ticker}: BASS ${data.bass_score}`);
      break;
    case "volume_anomaly":
      console.log(`Alert: ${data.ticker} volume z-score ${data.z_score}`);
      break;
    case "regime_change":
      console.log(`Regime changed to: ${data.new_state}`);
      break;
  }
};

Connection URL: wss://bandaralert.com/ws. WebSocket mendukung auto-reconnect. Ping/pong heartbeat setiap 30 detik untuk menjaga koneksi tetap aktif.

Error Codes

HTTP	Code	Description
400	BAD_REQUEST	Request parameter tidak valid atau missing
401	UNAUTHORIZED	API key atau JWT token tidak valid atau expired
403	FORBIDDEN	Tier Anda tidak memiliki akses ke endpoint ini
404	NOT_FOUND	Resource tidak ditemukan (ticker, broker code, dll)
429	RATE_LIMIT_EXCEEDED	Rate limit tercapai. Tunggu sesuai retry_after
500	INTERNAL_ERROR	Server error. Coba lagi dalam beberapa saat
503	PIPELINE_RUNNING	Data sedang diproses. Coba lagi dalam 15-30 menit

OpenAPI Spec: Dokumentasi lengkap tersedia dalam format OpenAPI 3.0 di https://bandaralert.com/openapi.json. Gunakan untuk generate SDK di bahasa apa pun menggunakan tools seperti openapi-generator.

Glosarium

Definisi istilah-istilah

FAQ

Pertanyaan yang sering diajukan