このページは機械翻訳されています。英語の原文が正式版です。 英語で読む →
メインコンテンツにスキップ

TypeScript SDK

TypeScript またはモダンな JavaScript から Hypercall REST API を呼び出すには、公式の @hypercallxyz/sdk パッケージを使用します。

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
リスクと IDriskGrid, 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 は、サーバーのタイムスタンプから 2 日前から 1 日後までの範囲の nonce を受け付けます。ミリ秒単位のエポック時刻をシードとして使用し、署名者ごとに最後の nonce をアトミックに永続化したうえで単調に増加させてください。これにより、並行するワーカー間やプロセス再起動時の衝突を防げます。

ルート: SDK の route 型には 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/sdkHttpTransport、InfoClient、ExchangeClient、エラークラス、公開型
@hypercallxyz/sdk/api/info低レベルの型付き info メソッドとリクエストスキーマ
@hypercallxyz/sdk/api/exchange低レベルの型付き exchange メソッドとリクエストスキーマ
@hypercallxyz/sdk/signingEIP-712 の型マップ、値ビルダー、型付きデータヘルパー

エンドポイントごとのリクエストとレスポンスの詳細は、REST API リファレンスを参照してください。リリース履歴と実行可能なサンプルについては、SDK の変更履歴と examples/ ディレクトリを参照してください。

最終更新: