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 示例 - 更多实战示例
Last updated