TypeScript SDK

使用官方 @hypercallxyz/sdk 包，从 TypeScript 或现代 JavaScript 调用 Hypercall REST API。

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

配置传输层

当您的应用通过配置选择运行环境时，请显式传入 API URL。

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 域、类型、主类型和消息。请将该类型化数据传给您所用钱包库提供的签名方法。

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

签名值必须一致

提交给 API 的 wallet、symbol、side、size、price、tif、route、client_id 和 nonce 必须与已签名 PlaceOrder 中对应的字段完全一致。请将 price 和 size 保持为字符串。不同的字符串表示会产生不同的签名。

Nonce 分配： Hypercall 接受服务器时间戳之前两天至之后一天范围内的 nonce。请以毫秒级 epoch 时间作为种子，按签名者原子化持久保存最近一次的 nonce，并单调递增，以避免并发工作进程之间以及进程重启后发生冲突。

路由： SDK 的 route 类型包含 rfq_only，但 API 目前在所有订单端点上都会拒绝该值。请使用 book_only 或 best_execution。

合约选择： 请在构建订单之前，立即通过 InfoClient 解析一个活跃合约。不要在长期运行的集成中硬编码带日期的期权代码。

对于只减仓请求，请使用对应的只减仓类型和构建函数：

• 下单： 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 方法及请求 schema
@hypercallxyz/sdk/api/exchange	底层类型化 exchange 方法及请求 schema
@hypercallxyz/sdk/signing	EIP-712 类型映射、值构建函数及类型化数据辅助工具

有关端点级别的请求和响应详情，请参阅 REST API 参考。有关版本历史和可运行示例，请参阅 SDK 的更新日志和 examples/ 目录。