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: 固定为falseerror.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 实施速率限制:
限制规则
公开端点
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
}建议处理策略:
监控响应头中的
X-RateLimit-Remaining当剩余次数较低时,主动降低请求频率
实现指数退避重试机制
使用 WebSocket API 接收实时数据,减少轮询
详细信息请参考 速率限制文档。
认证机制
Zanbara API 使用 JWT (JSON Web Token) 认证机制。
获取 Token
步骤 1: 在 Zanbara 网站生成 API Key
登录您的 Zanbara 账户
访问 "账户设置" > "API 管理"
点击 "创建 API Key"
设置权限范围 (只读/交易/提现)
记录您的 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}签名算法:
按照
timestamp+method+path+body拼接待签名字符串使用 API Secret 进行 HMAC-SHA256 签名
将签名结果进行 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获取测试资金
访问 Zanbara 测试网: https://testnet.zanbarax.com
连接 Solana Devnet 钱包
使用水龙头获取测试 SOL: https://faucet.solana.com
在测试网充值页面兑换测试 USDC
测试网特点
完全模拟生产环境功能
独立的订单簿和撮合引擎
定期重置数据 (每月 1 日)
无速率限制 (方便压力测试)
客户端库和 SDK
为了简化集成,Zanbara 提供官方 SDK:
TypeScript/JavaScript SDK
npm install @ZanbaraX/sdkimport { 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-sdkfrom 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 文档请参考:
最佳实践
错误处理
始终检查 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 问题请通过以下方式报告:
GitHub Issues: https://github.com/zanbarax/api-issues
Discord #api-bugs 频道
报告时请包含:
请求方法、URL、请求体
完整的响应内容
请求时间戳
您的 API Key (前 8 位)
功能建议
我们欢迎您提出 API 改进建议:
Discord #api-feedback 频道
每月 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
Last updated