TypeScript SDK

Hypercall REST API'sini TypeScript veya modern JavaScript'ten çağırmak için resmi @hypercallxyz/sdk paketini kullanın.

SDK şunları sağlar:

• Herkese açık, hesap ve imzalı borsa metotları için tipli istemciler.
• Bir istek gönderilmeden önce çalışma zamanı istek doğrulaması.
• Bir cüzdan tarafından imzalanan mesajın tam olarak oluşturulması için EIP-712 yardımcıları.
• https://api.hypercall.xyz ve 10 saniyelik istek zaman aşımı için üretim varsayılanları.

Kaynak kod github.com/hypercall-public/hypercall-typescript-sdk adresinde herkese açıktır.

Mevcut kapsam

TypeScript SDK; REST okumalarını, önceden imzalanmış REST yazma işlemlerini ve imzalama yardımcılarını kapsar. Emir, işlem gerçekleşmesi (fill), portföy ve piyasa güncellemelerini akış olarak almak için doğrudan WebSocket API kullanın.

ExchangeClient; POST /bulk_order, PUT /bulk_order, MMP yapılandırması veya perp emirlerini sarmalamaz. Bunları belgelenmiş yapılarla imzalayın ve uç noktaları doğrudan çağırın.

Kurulum

npm install @hypercallxyz/sdk

Paket ESM formatındadır ve her herkese açık giriş noktasıyla birlikte TypeScript tanımlarını dışa aktarır. Kontrollü yükseltme gerektiren üretim entegrasyonlarında tam bir sürümü sabitleyin.

Piyasa Verilerini Okuma

InfoClient, piyasa verilerine ve hesap durumuna tipli erişim sağlar. HttpTransport varsayılan olarak üretim API'sini kullanır.

import { HttpTransport, InfoClient } from "@hypercallxyz/sdk";

const info = new InfoClient({
  transport: new HttpTransport(),
});

const markets = await info.markets({ include_instruments: false });
const currency = markets.data[0]?.underlying;

if (!currency) {
  throw new Error("Hypercall returned no active markets");
}

const summaries = await info.optionSummaries({ currency });

console.log(summaries.result?.[0]?.instrument_name);
console.log(summaries.result?.[0]?.mark_price);

Yaygın InfoClient metotları şunlardır:

Alan	Metotlar
Borsa meta verileri	exchangeInfo, markets, instruments, optionSummaries, orderbook
Hesap durumu	portfolio, orders, orderStatus, fills, settlementPayouts, authorizedAgents
Aktivite	trade, trades, transfers, historicalPnl, historicalTheos
Risk ve kimlik	riskGrid, profile, profileTrades, referralBinding, referralCodeByOwner
RFQ ve likidasyon	rfqStatus, liquidations, liquidationStatus, liquidationHistory

İstek parametreleri önce gelir. Son argüman olarak isteğe bağlı bir AbortSignal iletebilirsiniz.

const controller = new AbortController();

const portfolio = await info.portfolio(
  { wallet: "0xYourWalletAddress" },
  controller.signal,
);

console.log(portfolio.data?.available_balance);

Transport Yapılandırması

Uygulamanız ortamını yapılandırma üzerinden seçiyorsa açık bir API URL'si iletin.

const transport = new HttpTransport({
  apiUrl: "https://api.hypercall.xyz",
  timeout: 15_000,
  fetchOptions: {
    cache: "no-store",
  },
});

• apiUrl varsayılan olarak https://api.hypercall.xyz değerini alır.
• timeout varsayılan olarak 10.000 milisaniyedir. Bunu yalnızca çağıran taraf kendi iptal politikasını sağladığında null olarak ayarlayın.
• fetchOptions, her isteğe varsayılan fetch seçeneklerini uygular. İstek metodu ve gövdesi SDK'nın kontrolündedir.

Yazma İşlemini İmzalama ve Gönderme

ExchangeClient, önceden imzalanmış istek yüklerini kabul eder. Cüzdan bağlantısı, nonce seçimi ve imza oluşturma sorumluluğu çağıran tarafta kalır.

İmzalama yardımcısı EIP-712 alanını (domain), tipleri, birincil tipi ve mesajı üretir. Bu tipli veriyi cüzdan kütüphanenizin sağladığı imzalama metoduna iletin.

import { ExchangeClient, HttpTransport, InfoClient } from "@hypercallxyz/sdk";
import {
  buildPlaceOrderValue,
  buildTypedData,
  PLACE_ORDER_TYPES,
} from "@hypercallxyz/sdk/signing";

declare const nonceStore: {
  next(signer: string, nowMs: number): Promise<number>;
};

declare const yourWallet: {
  signTypedData(typedData: unknown): Promise<`0x${string}`>;
};

const wallet = "0xYourWalletAddress";
const transport = new HttpTransport();
const info = new InfoClient({ transport });
const exchange = new ExchangeClient({ transport });

const instruments = await info.instruments({ currency: "BTC" });
const instrument = instruments.result?.find(
  ({ is_active, orderbook }) => is_active && orderbook,
);

if (!instrument) {
  throw new Error("Hypercall returned no active BTC orderbook instrument");
}

// Back this allocator with durable, per-signer state. It should atomically
// persist and return max(nowMs, previousNonce + 1).
const nonce = await nonceStore.next(wallet, Date.now());

const order = {
  wallet,
  symbol: instrument.instrument_name,
  side: "Buy" as const,
  size: "0.1",
  price: "100",
  tif: "gtc" as const,
  route: "book_only" as const,
  clientId: "quote-123",
  nonce,
};

const typedData = buildTypedData({
  chainId: 999,
  primaryType: "PlaceOrder",
  types: PLACE_ORDER_TYPES,
  message: buildPlaceOrderValue(order),
});

// Replace this with the typed-data signing call from your wallet library.
const signature = await yourWallet.signTypedData(typedData);

const result = await exchange.placeOrder({
  wallet: order.wallet,
  symbol: order.symbol,
  side: order.side,
  size: order.size,
  price: order.price,
  tif: order.tif,
  route: order.route,
  client_id: order.clientId,
  nonce: order.nonce,
  signature,
});

console.log(result.status);

İmzalı değerler eşleşmelidir

API'ye gönderilen wallet, symbol, side, size, price, tif, route, client_id ve nonce değerleri, imzalanan PlaceOrder alanlarındaki karşılıklarıyla tam olarak eşleşmelidir. price ve size değerlerini string olarak tutun. Farklı bir string gösterimi farklı bir imza üretir.

Nonce tahsisi: Hypercall, sunucu zaman damgasından iki gün öncesine ve bir gün sonrasına kadar olan nonce değerlerini kabul eder. Başlangıç değeri olarak milisaniye cinsinden epoch zamanını kullanın, imzalayan başına son nonce değerini atomik olarak kalıcı hale getirin ve eşzamanlı çalışanlar ile süreç yeniden başlatmaları arasında çakışmaları önlemek için monoton olarak artırın.

Route: SDK'nın route tipi rfq_only değerini içerir, ancak API şu anda bunu tüm emir uç noktalarında reddeder. book_only veya best_execution kullanın.

Enstrüman seçimi: Bir emri oluşturmadan hemen önce InfoClient üzerinden aktif bir enstrüman belirleyin. Uzun ömürlü bir entegrasyona belirli bir vade tarihli opsiyon sembolünü sabit olarak kodlamayın.

Reduce-only istekler için eşleşen reduce-only tipini ve oluşturucuyu kullanın:

• Place: PLACE_ORDER_REDUCE_ONLY_TYPES ile buildPlaceOrderReduceOnlyValue.
• Replace: REPLACE_ORDER_REDUCE_ONLY_TYPES ile buildReplaceOrderReduceOnlyValue.

Üretim imzalama alanı, nonce kuralları, ajan yetkilendirmesi ve desteklenen tüm yazma mesajları için Kimlik Doğrulama ve İmzalama sayfasına bakın.

Hataları Yönetme

Kök paket, SDK hata sınıflarını dışa aktarır.

import {
  HttpRequestError,
  ValidationError,
} from "@hypercallxyz/sdk";

try {
  await info.portfolio({ wallet: "invalid-wallet" });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error("Invalid request:", error.message);
  } else if (error instanceof HttpRequestError) {
    console.error("HTTP request failed:", error.response?.status, error.message);
  } else {
    throw error;
  }
}

• ValidationError, SDK'nın geçersiz bir isteği göndermeden önce reddettiği anlamına gelir.
• HttpRequestError, isteğin başarısız olduğu, zaman aşımına uğradığı, iptal edildiği, başarılı olmayan bir durum kodu döndürdüğü veya geçersiz JSON döndürdüğü anlamına gelir.
• İşlem sonuçları, başarılı bir HTTP yanıtında da reddedilmiş bir durum bildirebilir. Yalnızca istisnalara güvenmek yerine metot yanıtını inceleyin.

Kararlı hata yönetimi rehberliği için API Hataları sayfasına bakın.

İçe Aktarma Yüzeyleri

İçe aktarma	Kullanım
@hypercallxyz/sdk	HttpTransport, InfoClient, ExchangeClient, hata sınıfları ve herkese açık tipler
@hypercallxyz/sdk/api/info	Düşük seviyeli tipli info metotları ve istek şemaları
@hypercallxyz/sdk/api/exchange	Düşük seviyeli tipli exchange metotları ve istek şemaları
@hypercallxyz/sdk/signing	EIP-712 tip haritaları, değer oluşturucular ve tipli veri yardımcıları

Uç nokta düzeyindeki istek ve yanıt ayrıntıları için REST API Referansı sayfasını kullanın. Sürüm geçmişi ve çalıştırılabilir örnekler için SDK değişiklik günlüğünü ve examples/ dizinini kullanın.