WhaleScope MCP — Binance Futures Market Intelligence

🇮🇩 Bahasa Indonesia | 🇬🇧 English

MCP server yang menyediakan data publik Binance USDS-M Futures (funding rate, open interest, long/short ratio, taker volume, candlestick, order book, volatility) plus pembanding Binance Spot (harga, order book, candlestick, CVD) sebagai tools yang bisa dipanggil Claude. Semua data yang disajikan bersifat publik read-only — tidak ada order/trading, tidak ada akses ke data akun pribadi.

Quick Deploy

Tombol ini clone repo + bikin Worker di akun Cloudflare kamu sendiri, termasuk provision KV namespace & D1 database baru otomatis (Cloudflare generate id/database_id baru buat akun kamu, gak perlu bikin manual). Bukan zero-touch sepenuhnya — biar jujur soal apa yang masih manual: setelah klik, kamu TETAP perlu set secret (Cloudflare gak bisa nebak value dari layanan eksternal) — lihat .dev.vars.example di repo ini buat daftar lengkap, atau Setup Proxy Vercel di bawah. PROXY_URL/PROXY_SECRET WAJIB (semua 46 tool butuh).

Tujuan

Menyediakan gambaran positioning pasar Binance Futures — bukan cuma harga, tapi juga siapa yang lagi buka posisi apa (retail vs top trader), seberapa crowded leverage-nya, dan di harga berapa likuiditas menumpuk — langsung dalam percakapan dengan Claude, tanpa perlu buka dashboard exchange terpisah.

Manfaat

• Satu pintu buat banyak sinyal. Funding rate, open interest, order book, dan order flow — semua lewat satu MCP connector, bukan gonta-ganti tab.
• Bisa bedain retail vs whale. binance_get_top_trader_ratio kasih breakdown murni top-trader (terpisah dari binance_get_long_short_ratio yang blended) — berguna buat lihat kalau posisi retail dan whale lagi divergen.
• Native Binance di mana itu penting. Harga, funding rate, klines, order book — semua lewat jalur native Binance (bukan derivasi pihak ketiga), supaya presisi terjaga terutama untuk pair kecil/kurang likuid.
• Gratis buat pemakaian personal — lihat bagian Biaya.

Kelebihan

• 29 tools mencakup lima sudut analisis: bias arah pasar, area harga kunci (order book), konfirmasi eksekusi (order flow/aggressor), pembanding Futures-vs-Spot (leverage-driven vs demand riil), dan market-wide scan (funding rate ekstrem lintas semua pair, atau bandingkan metrik across beberapa pair) — plus tool composite (binance_analyze_pair) buat overview cepat tanpa banyak tool call, dan config/histori (threshold per-pair, basis time-series) yang tersimpan di Workers KV.
• Read-only terhadap data pasar Binance — tidak ada order/trading. Satu- satunya tool yang menulis state (binance_set_pair_threshold) cuma nyimpen preferensi threshold kamu sendiri di Workers KV, tidak menyentuh akun Binance/data pihak luar sama sekali.
• Transparan soal keterbatasan tiap tool (lihat bagian di bawah), bukan dibungkus seolah semua data sempurna.
• Infrastruktur cukup dengan free tier (Cloudflare Workers + Vercel Hobby) untuk pemakaian personal — 100% Binance-native, tidak ada dependensi agregator pihak ketiga lagi.

Kekurangan

• Sebagian besar tool request/response. Funding/OI/klines/order book/ratio semua snapshot atau histori periodik. Data streaming yang ada terbatas: binance_get_realtime_liquidations + binance_get_contract_events (via stream gateway VPS, lihat di bawah) — tidak ada push tick-by-tick untuk harga / order book.
• Liquidation: SAMPLED, bukan lengkap. Sejak 2026-08-28 ada binance_get_realtime_liquidations — WebSocket !forceOrder@arr (dstream.binance.com) di-buffer always-on di VPS Oracle Singapore (stream-gateway/, di luar Cloudflare — worker Cloudflare sendiri masih di-WAF-block dari Binance). Binance men-throttle stream ini maks 1 event/symbol/detik, jadi ini SAMPEL likuidasi, bukan tiap satu. Tetap cukup buat konfirmasi cluster stop-hunt di binance_detect_mm_activity (proxy ke-3, price-anchored & sisi-hunt). Tidak ada histori liquidation jauh ke belakang (buffer 24 jam).
• Setup awal butuh proxy Vercel (wajib) — bukan pasang-langsung-jalan, ada langkah konfigurasi manual sekali di awal.
• Tidak ada data wallet on-chain atau data dari exchange selain Binance Futures USDS-M.

Sumber data: satu jalur, 100% Binance native.

• Binance native, lewat proxy relay Vercel. Domain Binance (fapi.binance.com) memblokir traffic dari Cloudflare Workers di level WAF (403, company-wide — sudah dites langsung dari worker ini, bukan asumsi). Vercel pakai IP pool berbeda, jadi tidak kena block yang sama. Worker Cloudflare relay lewat proxy kecil di proxy/ (project Vercel terpisah, lihat proxy/README.md). Ini jalur untuk funding rate (current & histori), klines/OHLCV, bias multi-timeframe, realized volatility, statistik 24 jam, order book depth, aggregate trades, open interest (current & histori), long/short ratio (blended & top-trader), taker buy/sell volume ratio, dan harga spot (proxy juga relay ke Binance Spot API api.binance.com lewat parameter market=spot, lihat proxy/README.md).

Konsekuensinya, worker ini butuh PROXY_URL/PROXY_SECRET (proxy Vercel, wajib buat semua 46 tool) — lihat bagian Setup di bawah.

Caching & state, tanpa kredensial tambahan. Response upstream (funding rate, klines, OI, dll — kecuali order book & aggregate trades yang butuh freshness ketat) di-cache bertingkat (5 detik-1 jam tergantung endpoint) lewat Cache API bawaan Cloudflare Workers, tidak perlu setup apapun. Threshold custom per-pair tersimpan di Workers KV (binding CONFIG_KV). Time-series (basis+funding+OI, dan 6 skor sinyal binance_detect_mm_activity) tersimpan di D1 (binding DB) — diisi otomatis oleh Cron Trigger tiap 5 menit untuk watchlist tetap 50 pair (SNAPSHOT_WATCHLIST di src/shared.ts, diurutkan market cap, mis. BTCUSDT, ETHUSDT, SOLUSDT, BNBUSDT, XRPUSDT, dst).

Cross-exchange, tanpa proxy tambahan. whalescope_compare_funding_across_exchanges akses Bybit/OKX/Hyperliquid LANGSUNG dari worker (dites dari edge Cloudflare beneran, gak kena WAF/geo-block kayak Binance) — gak ada kredensial atau setup tambahan buat 3 exchange itu.

Yang disediakan

Konvensi detail: summary vs full (hemat token)

Semua tool di atas yang balikin data array/histori (klines, agg trades, order book, open interest/funding/basis history, long-short & top-trader ratio) punya parameter opsional detail: "summary" | "full", default "summary". Ini satu-satunya perubahan default-behavior yang disengaja di pembaruan token-efficiency 2026-08 — bukan penghapusan parameter, cuma default baru:

• detail: "summary" (default) — cuma metrik turunan (bias, tren, CVD, dominance, dst — yang memang sudah dihitung tool-nya) + maksimal 10 poin data terbaru. Ini yang dipakai kalau kamu tidak mengirim detail sama sekali, TERMASUK untuk caller lama yang belum tahu param ini ada.
• detail: "full" — array/level mentah penuh, perilaku identik dengan sebelum pembaruan ini.

Tool composite (binance_analyze_pair, binance_analyze_smart_money, binance_detect_mm_activity, analyze_futures_grid_risk, whalescope_full_pipeline) juga dirapikan: teks dipotong ~8-12 baris, structuredContent jadi payload utama dengan key lebih pendek/flat, field kosong (null/undefined) dibuang. Tidak ada sinyal/metrik yang hilang — semua tetap reachable via structuredContent atau detail: "full".

Detail lengkap + mapping field yang berganti nama: docs/tool_response_reference.md.

Framework Analisis: Deteksi Market Maker & Whale

Tidak ada tool yang bisa melihat identitas atau posisi spesifik market maker (MM)/whale secara langsung — data Binance yang publik memang tidak menyediakan itu. Yang bisa dilakukan (dan itulah fungsi framework ini): membaca jejak aktivitas mereka dengan menggabungkan beberapa tool di atas, lalu menghitung skor indikasi dari pola yang muncul.

Empat kategori sinyal yang dideteksi:

Rule of thumb: kalau ≥3 sinyal align dalam timeframe yang sama, indikasi aktivitas MM cukup kuat untuk ditindaklanjuti — ini heuristik checklist (lihat tier confidence di dokumen lengkap), bukan probabilitas yang terkalibrasi secara statistik.

Dokumen lengkap: docs/mm_detection_framework.md (v4, final) — berisi kriteria detail tiap sinyal, workflow step-by-step, checklist live, dan mapping tool → sinyal.

Framework: Full Pipeline Grid Bot (whalescope_full_pipeline)

Tool composite tertinggi di repo ini — menjalankan SELURUH decision chain Grid Bot Futures dalam satu tool call, untuk satu atau banyak symbol sekaligus (maks 20 per call), menggantikan ~8 tool call manual (binance_market_regime ×2, binance_analyze_smart_money, binance_detect_mm_activity, binance_get_order_book_imbalance, analyze_futures_grid_risk, dst.) plus kalkulasi bound grid yang sebelumnya tidak ada tool-nya sama sekali.

Tahapan (2-wave fetch, reject-early):

┌───────────────────────────────────────────────────────────────┐
│ WAVE 1 (semua symbol, paralel): ticker24hr, funding, klines    │
│ 1h+4h, OI+histori, agg trades, market context                  │
├───────────────────────────────────────────────────────────────┤
│ HARD SCREEN: tradable? volume >= minimum? |funding| <= maks?   │
│ regime 1h/4h != BREAKOUT?                                       │
│   → GAGAL = NO_TRADE, Wave 2 TIDAK PERNAH DIPANGGIL             │
├───────────────────────────────────────────────────────────────┤
│ WAVE 2 (survivor saja, paralel): top-trader ratio, global      │
│ account ratio, OI histori 24 titik, order book depth 50        │
├───────────────────────────────────────────────────────────────┤
│ TIER-1 SCORING: smart money divergence + 6 skor MM composite   │
│ + order book imbalance + CVD + regime → rankingScore 0-100     │
├───────────────────────────────────────────────────────────────┤
│ GRID BOUNDS (Compass-equivalent): ATR + swing high/low →       │
│ upper/lower/SL/TP/gridCount/gridType                            │
├───────────────────────────────────────────────────────────────┤
│ CAPITAL SOLVE: exact (bukan iteratif) per opsi leverage, pilih  │
│ leverage tertinggi SAFE/MODERATE dengan likuidasi aman          │
├───────────────────────────────────────────────────────────────┤
│ KEPUTUSAN: TRADE / WATCH / NO_TRADE + Grid Bot config siap-pakai│
└───────────────────────────────────────────────────────────────┘

Dokumen lengkap (stage-by-stage, worked example, Known Limitations): docs/full_pipeline_framework.md.

Hasil Validasi Empiris

Setiap klaim teknis di framework ini divalidasi langsung ke worker deployed (bukan asumsi) sebelum masuk versi final. Beberapa temuan yang mengoreksi asumsi awal:

Detail penuh (termasuk raw data test per klaim): Section 10, docs/mm_detection_framework.md.

Keterbatasan yang jujur perlu diketahui

• Long/short ratio (binance_get_long_short_ratio) adalah rasio agregat BLENDED, bukan breakdown terpisah "global account (retail)" vs "top trader (whale)". Untuk breakdown murni top-trader, pakai binance_get_top_trader_ratio (sudah native Binance, terpisah dari tool ini).
• Basis funding rate bisa noisy untuk pair kecil/baru listing — index price Binance adalah rata-rata tertimbang dari beberapa exchange spot, salah satunya bisa illikuid untuk pair semacam itu.
• Order book depth (binance_get_order_book_depth) adalah snapshot sesaat — wall besar bisa hilang dalam hitungan detik (potensi spoofing), jangan overinterpretasi satu snapshot. Untuk deteksi spoofing RIIL (2-snapshot), pakai binance_get_orderbook_delta atau binance_detect_mm_activity (lihat di bawah).
• Threshold "top trader" tidak dipublikasikan Binance secara pasti, dan datanya snapshot periodik, bukan real-time tick-by-tick.
• Data histori OI (binance_get_open_interest_history) dibatasi retensi endpoint resmi Binance (/futures/data/openInterestHist), cek langsung kalau butuh rentang panjang.
• Tidak ada data wallet on-chain.
• Liquidation cuma near-real-time + SAMPLED, tidak ada histori panjang. binance_get_realtime_liquidations baca buffer 24 jam dari stream gateway VPS (!forceOrder@arr via dstream.binance.com — fstream.binance.com di-black-hole dari IP VPS). Binance throttle 1 event/symbol/detik → sampel, bukan lengkap. Tidak ada REST publik market-wide buat backfill historis. Worker Cloudflare sendiri masih tidak bisa WS langsung ke Binance (WAF).
• binance_detect_mm_activity: spoofing sekarang 2-snapshot RIIL (~1-2 detik lebih lambat dari tool lain karenanya, jeda eksplisit 1500ms antar 2 fetch — lihat binance_get_orderbook_delta), bukan heuristik 1-snapshot lagi. Stop-hunt sekarang simetris (cek upper DAN lower wick, dulu cuma upper — bug lama) + 2 proxy independen (reuse fetch yang sudah ada, bukan fetch baru): OI turun >=2% berbarengan sama wick candle, dan/atau volume trade agresif >=30% terkonsentrasi tepat di zona harga wick itu (dari 100 aggTrades terakhir, sama data yang dipakai CVD). Confidence naik bertahap: 0 proxy aktif = base, 1 proxy = lebih tinggi, 2 proxy sekaligus = tertinggi — TETAP TANPA data liquidation-by-price riil (permanen, lihat poin di atas). Confidence stop-hunt masih lebih rendah dari sinyal lain di tool yang sama — dicatat di evidence text tiap response.
• binance_market_regime: spike volatilitas/volume dihitung relatif ke window fetch yang sama (10 candle terakhir vs 10 sebelumnya), bukan baseline historis jangka panjang.
• Time-series D1 (market_snapshots, dibaca binance_get_basis_history) SELALU tersedia untuk watchlist tetap 50 pair, best-effort untuk pair lain — pair non-watchlist dapat histori kalau di-query >=3x dalam ~24 jam DAN masuk top-5 pair non-watchlist paling sering di-query (KV counter, src/queryFrequency.ts), cron 5 menit baru snapshot pair itu setelah kondisi terpenuhi. signal_history (dibaca binance_backtest_signal) TETAP watchlist-only, tidak ikut diperluas.
• Pair futures-only (HYPEUSDT, 1000PEPEUSDT, PUMPUSDT, dst.) — spot_price & basis NULL di market_snapshots karena tidak listed di Binance Spot. Funding rate & Open Interest tetap tercatat normal; cuma kolom basis yang kosong buat pair semacam itu.
• Belum ada pruning/retention buat row D1 — row nambah terus tanpa batas seiring waktu (di 50 pair x ~6.048 row/hari gabungan kedua tabel, D1 free tier 5 juta write/hari & 5GB storage masih longgar untuk waktu yang lama, tapi ini bukan solusi permanen).
• Migrasi KV→D1 (basis history) TIDAK backfill data lama — histori basis yang sempat tersimpan di Workers KV sebelum migrasi ini hilang, window 24 jam baru keisi ulang natural beberapa jam setelah deploy.
• binance_backtest_signal: forward return DIHITUNG ON-DEMAND dari klines historis (close candle 1h terdekat ke waktu target), BUKAN simulasi eksekusi order riil — slippage/fee/partial fill tidak dihitung. Sample size kecil (di bawah ~20 sinyal) berarti confidence rendah, jangan simpulkan sinyal "reliable" dari sedikit data historis (baru mulai terkumpul dari kapan fitur ini deploy, bukan retroaktif).
• pipeline_decision_log + whalescope_backtest_pipeline_decisions: keputusan per-symbol Phase 2 entry-alert (dan persist=true) disimpan compact 90 hari. Forward return / SL-touch dihitung on-demand dari klines — bukan precompute, bukan auto-tune bobot 35/30/20/15 atau threshold 55. entry_alert_skip_log retensi 30 hari.
• whalescope_compare_funding_across_exchanges: Open Interest belum divalidasi silang ke data live antar 4 exchange (SEHARUSNYA base-asset di semua exchange termasuk OKX yang pakai field oiCcy, tapi belum ada pengecekan langsung — cek ulang kalau angkanya kelihatan janggal). Symbol mapping Binance→exchange lain best-effort (strip suffix USDT) — pair kecil yang gak listed di Bybit/OKX/Hyperliquid bakal muncul "gagal" di baris itu, bukan bikin tool call gagal total.
• Rate limit self-throttle ke proxy Binance itu best-effort, BUKAN hard global limiter — counter in-memory per-isolate (src/rateLimiter.ts), efektif SELAMA isolate yang sama dipakai ulang buat request beruntun, TAPI worker ini stateless per-request jadi bukan jaminan keras cross-isolate. Threshold 200 request/menit, count-based (bukan weight-based per-endpoint kayak limit asli Binance).
• binance_get_tool_catalog SEMI-otomatis — nama+description SELALU akurat (ditarik dari tool registry, gak pernah basi/ketinggalan). Tapi category/token-cost/dependencies TETAP manual (CATALOG_METADATA di src/tools/catalog.ts) — tool baru yang belum di-curated bakal muncul dengan category "uncategorized", tetap kelihatan (gak ke-omit diam-diam) tapi belum ter-kategorisasi rapi.
• binance_analyze_smart_money pakai threshold FIXED (bukan hasil kalibrasi statistik per-pair) — lihat Section 4.2 & 12 di docs/mm_detection_framework.md untuk kenapa threshold absolut pada top-trader ratio harus dipakai hati-hati. confidenceScore output-nya mengukur margin di atas threshold, BUKAN probabilitas statistik terkalibrasi.

Setup Proxy Vercel (wajib, sekali saja)

Tool berlabel "Binance native" di tabel atas butuh proxy relay di Vercel, karena worker Cloudflare diblokir langsung oleh WAF Binance. Detail deploy proxy ada di proxy/README.md — ringkasnya:

1. Deploy folder proxy/ sebagai project Vercel terpisah (Root Directory = proxy), set env var PROXY_SECRET di Vercel (string acak, generate sendiri, misal openssl rand -hex 32).
2. Set dua secret ini di worker Cloudflare:
   Terminal

   Copy

   npx wrangler secret put PROXY_URL
   npx wrangler secret put PROXY_SECRET
   

   PROXY_URL = URL project Vercel (contoh https://whale-pearl.vercel.app), PROXY_SECRET = string yang sama persis dengan yang di-set di Vercel.

Tanpa dua secret ini, tool berlabel "Binance native" akan gagal dengan pesan error yang jelas ("PROXY_URL atau PROXY_SECRET belum diset di worker").

Penting: jangan pernah buat secret Cloudflare dengan VALUE sebagai NAME (misal wrangler secret put lalu tidak sengaja paste value di prompt nama). wrangler secret list hanya boleh membocorkan nama secret, tidak pernah value — kesalahan ini membuat value asli bocor lewat command yang seharusnya aman.

Proxy sekunder / failover (opsional)

Kalau proxy primary kena WAF block/rate-limit/5xx, worker otomatis coba proxy sekunder — TAPI cuma kalau dikonfigurasi. Tanpa ini, perilaku persis sama seperti sebelumnya (1 proxy, error langsung dilempar kalau gagal).

1. Deploy instance Vercel KEDUA dari folder proxy/ yang sama (region beda kalau mau, misal Hong Kong vs Singapore) dengan PROXY_SECRET sendiri (boleh beda dari primary).
2. Set dua secret tambahan:
   Terminal

   Copy

   npx wrangler secret put PROXY_URL_2
   npx wrangler secret put PROXY_SECRET_2
   

Failover cuma jalan untuk error yang berkaitan sama kesehatan/kredensial tier (401 secret salah, 403 WAF block, 429 rate limit, 5xx) — bukan buat error request genuinely (400 symbol salah, 404) yang bakal gagal identik di tier manapun. 401 SENGAJA termasuk (beda dari versi sebelumnya) karena tiap tier proxy punya secret SENDIRI — primary salah bukan berarti secondary juga salah.

Direct fallback (tier terakhir, otomatis ON)

Kalau primary DAN secondary (kalau dikonfigurasi) sama-sama gagal, worker otomatis coba langsung ke fapi.binance.com/api.binance.com TANPA proxy sama sekali sebagai last-resort. Tidak butuh setup apapun (default ON) -- set DISABLE_DIRECT_FALLBACK=true di environment variable worker (bukan secret, plain var biasa) kalau mau matikan. Lihat komentar "DIRECT FALLBACK" di src/binanceProxyClient.ts untuk detail & catatan jujur soal kenapa tier ini kemungkinan besar tetap kena WAF block di kondisi produksi saat ini (worker Cloudflare ini SUDAH TERBUKTI diblokir Binance secara langsung) -- tetap berguna untuk wrangler dev lokal (IP pool beda dari edge Cloudflare produksi) dan sebagai jaring pengaman kalau kebijakan block berubah.

Setup Workers KV (wajib, sekali saja — kalau fork/deploy repo ini sendiri)

id KV namespace di wrangler.toml repo ini terikat ke akun Cloudflare yang bikin — kalau kamu fork/clone dan deploy ke akun sendiri, wajib bikin namespace baru:

npx wrangler kv namespace create WHALESCOPE_CONFIG

Copy id yang muncul ke [[kv_namespaces]] di wrangler.toml, ganti value id yang lama (binding-nya biarkan tetap CONFIG_KV, kode worker rujuk nama binding itu, bukan id). Tanpa ini, binance_set_pair_threshold dan binance_get_pair_threshold akan gagal dengan error jelas ("CONFIG_KV belum ke-bind di worker").

Setup Workers D1 (wajib, sekali saja — kalau fork/deploy repo ini sendiri)

Sama seperti KV di atas, database_id D1 di wrangler.toml repo ini terikat ke akun Cloudflare yang bikin. Kalau fork/deploy ke akun sendiri:

npx wrangler d1 create whalescope-mcp-db

Copy database_id yang muncul ke [[d1_databases]] di wrangler.toml (binding biarkan tetap DB), lalu jalankan migration:

npx wrangler d1 migrations apply whalescope-mcp-db --remote

Tanpa ini, binance_get_basis_history dan binance_backtest_signal akan gagal dengan error jelas ("D1 database (binding DB) belum ke-bind di worker"), dan Cron Trigger snapshot basis+sinyal MM (tiap 5 menit) akan gagal silent tiap tick (ke-log ke Workers Logs, tidak menggagalkan endpoint /mcp lain).

Admin: Usage Log (OPSIONAL)

Worker publik gampang ditemuin (terdaftar di MCP Server Registry) — jadi ada endpoint kecil buat liat siapa aja yang connect. Ini BUKAN MCP tool (sengaja HTTP endpoint terpisah, gak pernah muncul di tools/list) — kalau dibikin tool biasa, SIAPA AJA yang connect ke server ini bisa liat IP visitor lain, kontradiksi sama tujuannya.

1. Set secret (tanpa ini, endpoint SELALU balik 403 — fitur nonaktif by default, aman):
   Terminal

   Copy

   npx wrangler secret put ADMIN_SECRET
   

2. Akses:
   Terminal

   Copy

   curl "https://<worker-url>/admin/usage?key=<ADMIN_SECRET>&hours=24"
   

   Balikin JSON: total request, jumlah IP unik, top 20 IP (+ negara, count), 20 request terakhir mentah. Default window 24 jam, bisa diubah lewat hours.

Monitoring & Alerting

Backend ini punya beberapa titik gagal diam-diam (proxy Vercel/VPS mati, WS stream gateway putus, Cron Trigger di-Cancel platform). Yang ada sekarang, semua lewat Telegram (butuh TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID di-set — kalau tidak, alert cuma ke Workers Logs):

Semua cek KV-gated (maks 1 alert per cooldown selagi kondisi persist), aman dijalanin tiap 5 menit.

Yang MASIH belum ada (kerjaan dashboard, bukan kode):

• Uptime monitor eksternal ke worker / + relay https://<vps>/health — pakai UptimeRobot / Cloudflare Health Checks (gratis, 5-menit). Ini yang paling cepat nangkep VPS/relay mati total; cek internal di atas cuma backstop dengan lag.
• Cloudflare notification untuk spike error-rate Workers / CPU-limit — observability ([observability] enabled = true) cuma ngumpulin data, gak ada rule alert.

Keamanan: DNS Rebinding Protection (OPSIONAL)

Endpoint /mcp memvalidasi header Origin sebelum memproses request -- default izinkan https://claude.ai/https://claude.com (dan request TANPA header Origin sama sekali, yang mencakup mayoritas MCP client server-to-server, termasuk cara worker ini dipakai sebagai custom connector). Request dengan Origin LAIN yang tidak diizinkan dibalas 403. Ini pengganti opsi bawaan SDK (enableDnsRebindingProtection/ allowedHosts/allowedOrigins) yang sudah @deprecated di @modelcontextprotocol/sdk -- SDK sekarang merekomendasikan middleware eksternal, itu yang dilakukan di sini.

Kalau kamu punya web app sendiri yang perlu manggil /mcp langsung dari browser, tambahkan origin-nya:

npx wrangler secret put ALLOWED_ORIGINS
# contoh value: https://app-kamu.com,https://staging.app-kamu.com

(comma-separated, tanpa spasi setelah koma juga OK -- di-trim otomatis.)

Data disimpan di D1 (request_log), di-prune otomatis tiap Cron tick buat row lebih dari 30 hari (tabel ini gak dibatasi watchlist tetap kayak market_snapshots/signal_history, jadi bisa growth kalau ada traffic asing beneran).

Setup Deploy Otomatis (GitHub Actions → Cloudflare Workers)

Repo ini sudah punya workflow di .github/workflows/deploy.yml yang otomatis menjalankan wrangler deploy setiap kali ada push ke branch main.

Langkah setup (sekali saja)

1. Buat Cloudflare API Token

1. Buka https://dash.cloudflare.com/profile/api-tokens
2. Klik "Create Token"
3. Gunakan template "Edit Cloudflare Workers"
4. Scope ke akun kamu, lalu buat token
5. Salin token yang muncul (hanya ditampilkan sekali)

2. Tambahkan token sebagai GitHub Secret

1. Buka repo ini di GitHub → Settings → Secrets and variables → Actions
2. Klik New repository secret
3. Name: CLOUDFLARE_API_TOKEN
4. Value: token dari langkah 1
5. Simpan

3. Trigger deploy

Deploy akan otomatis jalan begitu ada push baru ke main. Untuk trigger manual tanpa push baru, buka tab Actions di GitHub repo → pilih workflow "Deploy to Cloudflare Workers" → Run workflow.

4. Cek hasil deploy

Setelah workflow selesai (cek tab Actions), worker akan live di:

https://whalescope-mcp.<subdomain-cloudflare-kamu>.workers.dev

Buka URL tersebut — harus muncul JSON status "ok".

Setup Custom Domain (whalescope-mcp.jaringan.dev)

Ini tidak bisa dilakukan lewat GitHub Actions — perlu langkah manual satu kali di dashboard Cloudflare:

1. Buka https://dash.cloudflare.com → pilih akun kamu
2. Buka Workers & Pages → pilih worker whalescope-mcp
3. Buka tab Settings → Domains & Routes
4. Klik Add → Custom Domain
5. Masukkan whalescope-mcp.jaringan.dev
6. Cloudflare akan otomatis membuat DNS record yang diperlukan jika domain jaringan.dev sudah berada di zona Cloudflare akun yang sama. Kalau domain itu terdaftar di akun/registrar lain, kamu perlu tambahkan CNAME record secara manual mengarah ke target yang ditampilkan Cloudflare.

Setelah custom domain aktif, worker bisa diakses di https://whalescope-mcp.jaringan.dev (bukan lagi domain .workers.dev).

Daftarkan sebagai Custom Connector di Claude

1. Buka Claude (claude.ai) → Settings → Connectors
2. Pilih Add custom connector
3. Masukkan URL: https://whalescope-mcp.jaringan.dev/mcp (atau https://whalescope-mcp.<subdomain>.workers.dev/mcp jika belum setup custom domain — perhatikan path /mcp di akhir, wajib)
4. Simpan, lalu aktifkan connector tersebut untuk percakapan yang kamu mau

Contoh Penggunaan

Setelah connector aktif, tinggal minta lewat percakapan biasa — Claude yang menentukan tool mana yang dipanggil (dan berapa kali) berdasarkan pertanyaan:

• "Funding rate BTCUSDT sekarang gimana, ada indikasi crowded?" → binance_get_funding_rate
• "Pair apa yang funding-nya paling ekstrem sekarang di seluruh market?" → binance_scan_funding_extremes
• "Cek overview lengkap ETHUSDT — funding, OI, order book, bias harga" → binance_analyze_pair (composite, 1 call ganti 6 tool terpisah)
• "Ada tanda-tanda aktivitas market maker di SOLUSDT belakangan ini?" → kombinasi beberapa tool (order book, agg trades, OI, klines) mengikuti Framework Analisis di atas — sebutkan pair-nya, Claude yang menjalankan workflow deteksinya
• "Bandingin funding rate BTC, ETH, SOL, sama BNB" → binance_compare_symbols
• "Layak gak buka Grid Bot Futures di BTCUSDT dan ETHUSDT sekarang, budget rugi $20?" → whalescope_full_pipeline (composite tertinggi, 1 call jalanin hard screen → Tier-1 intel → grid bounds → risk sizing → keputusan TRADE/WATCH/NO_TRADE + parameter Grid Bot siap copy-paste untuk kedua pair sekaligus)

Karena semua tool read-only, aman dicoba tanya apapun soal data pasar tanpa risiko memicu order/trading — worker ini tidak punya kemampuan itu sama sekali.

Uji coba manual sebelum daftar ke Claude (disarankan)

npm test (vitest) + npm run typecheck adalah automated check di repo ini — tapi keduanya cuma nge-cover pure logic (scoring functions, D1/KV wrapper, tool handler lewat fake McpServer), BUKAN Workers fetch/ scheduled handler beneran (gak ada @cloudflare/vitest-pool-workers). Verifikasi tool baru/berubah TETAP butuh manual lewat wrangler dev + curl JSON-RPC buat itu.

npm install
npx wrangler dev

Di terminal lain, contoh untuk tool Binance native:

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "binance_get_funding_rate",
      "arguments": { "symbol": "BTCUSDT" }
    }
  }'

Kalau ini mengembalikan data funding rate + basis BTCUSDT yang valid, jalur proxy Vercel bekerja.

Audit & Hasil

Efisiensi Token

Response tool MCP masuk langsung ke context window Claude — beda dari REST API biasa di mana ukuran response relatif "gratis". Repo ini pernah punya beberapa tool yang boros token tanpa disadari; sudah diperbaiki dan diverifikasi ke worker live (2026-08-12):

Verifikasi ulang kapan saja:

npm run token-audit

Manggil worker deployed langsung, ukur ukuran skema tool, ukuran response lintas skala limit, dan "Information Density Ratio" (data vs boilerplate) buat beberapa tool representatif, plus simulasi 1 percakapan multi-turn realistis. Bukan bagian npm test/CI (hit worker live via itu) — dipakai manual pas mau cek dampak perubahan tool description/ format response terhadap konsumsi token. Estimasi token pakai heuristik chars/4 (gak ada tokenizer resmi Claude yang di-publish sebagai package), jadi angkanya approximate, berguna buat perbandingan relatif (sebelum vs sesudah perubahan), bukan angka token exact.

Keamanan

• Validasi input simbol pair. symbolSchema (dipakai semua tool yang butuh parameter symbol) dibatasi maksimal 20 karakter dan hanya menerima [A-Z0-9_]. Sebelumnya tidak ada batasan — karena simbol dipakai langsung sebagai bagian key Workers KV (threshold:${symbol}, basis_history:${symbol}), input tanpa batas panjang/karakter berisiko melebihi limit 512-byte key KV atau menyisipkan karakter (titik dua, newline) yang mengacaukan konstruksi key. Batas 20 karakter divalidasi ke data riil (simbol terpanjang di Binance Futures saat ini 17 karakter), dan regex sengaja mengizinkan underscore supaya kontrak dated/quarterly (contoh BTCUSDT_260925) tetap valid.
• Read-only terhadap akun. Tidak ada tool yang melakukan order/trading atau mengakses data akun pribadi — satu-satunya tool yang menulis state (binance_set_pair_threshold) cuma menyimpan preferensi threshold di Workers KV milik worker sendiri.
• Kredensial selalu lewat Wrangler secret, tidak pernah di-hardcode atau masuk wrangler.toml/git — lihat peringatan eksplisit di bagian Setup Proxy Vercel soal cara aman set secret.
• Repo ini di-scan manual untuk memastikan tidak ada API key, secret, atau kredensial nyata yang ter-commit — hanya placeholder/contoh (misal URL proxy whale-pearl.vercel.app di dokumentasi setup adalah nama contoh, bukan endpoint nyata).

Biaya

• Cloudflare Workers: free tier 100.000 request/hari — untuk pemakaian personal trading analysis ini jauh dari cukup.
• Vercel (proxy relay): free tier Hobby plan mencakup jutaan invocation/bulan untuk serverless function — tidak akan kena biaya untuk pemakaian personal. Perhatikan: PROXY_SECRET wajib dijaga kerahasiaannya, karena siapapun yang tahu URL + secret bisa memakai quota proxy ini atas nama kamu.

Kemungkinan besar kamu tidak akan pernah kena biaya di kedua platform untuk pemakaian personal.

Disclaimer

Project ini open source dan publik — source code, arsitektur, dan dokumentasi (termasuk framework analisis di docs/) bisa dilihat, di-clone, dan dimodifikasi siapa saja lewat repo GitHub ini. Tidak ada data akun pribadi yang disimpan atau diproses — semua tool bersifat read-only terhadap API publik Binance.

• Bukan saran finansial. Semua data dan interpretasi (funding rate, OI, order book, framework deteksi MM, dll) bersifat informational — hasil pengolahan data publik, BUKAN rekomendasi trading. Tidak ada jaminan akurasi, kelengkapan, atau ketepatan waktu data — cek Keterbatasan yang jujur perlu diketahui untuk batasan spesifik tiap tool sebelum mengambil keputusan berdasarkan data ini.
• Tanggung jawab pengguna. Siapapun yang deploy, memakai, atau memodifikasi worker ini bertanggung jawab penuh atas hasil dan konsekuensi pemakaiannya sendiri — termasuk keputusan trading yang diambil berdasarkan output tool-tool ini.
• Kepatuhan ke Binance API Terms of Use. Worker ini memanggil endpoint publik Binance (Futures & Spot). Pemakaian personal/non-komersial sejalan dengan ketentuan Binance yang berlaku umum; redistribusi ulang data secara komersial atau pemakaian skala besar sebaiknya dicek dulu terhadap Binance API Terms of Use — di luar tanggung jawab project ini.
• Lisensi: MIT. Bebas dipakai, dimodifikasi, dan didistribusikan ulang (termasuk untuk keperluan komersial), selama notice copyright & lisensi MIT tetap disertakan. Software disediakan "as is", tanpa jaminan apapun — sejalan dengan disclaimer di atas.