TypeScript SDK

Verwenden Sie das offizielle Paket @hypercallxyz/sdk, um die Hypercall REST API aus TypeScript oder modernem JavaScript aufzurufen.

Das SDK bietet:

• Typisierte Clients für öffentliche, kontobezogene und signierte Exchange-Methoden.
• Request-Validierung zur Laufzeit, bevor eine Anfrage gesendet wird.
• EIP-712-Hilfsfunktionen zur Erstellung der exakten Nachricht, die von einer Wallet signiert wird.
• Produktions-Standardwerte für https://api.hypercall.xyz und ein Request-Timeout von 10 Sekunden.

Der Quellcode ist öffentlich unter github.com/hypercall-public/hypercall-typescript-sdk verfügbar.

Aktueller Umfang

Das TypeScript SDK deckt REST-Lesezugriffe, vorab signierte REST-Schreibvorgänge und Signatur-Hilfsfunktionen ab. Verwenden Sie die WebSocket API direkt für Streaming-Updates zu Orders, Fills, Portfolio und Märkten.

ExchangeClient kapselt weder POST /bulk_order, PUT /bulk_order, die MMP-Konfiguration noch Perp-Orders. Signieren Sie diese mit den dokumentierten Structs und rufen Sie die Endpunkte direkt auf.

Installation

npm install @hypercallxyz/sdk

Das Paket ist ESM und exportiert TypeScript-Deklarationen mit jedem öffentlichen Einstiegspunkt. Pinnen Sie für Produktionsintegrationen, die kontrollierte Upgrades benötigen, eine exakte Version.

Marktdaten lesen

InfoClient bietet typisierten Zugriff auf Marktdaten und Kontostatus. HttpTransport verwendet standardmäßig die Produktions-API.

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);

Häufig verwendete InfoClient-Methoden sind:

Bereich	Methoden
Exchange-Metadaten	exchangeInfo, markets, instruments, optionSummaries, orderbook
Kontostatus	portfolio, orders, orderStatus, fills, settlementPayouts, authorizedAgents
Aktivität	trade, trades, transfers, historicalPnl, historicalTheos
Risiko und Identität	riskGrid, profile, profileTrades, referralBinding, referralCodeByOwner
RFQ und Liquidation	rfqStatus, liquidations, liquidationStatus, liquidationHistory

Request-Parameter stehen an erster Stelle. Übergeben Sie optional ein AbortSignal als letztes Argument.

const controller = new AbortController();

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

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

Transport konfigurieren

Übergeben Sie eine explizite API-URL, wenn Ihre Anwendung ihre Umgebung über die Konfiguration auswählt.

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

• apiUrl ist standardmäßig https://api.hypercall.xyz.
• timeout beträgt standardmäßig 10.000 Millisekunden. Setzen Sie den Wert nur dann auf null, wenn der Aufrufer eine eigene Abbruchstrategie bereitstellt.
• fetchOptions wendet Standard-Fetch-Optionen auf jede Anfrage an. Methode und Body der Anfrage werden vom SDK festgelegt.

Einen Schreibvorgang signieren und übermitteln

ExchangeClient akzeptiert vorab signierte Request-Payloads. Der Aufrufer bleibt für die Wallet-Verbindung, die Nonce-Auswahl und die Erstellung der Signatur verantwortlich.

Die Signatur-Hilfsfunktion erzeugt EIP-712-Domain, Typen, Primärtyp und Nachricht. Übergeben Sie diese Typed Data an die Signaturmethode Ihrer Wallet-Bibliothek.

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);

Signierte Werte müssen übereinstimmen

Die an die API übermittelten Werte wallet, symbol, side, size, price, tif, route, client_id und nonce müssen exakt mit den entsprechenden signierten PlaceOrder-Feldern übereinstimmen. Behalten Sie price und size als Strings bei. Eine abweichende String-Darstellung erzeugt eine andere Signatur.

Nonce-Vergabe: Hypercall akzeptiert Nonces innerhalb von zwei Tagen vor und einem Tag nach dem Server-Zeitstempel. Verwenden Sie die Epoch-Zeit in Millisekunden als Ausgangswert, speichern Sie die letzte Nonce pro Signer atomar und erhöhen Sie sie monoton, um Kollisionen zwischen parallelen Workern und über Prozessneustarts hinweg zu vermeiden.

Route: Der route-Typ des SDK enthält rfq_only, die API lehnt diesen Wert derzeit jedoch an jedem Order-Endpunkt ab. Verwenden Sie book_only oder best_execution.

Instrumentauswahl: Ermitteln Sie ein aktives Instrument über InfoClient unmittelbar vor der Erstellung einer Order. Codieren Sie kein datiertes Optionssymbol fest in eine langlebige Integration.

Verwenden Sie für Reduce-Only-Anfragen den passenden Reduce-Only-Typ und Builder:

• Platzieren: PLACE_ORDER_REDUCE_ONLY_TYPES mit buildPlaceOrderReduceOnlyValue.
• Ersetzen: REPLACE_ORDER_REDUCE_ONLY_TYPES mit buildReplaceOrderReduceOnlyValue.

Unter Authentifizierung & Signierung finden Sie die Produktions-Signaturdomain, die Nonce-Regeln, die Agent-Autorisierung und alle unterstützten Schreibnachrichten.

Fehlerbehandlung

Das Root-Paket exportiert die Fehlerklassen des SDK.

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 bedeutet, dass das SDK eine ungültige Anfrage vor dem Senden abgelehnt hat.
• HttpRequestError bedeutet, dass die Anfrage fehlgeschlagen ist, eine Zeitüberschreitung hatte, abgebrochen wurde, einen Fehlerstatus zurückgegeben hat oder ungültiges JSON geliefert hat.
• Handelsergebnisse können auch in einer erfolgreichen HTTP-Antwort einen abgelehnten Status melden. Prüfen Sie die Antwort der Methode, anstatt sich ausschließlich auf Exceptions zu verlassen.

Unter API-Fehler finden Sie Hinweise zur stabilen Fehlerbehandlung.

Import-Pfade

Import	Verwendung
@hypercallxyz/sdk	HttpTransport, InfoClient, ExchangeClient, Fehlerklassen und öffentliche Typen
@hypercallxyz/sdk/api/info	Low-Level-typisierte Info-Methoden und Request-Schemas
@hypercallxyz/sdk/api/exchange	Low-Level-typisierte Exchange-Methoden und Request-Schemas
@hypercallxyz/sdk/signing	EIP-712-Type-Maps, Value-Builder und Typed-Data-Hilfsfunktionen

Details zu Requests und Responses auf Endpunktebene finden Sie in der REST-API-Referenz. Versionshistorie und ausführbare Beispiele finden Sie im Changelog des SDK und im Verzeichnis examples/.