TypeScript SDK

Sử dụng gói chính thức @hypercallxyz/sdk để gọi Hypercall REST API từ TypeScript hoặc JavaScript hiện đại.

SDK cung cấp:

• Client có kiểu cho các phương thức công khai, tài khoản và giao dịch đã ký.
• Xác thực request tại runtime trước khi request được gửi đi.
• Hàm hỗ trợ EIP-712 để xây dựng chính xác thông điệp được ví ký.
• Mặc định cho môi trường production với https://api.hypercall.xyz và thời gian chờ request 10 giây.

Mã nguồn được công khai tại github.com/hypercall-public/hypercall-typescript-sdk.

Phạm vi hiện tại

TypeScript SDK hỗ trợ các lệnh đọc REST, các lệnh ghi REST đã ký sẵn và các hàm hỗ trợ ký. Hãy sử dụng trực tiếp WebSocket API để nhận luồng cập nhật về lệnh, khớp lệnh, danh mục và thị trường.

ExchangeClient không bao gồm POST /bulk_order, PUT /bulk_order, cấu hình MMP hoặc lệnh perp. Hãy ký các yêu cầu đó bằng các struct được tài liệu hóa và gọi trực tiếp các endpoint.

Cài đặt

npm install @hypercallxyz/sdk

Gói này là ESM và xuất các khai báo TypeScript cho mọi entry point công khai. Hãy cố định một phiên bản chính xác cho các tích hợp production cần kiểm soát việc nâng cấp.

Đọc dữ liệu thị trường

InfoClient cung cấp quyền truy cập có kiểu vào dữ liệu thị trường và trạng thái tài khoản. HttpTransport mặc định sử dụng API production.

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

Các phương thức InfoClient thường dùng bao gồm:

Nhóm	Phương thức
Metadata sàn giao dịch	exchangeInfo, markets, instruments, optionSummaries, orderbook
Trạng thái tài khoản	portfolio, orders, orderStatus, fills, settlementPayouts, authorizedAgents
Hoạt động	trade, trades, transfers, historicalPnl, historicalTheos
Rủi ro và danh tính	riskGrid, profile, profileTrades, referralBinding, referralCodeByOwner
RFQ và thanh lý	rfqStatus, liquidations, liquidationStatus, liquidationHistory

Tham số request được truyền trước. Truyền một AbortSignal tùy chọn làm đối số cuối cùng.

const controller = new AbortController();

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

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

Cấu hình Transport

Hãy truyền URL API cụ thể khi ứng dụng của bạn chọn môi trường thông qua cấu hình.

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

• apiUrl mặc định là https://api.hypercall.xyz.
• timeout mặc định là 10.000 mili giây. Chỉ đặt thành null khi bên gọi tự cung cấp chính sách hủy riêng.
• fetchOptions áp dụng các tùy chọn fetch mặc định cho mọi request. SDK quản lý phương thức và body của request.

Ký và gửi lệnh ghi

ExchangeClient nhận các payload request đã được ký sẵn. Bên gọi vẫn chịu trách nhiệm kết nối ví, chọn nonce và tạo chữ ký.

Hàm hỗ trợ ký tạo ra domain, types, primary type và message EIP-712. Hãy truyền typed data đó vào phương thức ký do thư viện ví của bạn cung cấp.

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

Giá trị đã ký phải khớp

Các trường wallet, symbol, side, size, price, tif, route, client_id và nonce gửi lên API phải khớp chính xác với các trường PlaceOrder tương ứng đã được ký. Hãy giữ price và size ở dạng chuỗi. Một cách biểu diễn chuỗi khác sẽ tạo ra chữ ký khác.

Cấp phát nonce: Hypercall chấp nhận nonce trong khoảng từ hai ngày trước đến một ngày sau dấu thời gian của máy chủ. Hãy dùng thời gian epoch tính bằng mili giây làm giá trị khởi đầu, lưu bền vững nonce cuối cùng theo từng người ký một cách nguyên tử, và tăng đơn điệu để tránh xung đột giữa các worker chạy đồng thời và khi khởi động lại tiến trình.

Route: kiểu route của SDK có bao gồm rfq_only, nhưng API hiện từ chối giá trị này trên mọi endpoint đặt lệnh. Hãy sử dụng book_only hoặc best_execution.

Chọn instrument: Hãy xác định một instrument đang hoạt động từ InfoClient ngay trước khi xây dựng lệnh. Không mã hóa cứng một mã quyền chọn có ngày đáo hạn cụ thể vào một tích hợp chạy lâu dài.

Sử dụng type và builder reduce-only tương ứng cho các request reduce-only:

• Đặt lệnh: PLACE_ORDER_REDUCE_ONLY_TYPES với buildPlaceOrderReduceOnlyValue.
• Thay thế lệnh: REPLACE_ORDER_REDUCE_ONLY_TYPES với buildReplaceOrderReduceOnlyValue.

Xem Xác thực & Ký để biết domain ký production, quy tắc nonce, ủy quyền agent và tất cả các thông điệp ghi được hỗ trợ.

Xử lý lỗi

Gói gốc xuất các lớp lỗi của 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 nghĩa là SDK đã từ chối một request không hợp lệ trước khi gửi đi.
• HttpRequestError nghĩa là request thất bại, hết thời gian chờ, bị hủy, trả về mã trạng thái không thành công hoặc trả về JSON không hợp lệ.
• Kết quả giao dịch vẫn có thể báo trạng thái bị từ chối trong một phản hồi HTTP thành công. Hãy kiểm tra phản hồi của phương thức thay vì chỉ dựa vào exception.

Xem Lỗi API để biết hướng dẫn xử lý lỗi ổn định.

Các điểm import

Import	Mục đích sử dụng
@hypercallxyz/sdk	HttpTransport, InfoClient, ExchangeClient, các lớp lỗi và các kiểu công khai
@hypercallxyz/sdk/api/info	Các phương thức info có kiểu cấp thấp và schema request
@hypercallxyz/sdk/api/exchange	Các phương thức exchange có kiểu cấp thấp và schema request
@hypercallxyz/sdk/signing	Bản đồ type EIP-712, các builder giá trị và hàm hỗ trợ typed data

Để biết chi tiết request và response ở cấp endpoint, hãy dùng Tài liệu tham khảo REST API. Để xem lịch sử phát hành và các ví dụ có thể chạy được, hãy dùng changelog của SDK và thư mục examples/.