SDK TypeScript

Utilisez le package officiel @hypercallxyz/sdk pour appeler l'API REST de Hypercall depuis TypeScript ou du JavaScript moderne.

Le SDK fournit :

• Des clients typés pour les méthodes publiques, de compte et d'échange signées.
• Une validation des requêtes à l'exécution avant l'envoi d'une requête.
• Des helpers EIP-712 pour construire le message exact signé par un portefeuille.
• Des valeurs par défaut de production pour https://api.hypercall.xyz et un délai d'expiration des requêtes de 10 secondes.

Le code source est public sur github.com/hypercall-public/hypercall-typescript-sdk.

Périmètre actuel

Le SDK TypeScript couvre les lectures REST, les écritures REST pré-signées et les helpers de signature. Utilisez directement l'API WebSocket pour le streaming des mises à jour d'ordres, d'exécutions, de portefeuille et de marché.

ExchangeClient n'encapsule pas POST /bulk_order, PUT /bulk_order, la configuration MMP ni les ordres sur contrats perpétuels. Signez-les avec les structs documentées et appelez directement les endpoints.

Installation

npm install @hypercallxyz/sdk

Le package est au format ESM et exporte les déclarations TypeScript avec chaque point d'entrée public. Fixez une version exacte pour les intégrations de production qui nécessitent des mises à niveau contrôlées.

Lire les données de marché

InfoClient fournit un accès typé aux données de marché et à l'état des comptes. HttpTransport utilise l'API de production par défaut.

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

Les méthodes courantes de InfoClient incluent :

Domaine	Méthodes
Métadonnées de l'exchange	exchangeInfo, markets, instruments, optionSummaries, orderbook
État du compte	portfolio, orders, orderStatus, fills, settlementPayouts, authorizedAgents
Activité	trade, trades, transfers, historicalPnl, historicalTheos
Risque et identité	riskGrid, profile, profileTrades, referralBinding, referralCodeByOwner
RFQ et liquidation	rfqStatus, liquidations, liquidationStatus, liquidationHistory

Les paramètres de la requête viennent en premier. Passez un AbortSignal optionnel comme dernier argument.

const controller = new AbortController();

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

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

Configurer le transport

Passez une URL d'API explicite lorsque votre application sélectionne son environnement via la configuration.

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

• apiUrl vaut par défaut https://api.hypercall.xyz.
• timeout vaut par défaut 10 000 millisecondes. Ne le définissez à null que si l'appelant fournit sa propre politique d'annulation.
• fetchOptions applique des options fetch par défaut à chaque requête. Le SDK gère la méthode et le corps de la requête.

Signer et soumettre une écriture

ExchangeClient accepte des payloads de requête pré-signés. L'appelant reste responsable de la connexion du portefeuille, du choix du nonce et de la création de la signature.

Le helper de signature produit le domaine EIP-712, les types, le type principal et le message. Passez ces données typées à la méthode de signature fournie par votre bibliothèque de portefeuille.

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

Les valeurs signées doivent correspondre

Les champs wallet, symbol, side, size, price, tif, route, client_id et nonce soumis à l'API doivent correspondre exactement aux champs signés correspondants de PlaceOrder. Conservez price et size sous forme de chaînes. Une représentation de chaîne différente produit une signature différente.

Allocation du nonce : Hypercall accepte les nonces compris entre deux jours avant et un jour après l'horodatage du serveur. Utilisez le temps epoch en millisecondes comme valeur initiale, persistez atomiquement le dernier nonce par signataire et incrémentez-le de façon monotone pour éviter les collisions entre workers concurrents et lors des redémarrages de processus.

Route : le type route du SDK inclut rfq_only, mais l'API le rejette actuellement sur tous les endpoints d'ordres. Utilisez book_only ou best_execution.

Sélection de l'instrument : résolvez un instrument actif via InfoClient juste avant de construire un ordre. Ne codez pas en dur un symbole d'option daté dans une intégration de longue durée.

Utilisez le type et le builder reduce-only correspondants pour les requêtes reduce-only :

• Placement : PLACE_ORDER_REDUCE_ONLY_TYPES avec buildPlaceOrderReduceOnlyValue.
• Remplacement : REPLACE_ORDER_REDUCE_ONLY_TYPES avec buildReplaceOrderReduceOnlyValue.

Consultez Authentification et signature pour le domaine de signature de production, les règles de nonce, l'autorisation des agents et l'ensemble des messages d'écriture pris en charge.

Gérer les erreurs

Le package racine exporte les classes d'erreur du 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 signifie que le SDK a rejeté une requête invalide avant de l'envoyer.
• HttpRequestError signifie que la requête a échoué, a expiré, a été interrompue, a renvoyé un statut d'échec ou a renvoyé un JSON invalide.
• Les résultats de trading peuvent tout de même signaler un statut rejeté dans une réponse HTTP réussie. Inspectez la réponse de la méthode au lieu de vous fier uniquement aux exceptions.

Consultez Erreurs de l'API pour des recommandations stables sur la gestion des erreurs.

Points d'import

Import	Usage
@hypercallxyz/sdk	HttpTransport, InfoClient, ExchangeClient, classes d'erreur et types publics
@hypercallxyz/sdk/api/info	Méthodes info typées de bas niveau et schémas de requête
@hypercallxyz/sdk/api/exchange	Méthodes exchange typées de bas niveau et schémas de requête
@hypercallxyz/sdk/signing	Maps de types EIP-712, builders de valeurs et helpers de données typées

Pour le détail des requêtes et réponses au niveau des endpoints, utilisez la référence de l'API REST. Pour l'historique des versions et des exemples exécutables, consultez le changelog du SDK et le répertoire examples/.