WebSocket hızlı başlangıç

Tek bir WebSocket bağlantısı, anahtarınızın okuyabildiği her piyasada en fazla 200 enstrüman için canlı fiyat güncellemelerini akıtır.

Protokol konsolunda canlı deneyin →
Resmi KAP bildirimlerinin ayrı bir akışı var → KAP WS

1 — Bağlanın ve kimlik doğrulayın

Uç noktaya bağlanın, ardından auth mesajını ilk kare olarak gönderin (10 saniye içinde). live kapsamı zorunludur.

wss endpoint
wss://api.theportfoy.com/portgate/v1/ws
client → server
{"action": "auth", "api_key": "pg_live_…"}
server → client
{"type": "auth_ok", "plan": "tester"}

2 — Abone olun

Mesaj başına en fazla 100 kimlik, bağlantı başına 200 aktif, piyasaların herhangi bir karışımı. Her kimlik için anında bir anlık görüntü alırsınız (önbellekten), ardından fiyat her değiştiğinde bir güncelleme:

client → server
{"action": "subscribe", "ids": ["bist:THYAO", "us:AAPL", "fx:USDTRY"]}
server → client (ack, then a snapshot per id)
{"type": "subscribed", "ids": ["bist:THYAO", "us:AAPL", "fx:USDTRY"], "invalid": []}
server → client (per instrument, on change — see Push cadence)
{"type": "quote", "data": {
  "instrument_id": "us:AAPL", "symbol": "AAPL", "market": "us",
  "currency": "USD", "last": "314.96", "change_pct": "-0.3985",
  "as_of": "2026-07-11T00:00:01.062000Z", "data_delay_seconds": 900, ...
}}

quote.data değeri, REST Quote biçiminin bayt bayt aynısıdır — tek bir ayrıştırıcı her iki taşımaya da hizmet eder. Abonelikten çıkmak için {"action": "unsubscribe", "ids": [...]} kullanın.

Gönderim sıklığı

Fiyatlar değiştikçe gönderilir. BIST hisseleri ve endeksleri, döviz ve emtia: gecikmeli kaynaktaki her tikten yaklaşık 1 saniye sonra, yalnızca last, bid, ask, volume ya da as_of değeri değişen enstrümanlar için. Verinin kendisi hâlâ gecikmeli akıştır — BIST 15 dakika gecikmeli kalır (data_delay_seconds: 900); hızlanan yalnızca akışımızdan soketinize olan adımdır. ABD hisseleri ve kripto eskisi gibi her önbellek yenilemesinde gönderilir (ABD için yaklaşık dakikada bir; kripto, gecikme kademesine göre).

Kalp atışı: abone olunan her BIST kimliği, hiçbir şey değişmese de ve seans dışında da en az dakikada bir mesaj alır. Döviz, emtia ve endekslerde kalp atışı garantisi yoktur — değiştikçe gelirler.

Aynı kimlik için art arda iki mesaj aynı as_of'u taşıyabilir (kalp atışı); daha yeni bir fiyattan sonra daha eski bir fiyat asla gönderilmez. Enstrümanlar arası sıra hâlâ garanti değildir.

3 — Bağlantıyı canlı tutun

Her {"action": "ping"} 30 saniyede bir kez gönderin. Kenar (edge) atıl bağlantıları ~60sn sonra kapatır — sessiz izleme listeleri için ping isteğe bağlı değildir. Sunucu {"type": "pong"} ile yanıt verir.

Tam örnek

const ws = new WebSocket("wss://api.theportfoy.com/portgate/v1/ws");

ws.onopen = () => ws.send(JSON.stringify({ action: "auth", api_key: KEY }));

let pingTimer;
ws.onmessage = (ev) => {
  const msg = JSON.parse(ev.data);
  if (msg.type === "auth_ok") {
    ws.send(JSON.stringify({ action: "subscribe",
      ids: ["bist:THYAO", "us:AAPL"] }));
    pingTimer = setInterval(
      () => ws.send(JSON.stringify({ action: "ping" })), 30_000);
  }
  if (msg.type === "quote") render(msg.data);
  if (msg.type === "error") console.warn(msg.code, msg.message);
};

ws.onclose = () => clearInterval(pingTimer); // reconnect with backoff

Hatalar ve kapanış kodları

AlanTürNotlar
4400closeProtokol ihlali (3 hatalı mesaj, aşırı büyük kare, kimlik doğrulama olmayan ilk mesaj)
4401closeKimlik doğrulama başarısız / zaman aşımı (10sn içinde kimlik doğrulama yok)
4403closeAnahtarda live kapsamı yok
error{code:"subscription_limit"}message200 aktifi aşardı — abonelik tamamen reddedilir, bağlantı açık kalır
error{code:"bad_message"}messageBozuk kare / bilinmeyen action — kimlik doğrulamadan sonra 3 ihlal → kapanış 4400
subscribed.invalidfieldBir abonelikteki bilinmeyen kimlikler burada geri döner — geçerli olanlar yine de uygulanır

Herhangi bir kapanışta üstel geri çekilmeyle yeniden bağlanın ve kimlik doğrulama + abonelikleri yeniden gönderin; abonelikteki anlık görüntüler sayesinde anlamlı hiçbir şeyi kaçırmazsınız.

İyi uygulamalar ve ipuçları

  • Üstel geri çekilmeyle yeniden bağlanın (sıkı döngü değil), ardından yeniden kimlik doğrulayıp aboneliklerinizi yeniden gönderin. Her an kapanış olabilir — dağıtımlar 1001 ile kapatır.
  • Yaklaşık 30 sn'de bir ping gönderin. Kenar (edge) ~60 sn sessizlikten sonra atıl bağlantıyı kapatır; seans dışında (ve sakin döviz, emtia ya da endeks listelerinde) gönderimler bundan daha seyrek olabilir — ping isteğe bağlı değildir.
  • Abonelik, önce en güncel önbellek kotasyonunu anında gönderir, sonra farkları (delta). Sokette geçmiş tekrarı (replay) yoktur — yeniden bağlanınca yeniden abone olur ve anlık görüntüden senkronize olursunuz.
  • Teslimat en fazla bir kez (at-most-once) ve enstrümanlar arası sıra garantisi yoktur. Fiyatlar değiştikçe gönderilir; BIST kimlikleri değişmese de dakikada bir kalp atışı alır, böylece BIST için akış aynı zamanda bir tazelik sinyali görevi görür.
  • Abonelikleri toplu gönderin: mesaj başına ≤100 kimlik, bağlantı başına 200 aktif. Sınır aşılırsa abonelik tamamen reddedilir (kısmi değil) — büyük listeleri parçalayın.
  • Her kotasyon as_of ve data_delay_seconds taşır: BIST, döviz, emtia ve endekslerde 900 (15 dk gecikmeli), ABD hisselerinde 60 (~1 dk), kriptoda 300 (~5 dk). Akış REST ile aynı tazeliği taşır, onu artırmaz. 'Canlı', istemci bayrağı değil bir lisanslama kararıdır. 'live' kapsamı, gecikmesiz veri değil akış erişimi demektir.
  • quote.data, REST Quote biçiminin bayt bayt aynısıdır — her iki taşıma için tek bir model/ayrıştırıcı kullanın.
as_of her zaman UTC'dir — Zaman damgaları soketde ISO-8601 UTC'dir. Görüntülemeden önce piyasa saat dilimine çevirin (İstanbul UTC+3'tür) — aksi hâlde 15:19:01Z, yerel işlem saati 18:19:01'e göre '3 saat kaymış' görünür. Bu bir görüntüleme hatasıdır, veri eski değildir.