WebSocket API

Hypercall opsiyon işlemleri için gerçek zamanlı veri akışı.

Etkileşimli Referans

Canlı örnekler ve şema ayrıntılarıyla daha iyi bir tarama deneyimi için Etkileşimli WebSocket API Referansı sayfasına göz atın.

Makine Tarafından Okunabilir Spesifikasyon

Programatik kullanım için AsyncAPI spesifikasyonunu indirin.

Bağlantı

wss://HOST/ws adresine bağlanın:

Uç noktalar:

• Üretim: wss://api.hypercall.xyz/ws
• Yerel: ws://localhost:3000/ws

Testnet durumu

Hypercall daha fazla testnet HYPE edinene kadar testnet geçici olarak devre dışıdır.

Cüzdan Tanımlama

Kimliği doğrulanmış kanallarda (emirler, gerçekleşmeler, portföy) veri almak için, bağlandıktan sonra bir Authenticate mesajı göndererek cüzdanınızı tanımlayın:

{"type": "Authenticate", "wallet": "0x1234..."}

Sunucu bir onay ile yanıt verir:

{"type": "Authenticated", "wallet": "0x1234..."}

Authenticated yanıtını aldıktan sonra, kimliği doğrulanmış kanallara abone olabilirsiniz. Cüzdan adresi geçersizse, sunucu bir Error mesajıyla yanıt verir ve bağlantı açık kalır.

Kullanımdan Kaldırıldı: Sorgu Parametresiyle Kimlik Doğrulama

?wallet= sorgu parametresi geriye dönük uyumluluk için hâlâ desteklenmektedir, ancak kullanımdan kaldırılmıştır ve gelecekteki bir sürümde kaldırılacaktır. Yukarıdaki mesaj tabanlı yaklaşımı tercih edin.

Bağlantı Canlılığı

Sunucu bir WebSocket kalp atışı (heartbeat) uygular:

• Her 20 saniyede bir Ping kontrol çerçevesi gönderir
• 60 saniye içinde eşleşen bir Pong bekler
• İstemci yanıt vermeyi bırakırsa bağlantıyı 1008 kapanış koduyla ve pong timeout nedeniyle kapatır

Tarayıcı WebSocket uygulamaları ping/pong işlemini otomatik olarak yönetir. tungstenite ve tokio-tungstenite dahil birçok Rust websocket kütüphanesi de kontrol çerçevesi ping/pong işlemini sizin için yönetir. Manuel Pong işleme eklemeden önce istemci kütüphanenizin belgelerine bakın. Özel veya ham soket uygulamaları Ping çerçevelerine Pong ile yanıt vermelidir.

Yavaş Tüketici Kurtarma

Sunucu, yapılandırılmış mesaj, kodlanmış bayt, kuyruk yaşı veya soket yazma güvenlik tavanı içinde giden verileri boşaltamayan bir /ws bağlantısını kapatır. Bağlantı hâlâ bir kapanış çerçevesi kabul edebiliyorken, sunucu 1008 kodunu ve kompakt bir JSON nedenini kullanır:

{"error":"slow_consumer","class":"ordered_public","cause":"message_age","recovery":"snapshot_resubscribe"}

Neden alanları şunlardır:

Alan	Anlamı
class	Çerçevesi güvenlik sınırını aşan teslimat sınıfı.
cause	message_limit, byte_limit, message_age veya write_timeout.
recovery	resubscribe, snapshot_resubscribe, portfolio_refetch veya rest_reconcile gibi gereken sonraki eylem.

Herhangi bir bağlantı kesilmesinden sonra, yeniden bağlanın, gerektiğinde cüzdanı yeniden tanımlayın, yeniden abone olun ve yeni olayları işlemeden önce mevcut durumu mutabık kılın. Sıralı genel kanallar yeni bir anlık görüntü (snapshot) gerektirir. Özel olay kanalları, imleç yeniden oynatma (cursor replay) henüz kullanılamadığından, yetkili REST yüzeyi aracılığıyla mutabakat gerektirir. Tamamen takılmış bir bağlantı, kapanış nedenini okuyamadan sonlanabilir; bu nedenle istemciler temiz olmayan bir kapanış için de bu kurtarma akışını kullanmalıdır.

Yüksek hızlı genel piyasa verileri ile kimliği doğrulanmış komutlar veya özel akışlar için ayrı bağlantılar kullanın. Teslimat sınıfları metrikleri ve kurtarma davranışını seçer, ancak bir bağlantıdaki çerçeveler yine de tek bir sıralı soket yazma yolunu paylaşır. Takılmış bir genel yazma işlemi, bu nedenle, yazma son tarihi bağlantıyı kapatana kadar aynı bağlantıdaki sonraki özel çerçeveleri geciktirebilir.

Kanallara Abone Olma

Abone olmak için bir JSON mesajı gönderin:

{"type": "Subscribe", "channel": "orderbook"}

Aboneliği iptal etmek için:

{"type": "Unsubscribe", "channel": "orderbook"}

Bir onay alacaksınız:

{"type": "Subscribed", "channel": "orderbook"}

Sembol Filtreleme

order_updates ve fills kanalları isteğe bağlı bir symbols filtresini destekler. Sağlandığında, sunucu yalnızca dayanak varlığı belirtilen sembollerden biriyle eşleşen mesajları gönderir.

{"type": "Subscribe", "channel": "order_updates", "symbols": ["BTC"]}

Hem yalın dayanak varlıklar ("BTC") hem de tam enstrüman adları ("BTC-20260131-100000-C") kabul edilir. Daha fazla sembol eklemek için başka bir Subscribe gönderin. Belirli sembolleri kaldırmak için:

{"type": "Unsubscribe", "channel": "order_updates", "symbols": ["BTC"]}

Herhangi bir symbols belirtilmediğinde, cüzdanınıza ait tüm güncellemeler iletilir.

Opsiyon Zinciri Filtreleme

options_chain kanalı; dayanak varlık sembollerine, vade sonu tarihine ve opsiyon türüne göre filtrelemeyi destekler:

{
  "type": "Subscribe",
  "channel": "options_chain",
  "symbols": ["BTC-20260131-100000-C"],
  "expiry": "2026-01-31",
  "option_type": "call"
}

Filtre	Değerler	Varsayılan
symbols	Tam enstrüman sembolleri dizisi (ör. ["BTC-20260131-100000-C"])	Tüm enstrümanlar
expiry	"YYYY-MM-DD" tarih dizesi	Tüm vadeler
option_type	"call", "put" veya her ikisi için atlayın	Her ikisi

Kullanılabilir Kanallar

Kanal	Kimlik Doğrulama Gerekli	Açıklama
orderbook	Hayır	Tüm semboller için L2 emir defteri güncellemeleri
trades	Hayır	Genel işlem akışı
market_updates	Hayır	Piyasa listeleme değişiklikleri (oluşturuldu/silindi/vadesi doldu)
options_chain	Hayır	Artımlı opsiyon zinciri güncellemeleri (sembol, vade sonu, option_type ile filtrelenebilir)
index_prices	Hayır	Tüm dayanak varlıklar için gerçek zamanlı spot/endeks fiyatları
indicative_market_data	Hayır	İzin listesindeki teklif sağlayıcı akışı. Henüz genel kullanıma açık değil
order_updates	Evet	Emir durumu değişiklikleriniz (sembole göre filtrelenebilir)
fills	Evet	İşlem gerçekleşmeleriniz (sembole göre filtrelenebilir)
portfolio	Evet	Pozisyon ve bakiye güncellemeleriniz
liquidation	Evet	Likidasyon durumu değişiklikleriniz
competition	Evet	Yarışma K/Z özetiniz, sıralamanız ve nihai istatistikleriniz
competition_engagement	Evet	Sıralama değişiklikleri, bir sonraki sıraya olan fark ve nihai sıralamalar
rfq	Evet	RFQ teklifleri, durum güncellemeleri ve gerçekleşme bildirimleri

Mesaj Türleri

Emir Ver (Kimlik Doğrulamalı)

WebSocket komut yolu üzerinden bir emir verin.

{
  "type": "PlaceOrder",
  "wallet": "0x1234...",
  "symbol": "BTC-20260131-100000-C",
  "side": "Buy",
  "size": "1",
  "price": "100",
  "tif": "gtc",
  "route": "book_only",
  "client_id": "my-order-1",
  "nonce": 1000,
  "signature": "0x..."
}

Alan	Tür	Açıklama
wallet	string	Emrin sahibi olan cüzdan adresi
symbol	string	Opsiyon sembolü
side	string	"Buy" veya "Sell"
size	string	İmzalanan değerle tam olarak eşleşen kontrat büyüklüğü
price	string	İmzalanan değerle tam olarak eşleşen limit fiyatı
tif	string	İsteğe bağlı geçerlilik süresi (time-in-force), varsayılan "gtc"
route	string	İsteğe bağlı rota. Rota bilinçli WebSocket emirleri için "book_only" kullanın. Atlanan rota en az 4 Temmuz 2026'ya kadar kabul edilmeye devam eder.
client_id	string	İsteğe bağlı istemci emir kimliği
nonce	integer	Benzersiz imzalama nonce'u
signature	string	EIP-712 PlaceOrder imzası

WebSocket PlaceOrder şu anda doğrudan emir defterine yönlendirilir. route="best_execution" ve route="rfq_only", bu yol henüz RPI/RFQ yönlendirmesi çalıştırmadığından WebSocket'te reddedilir. best_execution için POST /order kullanın.

Emir Defteri Güncellemesi

Bir sembol için L2 emir defteri anlık görüntüsü/güncellemesi.

{
  "type": "OrderbookUpdate",
  "symbol": "BTC-20260131-100000-C",
  "bids": [["95000.5", "10.5"], ["94999.0", "25.0"]],
  "asks": [["95001.0", "8.0"], ["95002.5", "15.0"]],
  "timestamp": 1737331200000
}

Alan	Tür	Açıklama
symbol	string	Opsiyon sembolü
bids	array	[fiyat, büyüklük] tuple'ları olarak alış seviyeleri, büyüklük insan tarafından okunabilir kontrat cinsindendir
asks	array	[fiyat, büyüklük] tuple'ları olarak satış seviyeleri, büyüklük insan tarafından okunabilir kontrat cinsindendir
timestamp	integer	Unix zaman damgası (milisaniye)

İşlem

Genel işlem olayı.

{
  "type": "Trade",
  "symbol": "BTC-20260131-100000-C",
  "price": "0.0523",
  "size": "5.0",
  "side": "buy",
  "timestamp": 1737331200000
}

Alan	Tür	Açıklama
symbol	string	Opsiyon sembolü
price	string	USD cinsinden işlem fiyatı
size	string	Kontrat cinsinden işlem büyüklüğü
side	string	Agresör tarafı (buy veya sell)
timestamp	integer	Unix zaman damgası (milisaniye)

Gerçekleşme (Kimlik Doğrulamalı)

İşlem gerçekleşme bildiriminiz.

{
  "type": "Fill",
  "order_id": 12345,
  "fill_id": 67890,
  "symbol": "BTC-20260131-100000-C",
  "side": "buy",
  "price": "0.0523",
  "size": "5.0",
  "timestamp": 1737331200000,
  "wallet_address": "0x1234...abcd",
  "fee": "0",
  "trade_id": 99999,
  "is_taker": true
}

Alan	Tür	Açıklama
order_id	integer	Emir kimliğiniz
fill_id	integer	Gerçekleşme (fill) kimliği
symbol	string	Opsiyon sembolü
side	string	İşlem yönü (buy veya sell)
price	string	USD cinsinden gerçekleşme fiyatı
size	string	Kontrat cinsinden gerçekleşme büyüklüğü
timestamp	integer	Unix zaman damgası (milisaniye)
wallet_address	string	Cüzdan adresiniz
fee	string	Alınan işlem ücreti. Lansman platformu ücretleri devre dışıyken 0 döner
trade_id	integer	Benzersiz işlem kimliği
is_taker	boolean	Taker olup olmadığınız
builder_code_address	string?	Builder code cüzdanı (varsa)
builder_code_fee	string?	Builder code ücreti. Lansman platformu ücretleri devre dışıyken null döner

Portföy Güncellemesi (Kimlik Doğrulamalı)

Pozisyonlar, bakiyeler, teminat ve Greeks için portföy akışı güncellemesi.

Greeks güncelleme örneği:

{
  "type": "PortfolioUpdate",
  "timestamp": 1737331200000,
  "per_leg": [
    {
      "symbol": "BTC-20260131-100000-C",
      "quantity": "2.0",
      "delta": 0.91,
      "gamma": 0.003,
      "theta": -0.12,
      "vega": 0.44,
      "iv": 0.63
    }
  ],
  "aggregate": {
    "delta": 0.91,
    "gamma": 0.003,
    "theta": -0.12,
    "vega": 0.44,
    "iv": 0.63
  }
}

Boş portföyler için Greeks güncellemeleri şunları kullanır:

• per_leg: []
• aggregate: null

Yarışma K/Z Özeti (Kimlik Doğrulamalı)

Başlık/altbilgi K/Z gösterimi için yarışma akışı güncellemesi.

{
  "type": "CompetitionPnlSummary",
  "wallet_address": "0x1234...abcd",
  "lifetime_realized_pnl": "1250.50",
  "active_competition": {
    "competition_id": 7,
    "competition_name": "Spring Sprint",
    "competition_state": "active",
    "rank": 12,
    "pnl": "420.25",
    "volume": "25000",
    "efficiency": "0.01681",
    "medal": null
  },
  "timestamp": 1737331200000
}

Aktif bir yarışma olmadığında active_competition değeri null olur.

Emir Güncellemesi (Kimlik Doğrulamalı)

Emir durumu değişikliği bildirimi.

{
  "type": "OrderUpdate",
  "order_id": 12345,
  "client_order_id": "my-order-1",
  "status": "filled",
  "filled_size": "10.0",
  "remaining_size": "0",
  "avg_fill_price": "0.0523"
}

Piyasa Güncellemesi

Piyasa listeleme değişiklikleri.

Piyasa Oluşturuldu:

{
  "type": "MarketUpdate",
  "action": "Created",
  "symbol": "BTC-20260131-100000-C",
  "strike": "100000",
  "is_call": true,
  "underlying": "BTC",
  "expiry": 1738281600,
  "timestamp": 1737331200000
}

Piyasa Vade Sonuna Erdi:

{
  "type": "MarketUpdate",
  "action": "Expired",
  "symbol": "BTC-20260131-100000-C",
  "strike": "100000",
  "is_call": true,
  "underlying": "BTC",
  "expiry": 1738281600,
  "timestamp": 1738281600000
}

Pozisyon Vade Sonuna Erdi (Kimlik Doğrulamalı)

Pozisyonunuz vade sonunda uzlaştığında gönderilen bildirim.

{
  "type": "PositionExpired",
  "wallet_address": "0x1234...abcd",
  "symbol": "BTC-20260131-100000-C",
  "position_size": "10.0",
  "settlement_price": "105000",
  "settlement_value": "500.0",
  "timestamp": 1738281600000
}

Likidasyon Durumu Değişikliği (Kimlik Doğrulamalı)

Hesabınızın likidasyon durumu değişikliği.

{
  "type": "LiquidationStateChange",
  "wallet_address": "0x1234...abcd",
  "previous_state": "Normal",
  "new_state": "Warning",
  "equity": "10000.0",
  "mm_required": "9500.0",
  "shortfall": "0",
  "auction_id": null,
  "timestamp": 1737331200000
}

Durum	Açıklama
Normal	Hesap sağlıklı
Warning	Teminat tamamlama çağrısına yaklaşıyor
Liquidating	Likidasyon açık artırması aktif

Endeks Fiyatı Güncellemesi

Tüm dayanak varlıklar için toplu spot/endeks fiyatları.

{
  "type": "IndexPriceUpdate",
  "prices": [
    {"underlying": "BTC", "price": "97250.50"},
    {"underlying": "ETH", "price": "3200.00"},
    {"underlying": "HYPE", "price": "28.50"}
  ],
  "timestamp": 1737331200000
}

Alan	Tür	Açıklama
prices	array	Takip edilen her dayanak varlık için {underlying, price} girişlerinden oluşan dizi
prices[].underlying	string	Dayanak varlık sembolü (örn. "BTC", "ETH")
prices[].price	string	USD cinsinden güncel spot/endeks fiyatı
timestamp	integer	Unix zaman damgası (milisaniye)

Gösterge Niteliğinde Piyasa Verisi

Kayıtlı kotasyon sağlayıcılarından toplanan en iyi alış/satış ile allowlist'e alınmış kotasyon sağlayıcı akışı. Bu kanal henüz genel kullanıma açık değildir. Hypercall, entegrasyonunuz için kotasyon sağlayıcı akışını etkinleştirmedikçe REST piyasa verisini ve kimlik doğrulamalı emir/gerçekleşme/portföy kanallarını kullanın.

{
  "type": "IndicativeMarketData",
  "instrument": "BTC-20260131-100000-C",
  "best_bid": "0.0520",
  "best_ask": "0.0530",
  "indicative_bid_size": "50.0",
  "indicative_ask_size": "25.0",
  "num_providers": 3,
  "timestamp": 1737331200000
}

Alan	Tür	Açıklama
instrument	string	Opsiyon sembolü
best_bid	string	İsteğe bağlı en iyi toplu alış fiyatı
best_ask	string	İsteğe bağlı en iyi toplu satış fiyatı
bid_iv	number	En iyi alışın isteğe bağlı zımni oynaklığı
ask_iv	number	En iyi satışın isteğe bağlı zımni oynaklığı
indicative_bid_size	string	Sağlayıcılar genelinde isteğe bağlı toplam alış büyüklüğü
indicative_ask_size	string	Sağlayıcılar genelinde isteğe bağlı toplam satış büyüklüğü
num_providers	integer	Aktif kotasyon sağlayıcı sayısı
timestamp	integer	Unix zaman damgası (milisaniye)

Yarışma Sıralaması Değişikliği (Kimlik Doğrulamalı)

Aktif bir yarışmadaki sıralamanız değiştiğinde gönderilen bildirim.

{
  "type": "CompetitionRankChange",
  "wallet_address": "0x1234...abcd",
  "competition_id": 7,
  "from_rank": 15,
  "to_rank": 12,
  "delta_places": 3,
  "pnl": "420.25",
  "timestamp": 1737331200000
}

Yarışma Fark Güncellemesi (Kimlik Doğrulamalı)

Sizin üstünüzdeki bir sonraki sıraya olan mesafe.

{
  "type": "CompetitionGapUpdate",
  "wallet_address": "0x1234...abcd",
  "competition_id": 7,
  "rank": 12,
  "next_rank": 11,
  "gap_metric_value": "50.00",
  "timestamp": 1737331200000
}

Yarışma Nihai Sıralaması (Kimlik Doğrulamalı)

Bir yarışma sona erdiğinde nihai sonuçlarınızla birlikte gönderilir.

{
  "type": "CompetitionFinalStanding",
  "wallet_address": "0x1234...abcd",
  "competition_id": 7,
  "rank": 12,
  "pnl": "420.25",
  "volume": "25000",
  "efficiency": "0.01681",
  "medal": null,
  "timestamp": 1737331200000
}

RFQ Kotasyonları (Kimlik Doğrulamalı)

RFQ gönderiminize yanıt olarak alınan kotasyonlar.

{
  "type": "RfqQuotes",
  "rfq_id": "550e8400-e29b-41d4-a716-446655440000",
  "quotes": [
    {
      "quote_id": "660e8400-e29b-41d4-a716-446655440001",
      "net_premium": "52.30",
      "expires_at": 1737331225000
    }
  ],
  "status": "quoted",
  "taker_wallet": "0x1234...abcd"
}

RFQ Durum Güncellemesi (Kimlik Doğrulamalı)

Gönderdiğiniz bir RFQ için durum değişikliği.

{
  "type": "RfqStatusUpdate",
  "rfq_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "executed",
  "taker_wallet": "0x1234...abcd"
}

Hata

Sunucu hata mesajı.

{
  "type": "Error",
  "message": "Invalid channel: foobar"
}

Kimlik Doğrulama

Kimlik doğrulamalı kanallar, bağlandıktan sonra bir cüzdan tanımlama mesajı gerektirir:

{"type": "Authenticate", "wallet": "0x1234567890abcdef..."}

Kimlik doğrulamalı kanallardaki mesajlar, yalnızca kendi cüzdanınıza ait verileri gösterecek şekilde filtrelenir. WebSocket bağlantıları için imza gerekmez.

Örnek: Python İstemcisi

import asyncio
import websockets
import json

async def main():
    uri = "wss://api.hypercall.xyz/ws"

    async with websockets.connect(uri) as ws:
        # Identify the wallet before subscribing to authenticated channels.
        await ws.send(json.dumps({
            "type": "Authenticate",
            "wallet": "0xYourWallet"
        }))

        # Subscribe to orderbook
        await ws.send(json.dumps({
            "type": "Subscribe",
            "channel": "orderbook"
        }))

        # Subscribe to fills for BTC only
        await ws.send(json.dumps({
            "type": "Subscribe",
            "channel": "fills",
            "symbols": ["BTC"]
        }))

        # Listen for messages
        async for message in ws:
            data = json.loads(message)
            print(f"Received: {data['type']}")

asyncio.run(main())

Örnek: TypeScript İstemcisi

const ws = new WebSocket("wss://api.hypercall.xyz/ws");

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "Authenticate", wallet: "0xYourWallet" }));

  // Subscribe to channels
  ws.send(JSON.stringify({ type: "Subscribe", channel: "orderbook" }));

  // Subscribe to order updates filtered to BTC
  ws.send(JSON.stringify({
    type: "Subscribe",
    channel: "order_updates",
    symbols: ["BTC"],
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(`Received: ${msg.type}`);

  if (msg.type === "OrderbookUpdate") {
    console.log(`${msg.symbol}: ${msg.bids.length} bids, ${msg.asks.length} asks`);
  }
};