ZTDX API 文档

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

核心特性

🔒 安全可靠

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

⚡ 高性能

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

💰 低成本

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

🎁 丰富功能

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

---

基本信息

项目	内容
REST Base URL	https://api.renance.xyz
WebSocket Base URL	wss://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 状态码

状态码	描述	常见原因
200	OK	请求成功
400	Bad Request	参数错误、余额不足、业务逻辑违规
401	Unauthorized	JWT Token 过期或签名验证失败
403	Forbidden	无权访问该资源
404	Not Found	资源不存在
429	Too Many Requests	触发频率限制
500	Internal 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");
}

---

支持的交易对

交易对	最小订单量	价格精度	最大杠杆
BTCUSDT	0.001 BTC	2 位小数	50x
ETHUSDT	0.01 ETH	2 位小数	50x
SOLUSDT	0.1 SOL	3 位小数	50x

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

---

智能合约地址

Arbitrum Sepolia（测试网）

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

Arbitrum One（主网）

待部署

---

文档导航

🔰 入门指南

• 身份验证 - 必读：EIP-712 签名详解
• 错误代码 - 所有错误代码说明
• WebSocket - 实时数据推送

📊 市场数据

• 市场概览
• 交易对列表
• 行情数据
• K线数据
• 订单簿
• 最新成交

💼 账户管理

• 用户资料
• 账户余额
• 充值与提现
• 推荐系统

📈 交易功能

• 订单管理 - 核心功能
• 仓位管理
• 触发订单 - 止盈止损
• 交易历史

⚙️ 风险管理

• ADL 机制 - 自动减仓
• 清算机制
• 资金费率

---

社区与支持

• Discord: 加入社区
• Twitter: @ZTDX_io
• GitHub: github.com/ztdx
• Email: [email protected]

---

更新日志

2025-12-26

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

详见 变更日志。

---

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