API 文档概述

欢迎使用 Zanbara REST API 文档。本文档将帮助您快速集成 Zanbara 永续合约交易平台,实现程序化交易、做市策略和自动化风险管理。

API 架构概览

Zanbara 提供完整的 REST API 和 WebSocket API,支持所有核心交易功能:

• REST API: 用于下单、撤单、查询账户、管理仓位等操作

• WebSocket API: 用于实时接收市场数据、订单更新、仓位变动等推送消息

• 认证机制: JWT Token 认证,支持 HMAC-SHA256 签名

• 数据格式: 统一的 JSON 请求和响应格式

架构特点

Zanbara 采用混合架构设计,结合链上结算和链下撮合的优势:

• 高性能撮合引擎: 基于 Rust 实现,支持每秒数万笔订单处理

• 链上结算: Solana 区块链提供最终结算和资产托管

• 实时推送: Redis Pub/Sub 实现毫秒级市场数据推送

• 高可用架构: 多节点部署,支持故障自动切换

API 基础信息

Base URL

生产环境: https://api.zanbarax.com
测试环境: https://testnet-api.zanbarax.com

所有 API 请求都应该发送到以上基础 URL,并附加具体的 API 路径。

示例:

# 获取 SOL-PERP 行情
curl https://api.zanbarax.com/v1/market/ticker/SOL-PERP

# 创建订单 (需要认证)
curl -X POST https://api.zanbarax.com/v1/order/place \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"SOL-PERP","side":"buy","type":"limit","quantity":"10","price":"150.5"}'

API 版本控制

当前 API 版本: v1

Zanbara API 使用 URL 路径版本控制:

• /v1/... - 当前稳定版本

• 未来版本将使用 /v2/..., /v3/... 等

版本兼容性承诺:

• v1 API 将长期支持,不会破坏性变更

• 新功能将通过新版本 API 提供

• 废弃 API 将提前 6 个月通知

端点分类

Zanbara API 分为公开端点和私有端点:

公开端点 (无需认证)

这些端点不需要认证即可访问:

• 市场数据: 行情、订单簿、K线、成交记录

• 系统状态: 健康检查、服务器时间

• 交易对信息: 可用交易对、合约规格

私有端点 (需要认证)

这些端点需要有效的 JWT Token:

• 账户管理: 查询余额、充值、提现

• 订单管理: 下单、撤单、查询订单

• 仓位管理: 查询仓位、调整杠杆、平仓

• 交易历史: 成交记录、资金流水

统一响应格式

所有 API 响应都遵循统一的 JSON 格式:

成功响应

{
  "success": true,
  "data": {
    // 响应数据
  },
  "timestamp": 1696752000000
}

字段说明:

• success: 布尔值,表示请求是否成功

• data: 响应数据对象,具体结构取决于 API 端点

• timestamp: 服务器时间戳 (毫秒)

错误响应

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance: available=100.00 USDC, required=150.00 USDC",
    "field": "quantity"
  },
  "timestamp": 1696752000000
}

字段说明:

• success: 固定为 false

• error.code: 错误代码,用于程序化处理

• error.message: 人类可读的错误描述

• error.field: (可选) 导致错误的请求字段

• timestamp: 服务器时间戳 (毫秒)

常见错误代码请参考 错误码文档。

分页响应

对于返回列表的 API,使用统一的分页格式:

{
  "success": true,
  "data": {
    "items": [
      // 数据项数组
    ],
    "total": 1250,
    "page": 1,
    "limit": 20,
    "total_pages": 63,
    "has_next": true,
    "has_prev": false
  },
  "timestamp": 1696752000000
}

分页参数:

• page: 当前页码 (从 1 开始)

• limit: 每页数据量 (默认 20,最大 100)

• total: 总记录数

• total_pages: 总页数

• has_next: 是否有下一页

• has_prev: 是否有上一页

请求示例:

# 获取第 2 页订单,每页 50 条
curl "https://api.zanbarax.com/v1/order/list?page=2&limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

速率限制

为保证系统稳定性和公平性,Zanbara API 实施速率限制:

限制规则

端点类型	IP 限制	API Key 限制
公开端点	60 次/分钟	不适用
私有端点 - 查询	120 次/分钟	600 次/分钟
私有端点 - 交易	30 次/分钟	120 次/分钟

速率限制响应头

每个 API 响应都包含速率限制信息:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1696752060

响应头说明:

• X-RateLimit-Limit: 当前时间窗口的请求上限

• X-RateLimit-Remaining: 当前时间窗口剩余请求次数

• X-RateLimit-Reset: 速率限制重置时间 (Unix 时间戳)

超过限制的处理

当超过速率限制时,API 将返回 HTTP 429 Too Many Requests:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded: 120 requests per minute. Please retry after 45 seconds.",
    "retry_after": 45
  },
  "timestamp": 1696752000000
}

建议处理策略:

1. 监控响应头中的 X-RateLimit-Remaining

2. 当剩余次数较低时,主动降低请求频率

3. 实现指数退避重试机制

4. 使用 WebSocket API 接收实时数据,减少轮询

详细信息请参考 速率限制文档。

认证机制

Zanbara API 使用 JWT (JSON Web Token) 认证机制。

获取 Token

步骤 1: 在 Zanbara 网站生成 API Key

1. 登录您的 Zanbara 账户

2. 访问 "账户设置" > "API 管理"

3. 点击 "创建 API Key"

4. 设置权限范围 (只读/交易/提现)

5. 记录您的 API Key 和 Secret (仅显示一次)

步骤 2: 使用 API Key 和 Secret 生成 JWT Token

# 请求生成 Token
curl -X POST https://api.zanbarax.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET"
  }'

# 响应
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600
  }
}

Token 有效期: 1 小时 (3600 秒)。Token 过期后需要重新生成。

使用 Token

在所有私有 API 请求中,通过 Authorization 头部传递 JWT Token:

curl https://api.zanbarax.com/v1/account/balance \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

请求签名 (可选)

对于高安全性要求的场景,Zanbara 支持 HMAC-SHA256 请求签名:

Authorization: Bearer {JWT_TOKEN}
X-API-Key: {YOUR_API_KEY}
X-API-Signature: {HMAC_SHA256_SIGNATURE}
X-API-Timestamp: {UNIX_TIMESTAMP_MS}

签名算法:

1. 按照 timestamp + method + path + body 拼接待签名字符串

2. 使用 API Secret 进行 HMAC-SHA256 签名

3. 将签名结果进行 hex 编码

详细说明请参考 认证文档。

数据类型规范

数字精度

Zanbara 使用定点数表示价格和数量,避免浮点数精度问题:

字段类型	数据类型	精度	示例
价格 (Price)	Decimal	8 位小数	"150.50000000"
数量 (Quantity)	Decimal	8 位小数	"10.50000000"
金额 (Amount)	Decimal	8 位小数	"1580.25000000"
杠杆 (Leverage)	Integer	整数	10
资金费率 (Funding Rate)	Decimal	6 位小数	"0.000125"

重要提示:

• 请求中的数字字段应使用字符串类型传递,以保证精度

• 响应中的数字字段也为字符串类型

正确示例:

{
  "symbol": "SOL-PERP",
  "quantity": "10.5",
  "price": "150.75"
}

错误示例 (可能导致精度丢失):

{
  "symbol": "SOL-PERP",
  "quantity": 10.5,
  "price": 150.75
}

时间戳格式

Zanbara API 统一使用 Unix 时间戳 (毫秒):

{
  "timestamp": 1696752000000,
  "created_at": 1696752000000,
  "updated_at": 1696752000000
}

转换参考:

• JavaScript: Date.now() 或 new Date().getTime()

• Python: int(time.time() * 1000)

• Rust: SystemTime::now().duration_since(UNIX_EPOCH).unwrap().as_millis()

枚举类型

订单方向 (Order Side)

"buy"  - 买入/做多
"sell" - 卖出/做空

订单类型 (Order Type)

"limit"        - 限价单
"market"       - 市价单
"stop_limit"   - 止损限价单
"stop_market"  - 止损市价单
"take_profit"  - 止盈单
"trailing_stop" - 追踪止损单
"post_only"    - Post-Only 单
"iceberg"      - 冰山订单

订单状态 (Order Status)

"pending"        - 待成交
"partial_filled" - 部分成交
"filled"         - 完全成交
"cancelled"      - 已撤销
"expired"        - 已过期
"rejected"       - 已拒绝

时间有效性 (Time In Force)

"GTC" - Good Till Cancel (取消前有效)
"IOC" - Immediate or Cancel (立即成交否则撤销)
"FOK" - Fill or Kill (全部成交否则撤销)
"GTT" - Good Till Time (指定时间前有效)

保证金模式 (Margin Mode)

"cross"    - 全仓模式
"isolated" - 逐仓模式

仓位方向 (Position Side)

"long"  - 多头仓位
"short" - 空头仓位

测试环境

Zanbara 提供完整的测试环境供您开发和测试:

测试网信息

API Base URL: https://testnet-api.zanbarax.com
WebSocket URL: wss://testnet-ws.zanbarax.com
区块链: Solana Devnet

获取测试资金

1. 访问 Zanbara 测试网: https://testnet.zanbarax.com

2. 连接 Solana Devnet 钱包

3. 使用水龙头获取测试 SOL: https://faucet.solana.com

4. 在测试网充值页面兑换测试 USDC

测试网特点

• 完全模拟生产环境功能

• 独立的订单簿和撮合引擎

• 定期重置数据 (每月 1 日)

• 无速率限制 (方便压力测试)

客户端库和 SDK

为了简化集成,Zanbara 提供官方 SDK:

TypeScript/JavaScript SDK

npm install @ZanbaraX/sdk

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

const client = new ZanbaraClient({
  apiKey: 'YOUR_API_KEY',
  apiSecret: 'YOUR_API_SECRET',
  baseURL: 'https://api.zanbarax.com'
});

// 获取账户余额
const balance = await client.account.getBalance();

// 下限价单
const order = await client.orders.createLimit({
  symbol: 'SOL-PERP',
  side: 'buy',
  quantity: '10',
  price: '150.5'
});

Python SDK

pip install zanbara-sdk

from zanbara import ZanbaraClient

client = ZanbaraClient(
    api_key='YOUR_API_KEY',
    api_secret='YOUR_API_SECRET',
    base_url='https://api.zanbarax.com'
)

# 获取账户余额
balance = client.account.get_balance()

# 下限价单
order = client.orders.create_limit(
    symbol='SOL-PERP',
    side='buy',
    quantity='10',
    price='150.5'
)

Rust SDK

[dependencies]
zanbara-sdk = "0.1.0"

use zanbara_sdk::{ZanbaraClient, OrderSide};

#[tokio::main]
async fn main() {
    let client = ZanbaraClient::new(
        "YOUR_API_KEY",
        "YOUR_API_SECRET",
        "https://api.zanbarax.com"
    );

    // 获取账户余额
    let balance = client.account().get_balance().await.unwrap();

    // 下限价单
    let order = client.orders()
        .create_limit("SOL-PERP", OrderSide::Buy, "10", "150.5")
        .await
        .unwrap();
}

详细 SDK 文档请参考:

• TypeScript SDK 文档

• Python SDK 文档

• Rust SDK 文档

最佳实践

错误处理

始终检查 success 字段并处理错误:

try {
  const response = await client.orders.create(orderParams);
  if (!response.success) {
    console.error(`Order failed: ${response.error.code} - ${response.error.message}`);
    // 根据错误码进行特定处理
    if (response.error.code === 'INSUFFICIENT_BALANCE') {
      // 处理余额不足
    }
  }
} catch (error) {
  console.error('Network error:', error);
  // 处理网络错误
}

幂等性保证

对于创建订单等操作,使用客户端生成的唯一 ID 保证幂等性:

{
  "client_order_id": "unique-id-12345",
  "symbol": "SOL-PERP",
  "side": "buy",
  "type": "limit",
  "quantity": "10",
  "price": "150.5"
}

如果使用相同的 client_order_id 重复请求,系统将返回已有订单而不是创建新订单。

时钟同步

确保您的系统时钟准确:

# 获取服务器时间
curl https://api.zanbarax.com/v1/system/time

# 响应
{
  "success": true,
  "data": {
    "server_time": 1696752000000
  }
}

如果您的系统时钟与服务器时间相差超过 5 秒,签名验证可能失败。

WebSocket 心跳

WebSocket 连接需要定期发送心跳:

// 每 30 秒发送一次 ping
{"type": "ping"}

// 服务器响应
{"type": "pong", "timestamp": 1696752000000}

超过 60 秒没有心跳,连接将被服务器主动断开。

性能优化建议

批量操作

优先使用批量 API 减少请求次数:

# 批量撤单 (推荐)
POST /v1/order/cancel-batch
{
  "order_ids": ["id1", "id2", "id3"]
}

# 逐个撤单 (不推荐)
DELETE /v1/order/{id1}
DELETE /v1/order/{id2}
DELETE /v1/order/{id3}

使用 WebSocket

对于需要实时数据的场景,使用 WebSocket 而不是轮询:

// 推荐: WebSocket 订阅
ws.subscribe({
  channel: 'orderbook',
  symbol: 'SOL-PERP',
  depth: 20
});

// 不推荐: HTTP 轮询
setInterval(() => {
  fetch('/v1/market/orderbook/SOL-PERP');
}, 1000);

本地缓存

缓存不经常变化的数据:

// 交易对配置可以缓存 1 小时
const symbolsCache = new Map();

async function getSymbolInfo(symbol) {
  if (symbolsCache.has(symbol)) {
    return symbolsCache.get(symbol);
  }
  const info = await client.market.getSymbolInfo(symbol);
  symbolsCache.set(symbol, info);
  setTimeout(() => symbolsCache.delete(symbol), 3600000);
  return info;
}

连接复用

使用 HTTP Keep-Alive 和连接池:

import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

session = requests.Session()
retry = Retry(total=3, backoff_factor=0.3)
adapter = HTTPAdapter(max_retries=retry, pool_connections=10, pool_maxsize=20)
session.mount('https://', adapter)

安全建议

API Key 安全

• 永远不要在客户端代码中硬编码 API Secret

• 使用环境变量或密钥管理系统存储凭证

• 定期轮换 API Key (建议每 90 天)

• 为不同用途创建不同权限的 API Key

IP 白名单

在 API Key 设置中配置 IP 白名单:

允许的 IP:
203.0.113.10
203.0.113.20-30
203.0.113.0/24

权限最小化

根据实际需要分配最小权限:

只读 API Key: 仅用于查询余额、订单、仓位
交易 API Key: 可以下单、撤单,但不能提现
提现 API Key: 可以提现,需要额外的二次验证

支持与反馈

技术支持

遇到问题时,您可以通过以下方式获取帮助:

• 开发者文档: https://docs.zanbarax.com

• API 状态页: https://status.zanbarax.com

• Discord 社区: https://discord.gg/zanbarax

• 技术支持邮箱: [email protected]

Bug 报告

发现 API 问题请通过以下方式报告:

1. GitHub Issues: https://github.com/zanbarax/api-issues

2. 邮件: [email protected]

3. Discord #api-bugs 频道

报告时请包含:

• 请求方法、URL、请求体

• 完整的响应内容

• 请求时间戳

• 您的 API Key (前 8 位)

功能建议

我们欢迎您提出 API 改进建议:

• Discord #api-feedback 频道

• 邮件: [email protected]

• 每月 API 用户调研

变更日志

2025-10-07 - v1.0.0

• 初始发布

• 支持基础交易功能

• 支持实时市场数据订阅

• 支持账户和仓位管理

即将推出的功能 (v1.1.0 预计 2025-11):

• 批量订单操作

• 高级订单类型 (TWAPs, Iceberg)

• 历史数据导出 API

• GraphQL API 支持

---

下一步

选择您感兴趣的主题继续阅读:

• 认证机制详解 - 学习如何安全地认证 API 请求

• 错误码参考 - 完整的错误码列表和处理建议

• 市场数据 API - 获取实时行情、订单簿、K线数据

• 交易 API - 下单、撤单、查询订单

• 账户管理 API - 查询余额、充值、提现

• 仓位管理 API - 查询仓位、调整杠杆、平仓

示例代码:

• 完整下单示例

• 撤单示例

• 查询仓位示例

---

文档版本: v1.0.0 最后更新: 2025-10-07 维护: Zanbara API Team