Skip to main content

ZTDX API 文档

欢迎使用 ZTDX API 文档！ZTDX 是一个去中心化的永续合约交易平台，采用链上结算 + 链下撮合的混合架构，提供高性能、低成本、透明公开的加密货币衍生品交易服务。

核心特性​

🔒 安全可靠​

  • ✅ EIP-712 签名验证：标准化的结构化签名，钱包友好
  • ✅ 链上资金托管：所有资金由智能合约管理，用户完全掌控
  • ✅ 透明清算：清算和ADL机制完全公开透明

⚡ 高性能​

  • ✅ 内存撮合引擎：毫秒级订单匹配
  • ✅ 自动做市商：确保市价单流动性
  • ✅ WebSocket推送：实时行情和订单更新

💰 低成本​

  • ✅ 智能保证金计算：平仓订单几乎免保证金
  • ✅ Arbitrum网络：低gas费，快速确认
  • ✅ 竞争性手续费：Maker/Taker 费率优惠

🎁 丰富功能​

  • ✅ 止盈止损：支持触发订单、追踪止损
  • ✅ 推荐返佣：5级返佣制度，最高30%
  • ✅ ADL机制：自动减仓保护系统稳定性
  • ✅ 保险基金：覆盖清算损失

基本信息​

项目内容
REST Base URLhttps://api.renance.xyz
WebSocket Base URLwss://ws.ztdx.io
响应格式JSON
认证方式EIP-712 + JWT Token
网络Arbitrum One / Arbitrum Sepolia
抵押品USDT

认证机制​

ZTDX 使用 EIP-712 结构化签名进行身份验证，这是以太坊生态的标准签名方式。

登录流程​

sequenceDiagram
    participant User
    participant API
    participant Blockchain
    
    User->>API: 1. GET /auth/nonce/:address
    API-->>User: 返回 nonce 和 typed_data
    User->>User: 2. 使用钱包签名 typed_data
    User->>API: 3. POST /auth/login (signature)
    API->>API: 验证 EIP-712 签名
    API-->>User: 返回 JWT Token
    User->>API: 4. 后续请求携带 JWT Token

快速开始示例​

JavaScript (ethers.js v6)​

import { BrowserProvider } from 'ethers';

// 1. 获取 nonce
const response = await fetch(`/api/v1/auth/nonce/${address}`);
const { nonce, typed_data } = await response.json();

// 2. 使用钱包签名 EIP-712
const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const signature = await signer.signTypedData(
  typed_data.domain,
  { Login: typed_data.types.Login },
  typed_data.message
);

// 3. 登录获取 JWT
const loginResp = await fetch('/api/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    address: address.toLowerCase(),
    signature,
    timestamp: parseInt(typed_data.message.timestamp)
  })
});

const { token } = await loginResp.json();
localStorage.setItem('jwt_token', token);

// 4. 使用 JWT 调用其他接口
const balances = await fetch('/api/v1/account/balances', {
  headers: { 'Authorization': `Bearer ${token}` }
});

Python​

from eth_account import Account
from eth_account.messages import encode_typed_data
import requests

# 1. 获取 nonce
response = requests.get(f"/api/v1/auth/nonce/{address}")
data = response.json()
typed_data = data["typed_data"]

# 2. 签名
signable_message = encode_typed_data(full_message=typed_data)
signed = Account.sign_message(signable_message, private_key=private_key)

# 3. 登录
login_resp = requests.post(
    "/api/v1/auth/login",
    json={
        "address": address.lower(),
        "signature": signed.signature.hex(),
        "timestamp": int(typed_data["message"]["timestamp"])
    }
)

token = login_resp.json()["token"]

# 4. 使用 JWT
headers = { 'Authorization': f'Bearer {token}' }
balances = requests.get("/api/v1/account/balances", headers=headers)

详见 身份验证文档。

API 功能概览​

📊 市场数据（公开）​

  • 交易对列表
  • 实时行情 (Ticker)
  • K线数据（支持 1m, 5m, 15m, 1h, 4h, D, W, M）
  • 订单簿深度
  • 最新成交

💼 账户管理​

  • 用户资料
  • 余额查询（available + frozen）
  • 充值准备（链上转账）
  • 提现请求（后端签名 + 合约调用）
  • 推荐系统（5级返佣，链上透明）

📈 交易与仓位​

订单管理​

  • 创建订单（限价/市价，EIP-712签名）
  • 查询订单
  • 取消订单（EIP-712签名）
  • 批量取消

仓位管理​

  • 查询仓位
  • 增加/减少保证金
  • 清算状态检查
  • 设置止盈止损

触发订单 🆕​

  • 止盈订单（Take Profit）
  • 止损订单（Stop Loss）
  • 追踪止损（Trailing Stop）
  • 仓位TP/SL快捷设置

⚙️ 风险管理​

ADL（自动减仓）🆕​

  • ADL 配置查询
  • ADL 排名查询
  • 用户 ADL 历史
  • ADL 事件查询

清算​

  • 清算历史
  • 清算配置
  • 保险基金余额

资金费率​

  • 当前费率
  • 历史费率
  • 用户结算记录

🔔 实时推送（WebSocket）​

  • 实时行情（ticker）
  • 订单簿更新
  • 最新成交
  • 订单状态更新
  • 仓位变化
  • 余额变化

数据类型规范​

Decimal 类型​

所有价格、数量、金额均使用 字符串 表示 Decimal，保证精度：

{
  "price": "65000.50",     // ✅ 正确
  "amount": "0.1",         // ✅ 正确
  "pnl": "-123.45"         // ✅ 正确
}

❌ 错误示例：

{
  "price": 65000.5,        // ❌ number 精度不足
  "amount": 0.1            // ❌ 浮点数精度问题
}

时间戳类型​

  • 签名时间戳：秒级（用于 EIP-712 签名的 timestamp 字段）
  • 记录时间戳：毫秒级（created_at, updated_at等）
{
  "timestamp": 1704067200,        // 秒（签名用）
  "created_at": 1704067200000,    // 毫秒（记录时间）
  "expires_at": 1704153600        // 秒（过期时间）
}

地址格式​

所有以太坊地址必须是小写：

{
  "address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb"  // ✅ 全小写
}

错误处理​

HTTP 状态码​

状态码描述常见原因
200OK请求成功
400Bad Request参数错误、余额不足、业务逻辑违规
401UnauthorizedJWT Token 过期或签名验证失败
403Forbidden无权访问该资源
404Not Found资源不存在
429Too Many Requests触发频率限制
500Internal Server Error服务器内部错误

错误响应格式​

{
  "error": "余额不足，需要 653.25 USDT 作为保证金",
  "code": "INSUFFICIENT_BALANCE",
  "details": {
    "required": "653.25",
    "available": "500.00"
  }
}

详见 错误代码文档。

频率限制​

REST API​

类型限制窗口期
公开接口100 次/分钟IP 级别
私有接口60 次/分钟用户级别
订单操作20 次/秒用户级别

WebSocket​

  • 每个连接最多订阅 50 个数据流
  • 每秒最多发送 10 条消息

最佳实践​

1. 使用 WebSocket 获取实时数据​

// ✅ 推荐：使用 WebSocket
ws.subscribe('ticker', 'BTCUSDT');

// ❌ 不推荐：轮询 REST API
setInterval(() => getTicker('BTCUSDT'), 1000);

2. 处理时间戳过期​

// 签名时间戳必须在 5 分钟内
const timestamp = Math.floor(Date.now() / 1000);

try {
  await createOrder({...});
} catch (error) {
  if (error.code === 'TIMESTAMP_EXPIRED') {
    // 重新生成时间戳和签名
    await retryWithNewTimestamp();
  }
}

3. 永远设置止损​

// 开仓后立即设置止损
const position = await getPositions();
await setPositionTPSL(position.id, {
  stop_loss_price: calculateStopLoss(position),
  take_profit_price: calculateTakeProfit(position)
});

4. 监控清算风险​

// 定期检查健康系数
const liquidation = await getLiquidationStatus(positionId);

if (liquidation.health_factor < 1.2) {
  // 增加保证金
  await addCollateral(positionId, "100");
}

支持的交易对​

交易对最小订单量价格精度最大杠杆
BTCUSDT0.001 BTC2 位小数50x
ETHUSDT0.01 ETH2 位小数50x
SOLUSDT0.1 SOL3 位小数50x

更多交易对请查询 市场列表 API。

智能合约地址​

Arbitrum Sepolia（测试网）​

  • Vault: 0x...
  • ReferralRebate: 0x...
  • ReferralStorage: 0x...

Arbitrum One（主网）​

待部署

文档导航​

🔰 入门指南​

📊 市场数据​

💼 账户管理​

📈 交易功能​

⚙️ 风险管理​

社区与支持​

更新日志​

2025-12-26​

  • ✨ 新增触发订单功能（止盈止损、追踪止损）
  • ✨ 新增 ADL 机制完整文档
  • ✨ 推荐系统支持链上查询和领取
  • 🔧 完善保证金计算逻辑（智能平仓优化）
  • 📚 全面更新为 EIP-712 签名机制
  • 📚 100% API 覆盖率文档

详见 变更日志。

开始探索 ZTDX API，开启您的交易之旅！ 🚀