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 приймає попередньо підписані payload запитів. Підключення гаманця, вибір 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 в межах двох днів до та одного дня після серверної мітки часу. Використовуйте час epoch у мілісекундах як початкове значення, атомарно зберігайте останній nonce для кожного підписанта та монотонно збільшуйте його, щоб уникнути колізій між паралельними воркерами та після перезапуску процесів.

Маршрут: тип route у SDK містить rfq_only, але наразі API відхиляє його на всіх ендпоінтах ордерів. Використовуйте book_only або best_execution.

Вибір інструмента: Отримуйте активний інструмент через InfoClient безпосередньо перед формуванням ордера. Не прописуйте жорстко символ опціону з датою в довготривалій інтеграції.

Для запитів reduce-only використовуйте відповідний тип і білдер 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	Низькорівневі типізовані біржові методи та схеми запитів
@hypercallxyz/sdk/signing	Мапи типів EIP-712, білдери значень і допоміжні функції для typed data

Подробиці запитів і відповідей на рівні ендпоінтів дивіться в довіднику REST API. Історію релізів і робочі приклади дивіться в журналі змін SDK і каталозі examples/.