XBlade 做市商 API 文档

版本： 1.0

测试网基准 URL： https://api.8a27.xyz/api/v1

主网基准 URL： https://api.renance.xyz/api/v1

网络： Arbitrum Sepolia (测试网) / Arbitrum One (主网)

简介

XBlade 是一个构建在 Arbitrum 上的非托管去中心化永续期货交易所。做市商可以使用 API Key 结合 EIP-712 钱包签名，以编程方式下单、管理仓位及查询数据。

核心特性

非托管：资金保留在您的钱包中；未经您的签名，平台无法执行订单。
API Key 认证：为自动化交易提供简化的会话管理。
EIP-712 签名：针对所有关键操作采用安全、类型化的数据签名标准。
高杠杆：永续合约支持最高 100 倍杠杆。
低延迟：针对高频交易优化的撮合引擎。
实时 WebSocket：实时推送订单簿、成交记录和仓位更新。

快速入门

前提条件

带有私钥的钱包：您需要一个兼容以太坊的钱包（如 MetaMask、硬件钱包等）。
充值资金：通过链上交易将 USDT（抵押品）充值到 XBladeVault 合约。
API Key：通过 Web 界面或编程方式创建 API key。

网络配置

网络	链 ID (Chain ID)	RPC 地址	金库合约 (Vault Contract)
Arbitrum Sepolia (测试网)	421614	`https://sepolia-rollup.arbitrum.io/rpc`	`0xAAbdbE3F3382D8E620cDeCD9b06022b8E63bE33D`
Arbitrum One (主网)	42161	`https://arb1.arbitrum.io/rpc`	`0x5d2efcbdC2dD4b9Ff06Ea396F62878Ef982377c2`

代币地址

代币	Sepolia 测试网	Mainnet 主网
USDT	`0x572E474C3Cf364D085760784F938A1Aa397a8B9b`	`0x6A2D98c29F8938312dD13C038585a6fe67CA2B8B`

快速入门清单

向 XBladeVault 合约充值 USDT
通过对登录消息进行签名获取 JWT 令牌 (Token)
使用 JWT 令牌创建 API Key
使用 API Key 测试下单
实现订单管理逻辑

身份认证

XBlade 使用双层认证系统：

API Key：用于会话认证（类似于币安）。
EIP-712 签名：用于授权关键操作（下单、撤单、提现）。

创建 API Key

第一步：登录以获取 JWT 令牌

接口： POST /auth/login

首先，您需要获取一个 nonce 并对登录消息进行签名：

GET /auth/nonce/{wallet_address}

响应：

{
  "nonce": 123456789
}

然后，使用 EIP-712 签名登录消息：

类型化数据结构 (Typed Data Structure)：

{
  "types": {
    "EIP712Domain": [
      {"name": "name", "type": "string"},
      {"name": "version", "type": "string"},
      {"name": "chainId", "type": "uint256"},
      {"name": "verifyingContract", "type": "address"}
    ],
    "Login": [
      {"name": "wallet", "type": "address"},
      {"name": "nonce", "type": "uint256"},
      {"name": "timestamp", "type": "uint256"}
    ]
  },
  "primaryType": "Login",
  "domain": {
    "name": "AXBlade",
    "version": "1",
    "chainId": 421614,
    "verifyingContract": "0xAAbdbE3F3382D8E620cDeCD9b06022b8E63bE33D"
  },
  "message": {
    "wallet": "0x...",
    "nonce": 123456789,
    "timestamp": 1673000000
  }
}

⚠️ 重要的域名 (Domain Names)：

测试网 (Sepolia)："AXBlade"
主网："XBlade Vault"

登录请求：

POST /auth/login
Content-Type: application/json

{
  "address": "0x29F721B203A9fC9c5DDe35A739d8b8E0E4605489",
  "signature": "0x...",
  "timestamp": 1673000000
}

响应：

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

第二步：创建 API Key

接口： POST /api-keys

请求头：

Authorization: Bearer {jwt_token}
Content-Type: application/json

请求体：

{
  "label": "My Trading Bot",
  "ip_whitelist": null
}

响应：

{
  "id": "c4938422-8b32-457a-8502-5307fe9898c6",
  "api_key": "07aefa8e0593a7f6161170940a516f1f03a1fe9d15f06401672c65885e8190da",
  "secret_key": "d8b2dcefdb66734ce4a6bae5c045c9622683f8976559252f99deae42c5d3da10",
  "label": "My Trading Bot",
  "ip_whitelist": null,
  "permissions": "trading,deposit",
  "created_at": "2026-01-12T06:27:31.736360Z",
  "status": "active"
}

⚠️ 重要提示：

请立即保存 api_key 和 secret_key。出于安全原因，secret_key 稍后将无法检索。
每个账户最多创建 30 个 API key。

管理 API Key

更新 API Key / 绑定 IP 白名单

接口： PUT /api-keys/{id}

请求头：

Authorization: Bearer {jwt_token}
Content-Type: application/json

请求体：

{
  "label": "Updated Bot Label",
  "ip_whitelist": "192.168.1.1,10.0.0.1",
  "status": "active"
}

参数说明：

参数	类型	必填	描述
label	string	否	API Key 的标签
ip_whitelist	string	否	允许访问的 IP 地址列表，使用逗号分隔。传空字符串或 `null` 可清除白名单（不推荐）。
status	string	否	状态：`"active"` (启用) 或 `"disabled"` (禁用)

响应：

{
  "id": "c4938422-8b32-457a-8502-5307fe9898c6",
  "api_key": "07aef...",
  "label": "Updated Bot Label",
  "ip_whitelist": "192.168.1.1,10.0.0.1",
  "permissions": "trading,deposit",
  "created_at": "2026-01-12T06:27:31.736360Z",
  "status": "active"
}

删除 API Key

接口： DELETE /api-keys/{id}

请求头：

Authorization: Bearer {jwt_token}

响应： 204 No Content

使用 API Key

在所有经过身份验证的请求中包含 API key：

请求头：

X-MBX-APIKEY: {your_api_key}

EIP-712 签名

关键操作（下单、撤单）需要您的钱包私钥提供的 EIP-712 签名。这确保了平台无法伪造您的订单。

为什么使用 EIP-712？

签名消息人类可读。
类型安全的数据结构。
所有主流钱包均支持的标准。
防止签名重放攻击。

API 接口

交易接口

下单 (Place Order)

接口： POST /orders

频率限制： 每个 API key 每秒 100 个请求

请求头：

X-MBX-APIKEY: {your_api_key}
Content-Type: application/json

请求体：

{
  "symbol": "BTCUSDT",
  "side": "buy",
  "order_type": "limit",
  "price": "50000.00",
  "amount": "0.1",
  "leverage": 10,
  "timestamp": 1673000000,
  "signature": "0x..."
}

参数说明：

参数	类型	必填	描述
symbol	string	是	交易对 (例如 "BTCUSDT", "ETHUSDT")
side	string	是	订单方向：`"buy"` (买入/做多) 或 `"sell"` (卖出/做空)
order_type	string	是	订单类型：`"limit"` (限价) 或 `"market"` (市价)
price	string	是*	订单价格 (*限价单必填)
amount	string	是	基础资产数量 (例如 BTC 数量)
leverage	integer	是	杠杆倍数 (1-100)
timestamp	integer	是	Unix 时间戳（秒），必须在 5 分钟内
signature	string	是	订单的 EIP-712 签名

EIP-712 消息结构： （参考创建 API Key部分的结构，PrimaryType 为 CreateOrder）

响应：

{
  "order_id": "231d4083-a2d2-455c-8af3-a5890978e329",
  "status": "open",
  "filled_amount": "0",
  "remaining_amount": "0.1",
  "average_price": "0",
  "created_at": 1673000000000
}

可能的状态：

pending: 订单已提交至撮合引擎
open: 订单在订单簿中处于活跃状态
partially_filled: 订单部分成交
filled: 订单完全成交
cancelled: 用户已撤单
rejected: 订单被拒绝（如余额不足）

撤单 (Cancel Order)

接口： DELETE /orders/{order_id}

请求体：

{
  "signature": "0x...",
  "timestamp": 1673000000
}

EIP-712 消息结构： （PrimaryType 为 CancelOrder，包含 wallet, orderId, timestamp）

批量撤单 (Batch Cancel Orders)

接口： POST /orders/batch

账户接口

获取账户余额

接口： GET /account/balances

响应：

{
  "USDT": {
    "available": "10000.50",
    "frozen": "500.25",
    "total": "10500.75"
  }
}

获取当前仓位

接口： GET /positions 或 GET /account/positions

获取订单历史 / 成交历史

接口分别为 GET /account/orders 和 GET /account/trades。

错误代码

所有错误均遵循以下格式：

{
  "error": "人类可读的错误消息",
  "code": "ERROR_CODE_CONSTANT"
}

状态码	错误代码	描述
400	`INVALID_SYMBOL`	不支持的交易对
400	`TIMESTAMP_EXPIRED`	时间戳过期（超过 5 分钟）
400	`INSUFFICIENT_BALANCE`	可用余额不足
401	`SIGNATURE_INVALID`	EIP-712 签名验证失败
429	`RATE_LIMIT_EXCEEDED`	请求过于频繁

最佳实践

1. 安全性

🔐 绝不泄露您的私钥、API key 或 secret key。
🔒 将凭据存储在环境变量中，而非代码中。
🌐 创建 API key 时使用 IP 白名单。
🔄 定期更换 API key（建议每月更换）。

2. 频率限制

当前限制：每秒 100 个请求/API key。
推荐使用 WebSocket 获取实时行情，而不是轮询 REST 接口。
对重试逻辑实施指数退避算法。

3. 风险管理

📊 持续监控仓位和未实现盈亏 (PnL)。
🛡️ 确保足够的保证金以避免被强制平仓（爆仓）。
⚖️ 在多个交易对之间进行分散投资。

支持的交易对

XBlade 支持 50 多种永续合约，包括： BTCUSDT, ETHUSDT, SOLUSDT, XRPUSDT, DOGEUSDT, ARBUSDT... 使用 GET /markets 接口获取最新列表。

WebSocket API

测试网： wss://api.8a27.xyz/ws

主网： wss://api.renance.xyz/ws

公共频道

ticker:{symbol}: 价格指数
orderbook:{symbol}: 订单簿
kline:{symbol}:{interval}: K 线图 (1m, 5m, 1h 等)

私有频道（需认证）

positions: 仓位变动
orders: 订单状态更新
balance: 余额变动

支持与反馈

💬 Discord: https://discord.gg/xblade
📧 Email: support@xblade.io
📘 GitHub: https://github.com/XBladeStudio/XBlade_hyper_strcution

最后更新： 2026-01-12

维护方： XBlade 团队

目录​

简介​

核心特性​

快速入门​

前提条件​

网络配置​

代币地址​

快速入门清单​

身份认证​

创建 API Key​

第一步：登录以获取 JWT 令牌​

第二步：创建 API Key​

管理 API Key​

更新 API Key / 绑定 IP 白名单​

删除 API Key​

使用 API Key​

EIP-712 签名​

API 接口​

交易接口​

下单 (Place Order)​

撤单 (Cancel Order)​

批量撤单 (Batch Cancel Orders)​

账户接口​

获取账户余额​

获取当前仓位​

获取订单历史 / 成交历史​

错误代码​

最佳实践​

1. 安全性​

2. 频率限制​

3. 风险管理​

支持的交易对​

WebSocket API​

公共频道​

私有频道（需认证）​

支持与反馈​

目录

简介

核心特性

快速入门

前提条件

网络配置

代币地址

快速入门清单

身份认证

创建 API Key

第一步：登录以获取 JWT 令牌

第二步：创建 API Key

管理 API Key

更新 API Key / 绑定 IP 白名单

删除 API Key

使用 API Key

EIP-712 签名

API 接口

交易接口

下单 (Place Order)

撤单 (Cancel Order)

批量撤单 (Batch Cancel Orders)

账户接口

获取账户余额

获取当前仓位

获取订单历史 / 成交历史

错误代码

最佳实践

1. 安全性

2. 频率限制

3. 风险管理

支持的交易对

WebSocket API

公共频道

私有频道（需认证）

支持与反馈