TypeScript SDK

Официальный пакет @hypercallxyz/sdk позволяет обращаться к REST API Hypercall из TypeScript или современного JavaScript.

SDK предоставляет:

• Типизированные клиенты для публичных, аккаунтных и подписываемых биржевых методов.
• Валидацию запросов в рантайме до их отправки.
• Хелперы EIP-712 для построения ровно того сообщения, которое подписывает кошелёк.
• Продакшн-настройки по умолчанию: https://api.hypercall.xyz и таймаут запроса 10 секунд.

Исходный код открыт: github.com/hypercall-public/hypercall-typescript-sdk.

Текущий охват

TypeScript SDK покрывает чтение через REST, отправку заранее подписанных REST-запросов на запись и хелперы для подписи. Для потоковых обновлений по ордерам, исполнениям, портфелю и рынку используйте WebSocket API напрямую.

ExchangeClient не оборачивает POST /bulk_order, PUT /bulk_order, настройку MMP и ордера на перпы. Подписывайте такие запросы по описанным структурам и вызывайте эндпоинты напрямую.

Установка

npm install @hypercallxyz/sdk

Пакет распространяется в формате ESM и экспортирует TypeScript-декларации для каждой публичной точки входа. Для продакшн-интеграций, где обновления должны быть контролируемыми, фиксируйте точную версию.

Чтение рыночных данных

InfoClient даёт типизированный доступ к рыночным данным и состоянию аккаунта. HttpTransport по умолчанию работает с продакшн-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);

Основные методы InfoClient:

Раздел	Методы
Метаданные биржи	exchangeInfo, markets, instruments, optionSummaries, orderbook
Состояние аккаунта	portfolio, orders, orderStatus, fills, settlementPayouts, authorizedAgents
Активность	trade, trades, transfers, historicalPnl, historicalTheos
Риск и идентификация	riskGrid, profile, profileTrades, referralBinding, referralCodeByOwner
RFQ и ликвидация	rfqStatus, liquidations, liquidationStatus, liquidationHistory

Параметры запроса передаются первыми. Необязательный AbortSignal передаётся последним аргументом.

const controller = new AbortController();

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

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

Настройка транспорта

Если приложение выбирает окружение через конфигурацию, передавайте URL API явно.

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

• apiUrl по умолчанию равен https://api.hypercall.xyz.
• timeout по умолчанию составляет 10 000 миллисекунд. Устанавливайте null только в том случае, если вызывающий код сам реализует политику отмены запросов.
• fetchOptions задаёт параметры fetch по умолчанию для каждого запроса. Метод и тело запроса SDK формирует сам.

Подпись и отправка операции записи

ExchangeClient принимает заранее подписанные запросы. Подключение кошелька, выбор nonce и создание подписи остаются на стороне вызывающего кода.

Хелпер подписи формирует EIP-712 domain, types, primary type и message. Передайте эти typed data в метод подписи вашей библиотеки кошелька.

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

Подписанные значения должны совпадать

Поля wallet, symbol, side, size, price, tif, route, client_id и nonce, отправляемые в API, должны в точности совпадать с соответствующими подписанными полями PlaceOrder. Передавайте price и size строками. Другое строковое представление даёт другую подпись.

Выделение nonce: Hypercall принимает nonce в диапазоне от двух суток до и одних суток после серверного времени. Используйте время эпохи в миллисекундах как начальное значение, атомарно сохраняйте последний nonce для каждого подписанта и монотонно увеличивайте его, чтобы исключить коллизии между параллельными воркерами и при перезапусках процесса.

Маршрут: тип route в SDK включает rfq_only, но API сейчас отклоняет это значение на всех эндпоинтах ордеров. Используйте book_only или best_execution.

Выбор инструмента: получайте активный инструмент через InfoClient непосредственно перед построением ордера. Не зашивайте символ опциона с конкретной датой экспирации в долгоживущую интеграцию.

Для запросов reduce-only используйте соответствующие тип и билдер:

• Размещение: PLACE_ORDER_REDUCE_ONLY_TYPES с buildPlaceOrderReduceOnlyValue.
• Замена: REPLACE_ORDER_REDUCE_ONLY_TYPES с buildReplaceOrderReduceOnlyValue.

Продакшн-домен подписи, правила nonce, авторизация агентов и все поддерживаемые сообщения записи описаны в разделе Аутентификация и подпись.

Обработка ошибок

Корневой пакет экспортирует классы ошибок 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 означает, что SDK отклонил некорректный запрос до отправки.
• HttpRequestError означает, что запрос завершился ошибкой, превысил таймаут, был прерван, вернул неуспешный статус или невалидный JSON.
• Результаты торговых операций могут содержать статус отклонения даже при успешном HTTP-ответе. Проверяйте ответ метода, а не полагайтесь только на исключения.

Рекомендации по устойчивой обработке ошибок приведены в разделе Ошибки API.

Точки импорта

Импорт	Назначение
@hypercallxyz/sdk	HttpTransport, InfoClient, ExchangeClient, классы ошибок и публичные типы
@hypercallxyz/sdk/api/info	Низкоуровневые типизированные info-методы и схемы запросов
@hypercallxyz/sdk/api/exchange	Низкоуровневые типизированные exchange-методы и схемы запросов
@hypercallxyz/sdk/signing	Карты типов EIP-712, билдеры значений и хелперы для typed data

Подробности запросов и ответов по каждому эндпоинту смотрите в справочнике REST API. История релизов и готовые к запуску примеры находятся в changelog SDK и в каталоге examples/.