API ile İşlem

Bir piyasa yapıcıyı, kotasyon sistemini veya emir yürütme servisini Hypercall ile entegre ediyorsanız bu kılavuzu kullanın.

Üretim API'si

REST temel URL'si: https://api.hypercall.xyz

WebSocket URL'si: wss://api.hypercall.xyz/ws

Testnet durumu: Hypercall daha fazla testnet HYPE edinene kadar testnet geçici olarak devre dışıdır. Hypercall size özel bir ortam sağlamadıkça yeni piyasa yapıcı entegrasyonları üretim ortamını kullanmalıdır.

İzin listesine bağlı akışlar

Gösterge niteliğindeki kotasyon sağlayıcı akışı henüz genel kullanıma açık değildir. Hypercall bunu onaylı entegrasyonlar için etkinleştirebilir, ancak olağan piyasa yapıcı başlangıç süreci REST piyasa verilerini ve kimliği doğrulanmış emir, gerçekleşme ve portföy WebSocket kanallarını kullanmalıdır.

Başlangıç Kontrol Listesi

• İşlem cüzdanı: EIP-712 tipli verilerini imzalayabilen bir EVM cüzdanı.
• Fonlama: app.hypercall.xyz üzerinden üretim ortamında USDC fonlaması.
• Erişim: Piyasa yapıcı limitlerine veya gösterge niteliğindeki kotasyon sağlayıcı akışına ihtiyacınız varsa Hypercall ile iletişime geçin.
• Ortam: Yukarıdaki üretim REST ve WebSocket URL'leri. Testnet'in kullanılabilir olduğunu varsaymayın.
• Mutabakat: Kendi müşteri emir kimliklerinizi, nonce'larınızı, emirlerinizi, gerçekleşmelerinizi ve pozisyon anlık görüntülerinizi kalıcı olarak saklayın.

Entegrasyon Yolları

TypeScript SDK

Tipli REST istemcileri, çalışma zamanı istek doğrulaması ve EIP-712 imzalama yardımcıları için resmi TypeScript paketini kurun:

npm install @hypercallxyz/sdk

Piyasa verisi okumaları, hesap sorguları, imzalı yazma işlemleri, hata yönetimi ve paket giriş noktaları için TypeScript SDK kılavuzuna bakın. TypeScript SDK şu anda REST ve imzalamayı kapsamaktadır. Akış güncellemeleri için doğrudan WebSocket API'sine bağlanın.

Rust Crate'leri

Hypercall, desteklenen entegrasyon yüzeyi için herkese açık Rust crate'lerini github.com/hypercall-public/hypercall-rust üzerinde yayımlar. Bu crate'ler crates.io'da bulunmaz. Bunları git bağımlılığı olarak ekleyin ve bir etikete veya commit'e sabitleyin.

Crate	Kullanım
hypercall-client	REST istemcisi, WebSocket istemcisi, EIP-712 imzalama yardımcıları, yerel imzalama ve AWS KMS imzalama
hypercall-sdk-types	İstemci tarafından paylaşılan herkese açık istek ve yanıt DTO'ları
hypercall-ws-protocol	Herkese açık WebSocket mesaj tipleri
hypercall-hyperliquid	Hyperliquid üzerinde de hedge yapan entegrasyonlar için isteğe bağlı Hyperliquid yardımcı crate'i
hypercall-liquidator	Standart Teminat likidasyonu için referans istemci. Olağan piyasa yapıcılığı için gerekli değildir

Mümkün olduğunda crate'leri kullanın. Bunlar güncel imzalama alanını, istek yapılarını, yönlendirme kurallarını ve elle uygulanırken kolayca hata yapılabilecek string biçimlendirme kurallarını içerir.

Ham REST ve WebSocket

Rust kullanmıyorsanız API Referansı, Kimlik Doğrulama ve İmzalama ve WebSocket API sayfalarını esas kaynak olarak kullanın.

1. Piyasaları Keşfedin

Aktif piyasaları ve enstrüman özelliklerini yükleyerek başlayın:

curl https://api.hypercall.xyz/markets
curl "https://api.hypercall.xyz/instrument-specs?currency=BTC"
curl "https://api.hypercall.xyz/options-summary?currency=BTC"

Kullanım:

• GET /markets: listelenen dayanak varlık ve vade sonu grupları için.
• GET /instrument-specs?currency=BTC: işlem yapılabilir opsiyon özellikleri için.
• GET /options-summary?currency=BTC: zincir düzeyinde en iyi alış, en iyi satış, mark ve Greek benzeri özet alanlar için.

2. İmzalamayı Kurun

Yazma işlemleri EIP-712 imzaları kullanır.

• Üretim zincir kimliği: 999
• Alan adı (domain name): Hypercall
• Alan sürümü (domain version): 1
• Doğrulayıcı kontrat: 0x0000000000000000000000000000000000000000

Piyasa yapıcılar genellikle bir ajan cüzdanı kullanmalıdır:

1. Sahip cüzdan, POST /approve-agent ile bir ajanı onaylar.
2. Ajan cüzdan, sahip cüzdan adına emirleri ve iptalleri imzalar.
3. Sahip cüzdan, portföy, fonlama ve risk kimliği olmaya devam eder.

Kesin struct ve alan adları için Kimlik Doğrulama ve İmzalama sayfasına bakın.

3. Toplu Emirlerle Kotasyon Verin

Piyasa yapıcı kotasyonları için route: "book_only" ile POST /bulk_order kullanın.

curl -X POST https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "100.0",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1791273600000,
        "signature": "0x..."
      },
      {
        "wallet": "0x...",
        "symbol": "BTC-20260131-100000-C",
        "price": "101.0",
        "size": "0.1",
        "side": "Sell",
        "tif": "gtc",
        "route": "book_only",
        "client_id": "mm-ask-1",
        "mmp_enabled": true,
        "nonce": 1791273600001,
        "signature": "0x..."
      }
    ]
  }'

Önemli kurallar:

• price ve size string'dir; hem imzalanan yükte hem de JSON gövdesinde.
• String biçimlendirmesi, imza ile JSON gövdesi arasında birebir eşleşmelidir.
• Toplu emir boyutu, istek başına 50 emirle sınırlıdır.
• Toplu emir yönlendirmesi yalnızca emir defterine yöneliktir. route, book_only olabilir veya hiç belirtilmeyebilir. route: "best_execution" toplu emirlerde reddedilir; bunun için POST /order kullanın. route: "rfq_only" bugün tüm emir uç noktalarında reddedilir.
• Nonce'lar milisaniye cinsinden zaman damgalarıdır. Sunucu zamanının iki gün öncesi ile bir gün sonrası aralığının dışındaki bir nonce reddedilir. Bkz. Nonce Yönetimi.
• İşlem retlerinin çoğu HTTP 200 döndürür ve status: "REJECTED" içerir. Her sonucu mutlaka inceleyin.

4. Kotasyonları Yenileyin

Mevcut kotasyon emirlerini iptal edip yerlerine tek bir istekte yenilerini koymak istediğinizde PUT /bulk_order kullanın.

curl -X PUT https://api.hypercall.xyz/bulk_order \
  -H "Content-Type: application/json" \
  -d '{
    "replacements": [
      {
        "wallet": "0x...",
        "order_id": 12345,
        "symbol": "BTC-20260131-100000-C",
        "price": "99.5",
        "size": "0.1",
        "side": "Buy",
        "tif": "gtc",
        "client_id": "mm-bid-1",
        "mmp_enabled": true,
        "nonce": 1791273600002,
        "signature": "0x..."
      }
    ]
  }'

Değiştirme emirleri route alanı içermez ve emir alanlarına eski orderId değerini ekleyen ReplaceOrder olarak imzalanır. Bkz. Kimlik Doğrulama ve İmzalama.

PUT /bulk_order, yeni grubu oluşturmadan önce eski grubu iptal eder. Sonuçlar, istek sırasına göre her değiştirme için ayrı ayrı döndürülür. Başarısız bir iptal, ilgili değiştirme emrinin oluşturulmasını engeller.

Gecikmeye duyarlı tekil bir değiştirme için PUT /order kullanın.

5. Güncellemelere Abone Olun

Üretim WebSocket'ine bağlanın:

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

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

Kullanım:

• order_updates: PARTIALLY_FILLED dahil emir durumu değişiklikleri için. Buradaki filled_size, emir için gerçekleşen kümülatif miktardır.
• fills: tekil gerçekleşmeler ve her gerçekleşmeye ait miktarlar için.
• portfolio: hesap durumu güncellemeleri için.
• orderbook, trades, options_chain ve index_prices: herkese açık piyasa verileri için.

Kanal formatları ve bağlantı canlılığı davranışı için WebSocket API sayfasına bakın.

6. Durumu Mutabık Kılın

WebSocket bağlantınız sağlıklı olsa bile bir mutabakat döngüsü çalıştırın.

Durum	REST yedeği	WebSocket kanalı
Emirler	GET /orders?wallet=...	order_updates
Gerçekleşmeler	GET /fills?wallet=...	fills
Portföy	GET /portfolio?wallet=...	portfolio
Piyasalar	GET /markets, GET /instrument-specs	market_updates, options_chain

Önerilen döngü:

1. Başlangıçta piyasaları yükleyin.
2. Kotasyon vermeden önce açık emirleri ve son gerçekleşmeleri yükleyin.
3. WebSocket güncellemelerine abone olun.
4. Deterministik müşteri kimlikleriyle kotasyon verin.
5. Bağlantı kopmalarından veya kaçırılan mesajlardan kurtulmak için REST'i düzenli aralıklarla sorgulayın.
6. REST ve WebSocket durumları yeniden uyuşana kadar bilinmeyen durumda kotasyonu durdurun.

7. Lansman Kapsamını Anlayın

Mainnet Alpha bilinçli olarak sınırlandırılmıştır.

• Teminat: Standart Teminat ve Portföy Teminatı canlıdır. HyperCore hesabı birleşik moda geçtiğinde herhangi bir Hesap Portföy Teminatı'na geçebilir.
• Opsiyon kısa pozisyonları: Standart Teminat ile opsiyon short pozisyonları, teminat ve seviyenizin limitlerine tabi olarak etkindir. standard_margin_shorts_enabled için GET /risk/limits?wallet=... uç noktasını kontrol edin.
• Perp'ler: Perp emirleri ayrı bir imzalama alanı ve uç nokta kullanır. Bkz. Kimlik Doğrulama ve İmzalama.
• Gösterge niteliğindeki akış: Kotasyon sağlayıcı akışları izin listesine bağlıdır ve henüz genel kullanıma açık bir entegrasyon yolu değildir.
• Likidasyon araçları: Herkese açık liquidator crate'i, olağan piyasa yapıcılığı için değil, Standart Teminat likidasyon iş akışları içindir.
• Testnet: Hypercall daha fazla testnet HYPE edinene kadar kullanılamaz.

Sık Karşılaşılan Sorunlar

İmza doğrulaması başarısız oldu

• price ve size değerlerinin JSON string'i olduğunu kontrol edin.
• İmzalanan string'lerin gönderilen string'lerle birebir eşleştiğini kontrol edin.
• Üretim için 999 zincir kimliğini kullanın.
• Her imzalı yazma işlemi için yeni bir nonce kullanın.
• İmzalayanın cüzdan sahibi veya onaylı bir ajan olduğunu doğrulayın.

Yetersiz teminat

• GET /portfolio?wallet=... uç noktasını kontrol edin.
• Teminat ekleyin veya kotasyon büyüklüğünü azaltın.
• Cüzdanınızın, kotasyon verdiğiniz strateji için gereken erişim seviyesine sahip olduğunu doğrulayın.

Satış, erişim veya karşılık nedeniyle reddedildi

• GET /risk/limits?wallet=... uç noktasını kontrol edin. Bazı seviyeler yalnızca gerçekleşmiş long envanterle karşılanan satışlara izin verir.
• Cüzdanınızın farklı bir seviyeye ihtiyacı varsa Hypercall ile iletişime geçin.

WebSocket üzerinden gerçekleşme gelmiyor

• Kimlik doğrulamalı kanallara abone olmadan önce bir Authenticate mesajı gönderin.
• Yalnızca order_updates kanalına değil, fills kanalına da abone olun.
• Yeniden bağlandıktan sonra GET /fills?wallet=... ile yedek sorgu yapın.

Sonraki Adımlar

• Kimlik doğrulama: Kimlik Doğrulama ve İmzalama
• WebSocket protokolü: WebSocket API
• Hız limitleri: Hız Limitleri
• Hatalar: Hatalar ve Ret Nedenleri
• Referans: API Referansı