SDK de TypeScript

Use el paquete oficial @hypercallxyz/sdk para llamar a la API REST de Hypercall desde TypeScript o JavaScript moderno.

El SDK ofrece:

• Clientes tipados para métodos públicos, de cuenta y de exchange firmados.
• Validación de solicitudes en tiempo de ejecución antes de enviar una solicitud.
• Helpers EIP-712 para construir el mensaje exacto que firma una wallet.
• Valores predeterminados de producción para https://api.hypercall.xyz y un timeout de solicitud de 10 segundos.

El código fuente es público en github.com/hypercall-public/hypercall-typescript-sdk.

Alcance actual

El SDK de TypeScript cubre lecturas REST, escrituras REST prefirmadas y helpers de firma. Use la API de WebSocket directamente para recibir en streaming actualizaciones de órdenes, ejecuciones, portafolio y mercado.

ExchangeClient no envuelve POST /bulk_order, PUT /bulk_order, la configuración de MMP ni las órdenes de perpetuos. Firme esas solicitudes con las estructuras documentadas y llame a los endpoints directamente.

Instalación

npm install @hypercallxyz/sdk

El paquete es ESM y exporta declaraciones de TypeScript en cada punto de entrada público. Fije una versión exacta en integraciones de producción que requieran actualizaciones controladas.

Leer datos de mercado

InfoClient ofrece acceso tipado a datos de mercado y al estado de la cuenta. HttpTransport usa la API de producción de forma predeterminada.

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

Entre los métodos más comunes de InfoClient se incluyen:

Área	Métodos
Metadatos del exchange	exchangeInfo, markets, instruments, optionSummaries, orderbook
Estado de la cuenta	portfolio, orders, orderStatus, fills, settlementPayouts, authorizedAgents
Actividad	trade, trades, transfers, historicalPnl, historicalTheos
Riesgo e identidad	riskGrid, profile, profileTrades, referralBinding, referralCodeByOwner
RFQ y liquidación	rfqStatus, liquidations, liquidationStatus, liquidationHistory

Los parámetros de la solicitud van primero. Pase un AbortSignal opcional como último argumento.

const controller = new AbortController();

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

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

Configurar el transporte

Pase una URL de API explícita cuando su aplicación seleccione el entorno mediante configuración.

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

• apiUrl tiene como valor predeterminado https://api.hypercall.xyz.
• timeout tiene como valor predeterminado 10.000 milisegundos. Establézcalo en null solo cuando el llamador implemente su propia política de cancelación.
• fetchOptions aplica opciones de fetch predeterminadas a cada solicitud. El SDK controla el método y el cuerpo de la solicitud.

Firmar y enviar una escritura

ExchangeClient acepta payloads de solicitud prefirmados. El llamador sigue siendo responsable de la conexión de la wallet, la selección del nonce y la creación de la firma.

El helper de firma genera el dominio EIP-712, los tipos, el tipo primario y el mensaje. Pase esos datos tipados al método de firma que ofrezca su librería de wallet.

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

Los valores firmados deben coincidir

Los campos wallet, symbol, side, size, price, tif, route, client_id y nonce enviados a la API deben coincidir exactamente con sus campos firmados correspondientes de PlaceOrder. Mantenga price y size como strings. Una representación de string distinta produce una firma distinta.

Asignación de nonces: Hypercall acepta nonces dentro de un rango de dos días antes y un día después del timestamp del servidor. Use el tiempo epoch en milisegundos como semilla, persista de forma atómica el último nonce por firmante e increméntelo de forma monótona para evitar colisiones entre workers concurrentes y reinicios del proceso.

Ruta: el tipo route del SDK incluye rfq_only, pero la API actualmente lo rechaza en todos los endpoints de órdenes. Use book_only o best_execution.

Selección del instrumento: obtenga un instrumento activo desde InfoClient inmediatamente antes de construir una orden. No fije en el código un símbolo de opción con fecha en una integración de larga duración.

Use el tipo y el builder reduce-only correspondientes para solicitudes reduce-only:

• Colocar: PLACE_ORDER_REDUCE_ONLY_TYPES con buildPlaceOrderReduceOnlyValue.
• Reemplazar: REPLACE_ORDER_REDUCE_ONLY_TYPES con buildReplaceOrderReduceOnlyValue.

Consulte Autenticación y firma para conocer el dominio de firma de producción, las reglas de nonce, la autorización de agentes y todos los mensajes de escritura admitidos.

Manejo de errores

El paquete raíz exporta las clases de error del 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 indica que el SDK rechazó una solicitud inválida antes de enviarla.
• HttpRequestError indica que la solicitud falló, superó el timeout, fue abortada, devolvió un estado no exitoso o devolvió JSON inválido.
• Los resultados de trading pueden reportar un estado rechazado aun dentro de una respuesta HTTP exitosa. Inspeccione la respuesta del método en lugar de depender solo de las excepciones.

Consulte Errores de la API para ver pautas estables de manejo de errores.

Puntos de importación

Importación	Uso
@hypercallxyz/sdk	HttpTransport, InfoClient, ExchangeClient, clases de error y tipos públicos
@hypercallxyz/sdk/api/info	Métodos info tipados de bajo nivel y esquemas de solicitud
@hypercallxyz/sdk/api/exchange	Métodos exchange tipados de bajo nivel y esquemas de solicitud
@hypercallxyz/sdk/signing	Mapas de tipos EIP-712, builders de valores y helpers de datos tipados

Para detalles de solicitudes y respuestas a nivel de endpoint, use la Referencia de la API REST. Para el historial de versiones y ejemplos ejecutables, use el changelog del SDK y el directorio examples/.