TypeScript SDK

Zanbara TypeScript SDK 为 JavaScript/TypeScript 应用提供完整的 API 和 WebSocket 客户端封装。

安装

npm install @ZanbaraX/sdk
# 或
yarn add @ZanbaraX/sdk
# 或
pnpm add @ZanbaraX/sdk

快速开始

import { ZanbaraApiClient, ZanbaraWsClient } from '@ZanbaraX/sdk';

// REST API 客户端
const apiClient = new ZanbaraApiClient('https://api.zanbarax.com/v1');

// WebSocket 客户端
const wsClient = new ZanbaraWsClient('wss://ws.zanbarax.com');

// 获取订单簿
const orderbook = await apiClient.getOrderbook('BTC-PERP', 20);
console.log('订单簿:', orderbook);

// 订阅实时数据
await wsClient.connect();
wsClient.subscribeTicker('BTC-PERP', (data) => {
  console.log('价格更新:', data.lastPrice);
});

REST API 客户端

初始化

import { ZanbaraApiClient } from '@ZanbaraX/sdk';

const apiClient = new ZanbaraApiClient('https://api.zanbarax.com/v1');

// 使用自定义配置
const apiClient = new ZanbaraApiClient('https://api.zanbarax.com/v1', {
  timeout: 10000,
  headers: {
    'X-Custom-Header': 'value'
  }
});

市场数据

// 获取所有市场
const markets = await apiClient.getMarkets();

// 获取订单簿
const orderbook = await apiClient.getOrderbook('BTC-PERP', 20);

// 获取最新成交
const trades = await apiClient.getTrades('BTC-PERP', 50);

// 获取 K线数据
const klines = await apiClient.getKlines('BTC-PERP', '1h', {
  startTime: Date.now() - 86400000,
  endTime: Date.now(),
  limit: 100
});

// 获取 24h 统计
const stats = await apiClient.getMarketStats('BTC-PERP');

账户操作 (需要认证)

// 设置 API Key
apiClient.setApiKey('YOUR_API_KEY');

// 获取持仓
const positions = await apiClient.getPositions('YOUR_WALLET_ADDRESS');

// 获取订单
const orders = await apiClient.getOrders('YOUR_WALLET_ADDRESS', 'open');

// 获取成交历史
const fills = await apiClient.getFills('YOUR_WALLET_ADDRESS', {
  market: 'BTC-PERP',
  limit: 50
});

高级订单

// 创建 Iceberg 订单
const icebergOrder = await apiClient.createIcebergOrder({
  symbol: 'BTC-PERP',
  side: 'buy',
  totalQuantity: '5.0',
  visibleQuantity: '0.5',
  price: '43000.0'
});

// 创建 TWAP 订单
const twapOrder = await apiClient.createTwapOrder({
  symbol: 'ETH-PERP',
  side: 'sell',
  totalQuantity: '10.0',
  durationSeconds: 3600,
  numSlices: 10
});

// 获取执行统计
const icebergStats = await apiClient.getIcebergStats('iceberg_abc123');
const twapStats = await apiClient.getTwapStats('twap_xyz789');

WebSocket 客户端

初始化和连接

import { ZanbaraWsClient } from '@ZanbaraX/sdk';

const wsClient = new ZanbaraWsClient('wss://ws.zanbarax.com', {
  autoReconnect: true,
  maxReconnectAttempts: 10,
  heartbeatInterval: 30000,
  debug: true
});

await wsClient.connect();

公开频道订阅

// 订阅订单簿
wsClient.subscribeOrderbook('BTC-PERP', (data) => {
  console.log('订单簿更新:', data);
});

// 订阅最新成交
wsClient.subscribeTrades('ETH-PERP', (data) => {
  console.log('新成交:', data);
});

// 订阅 Ticker
wsClient.subscribeTicker('SOL-PERP', (data) => {
  console.log('Ticker:', data);
});

// 订阅 K线
wsClient.subscribeKline('BTC-PERP', '1m', (data) => {
  console.log('K线:', data);
});

私有频道订阅 (需要认证)

// 获取 WebSocket token
const token = await apiClient.getWebSocketToken();

// 使用 token 连接
const wsClient = new ZanbaraWsClient(`wss://ws.zanbarax.com?token=${token}`);
await wsClient.connect();

// 订阅账户更新
wsClient.subscribe('account', (data) => {
  console.log('账户更新:', data);
});

// 订阅订单更新
wsClient.subscribeOrders('YOUR_WALLET_ADDRESS', (data) => {
  console.log('订单更新:', data);
});

// 订阅持仓更新
wsClient.subscribePositions('YOUR_WALLET_ADDRESS', (data) => {
  console.log('持仓更新:', data);
});

// 订阅 Iceberg 订单
wsClient.subscribeIcebergOrders('YOUR_WALLET_ADDRESS', (data) => {
  console.log('Iceberg 订单:', data);
});

// 订阅 TWAP 订单
wsClient.subscribeTwapOrders('YOUR_WALLET_ADDRESS', (data) => {
  console.log('TWAP 订单:', data);
});

事件监听

wsClient.on('connected', () => {
  console.log('✓ WebSocket 已连接');
});

wsClient.on('disconnected', () => {
  console.log('✗ WebSocket 已断开');
});

wsClient.on('error', (error) => {
  console.error('✗ WebSocket 错误:', error);
});

wsClient.on('message', (message) => {
  console.log('收到消息:', message);
});

TypeScript 类型定义

SDK 提供完整的 TypeScript 类型定义:

import type {
  // Market Data
  OrderbookData,
  OrderbookLevel,
  Trade,
  Kline,
  MarketStats,
  Ticker,

  // Account
  Position,
  Order,
  Fill,
  AccountBalance,

  // Advanced Orders
  IcebergOrder,
  TwapOrder,
  IcebergStats,
  TwapStats,

  // WebSocket
  WsMessage,
  OrderbookUpdate,
  TradeUpdate,
  TickerUpdate,
  PositionUpdate,
  OrderUpdate,
} from '@ZanbaraX/sdk';

React Hooks

SDK 提供便捷的 React Hooks:

import { useOrderbook, useTicker, usePositions } from '@ZanbaraX/sdk/react';

function TradingComponent() {
  // 使用订单簿 Hook
  const { orderbook, loading, error } = useOrderbook('BTC-PERP');

  // 使用 Ticker Hook
  const { ticker } = useTicker('BTC-PERP');

  // 使用持仓 Hook (需要认证)
  const { positions } = usePositions('YOUR_WALLET_ADDRESS', token);

  return (
    <div>
      <h1>{ticker?.lastPrice}</h1>
      <OrderbookDisplay orderbook={orderbook} />
      <PositionsList positions={positions} />
    </div>
  );
}

错误处理

try {
  const orderbook = await apiClient.getOrderbook('BTC-PERP');
} catch (error) {
  if (error instanceof ApiError) {
    console.error('API 错误:', error.message);
    console.error('错误码:', error.code);
    console.error('状态码:', error.statusCode);
  } else {
    console.error('未知错误:', error);
  }
}

完整示例

import { ZanbaraApiClient, ZanbaraWsClient } from '@ZanbaraX/sdk';

async function main() {
  // 初始化客户端
  const apiClient = new ZanbaraApiClient('https://api.zanbarax.com/v1');
  const wsClient = new ZanbaraWsClient('wss://ws.zanbarax.com');

  // 获取市场列表
  const markets = await apiClient.getMarkets();
  console.log('可用市场:', markets.map(m => m.symbol));

  // 连接 WebSocket
  await wsClient.connect();

  // 订阅多个市场
  for (const market of ['BTC-PERP', 'ETH-PERP', 'SOL-PERP']) {
    wsClient.subscribeTicker(market, (data) => {
      console.log(`${market}: ${data.lastPrice} (${data.priceChangePercent24h}%)`);
    });
  }

  // 保持运行
  await new Promise(() => {});
}

main().catch(console.error);

下一步

• Python SDK - Python SDK 文档

• Rust SDK - Rust SDK 文档

• SDK 示例 - 更多实战示例