交易 API (Trading API)

Version: v1.1 Last Updated: 2026-01-20

概述

AXBlade Trading API 提供永续合约交易功能，支持最高 50 倍杠杆。所有交易操作需要 EIP-712 签名认证。

认证

所有交易端点需要 JWT 认证，在请求头中包含 token：

Authorization: Bearer <jwt_token>

订单 API

创建订单

POST /api/v1/orders

创建限价单或市价单。

请求体：

{
  "symbol": "HYPEUSDT",
  "side": "buy",
  "order_type": "limit",
  "price": "25.50",
  "amount": "10.0",
  "leverage": 10,
  "timestamp": 1704067200,
  "signature": "0x..."
}

参数：

参数	类型	必需	描述
symbol	string	是	交易对 (如 "HYPEUSDT")
side	string	是	订单方向: "buy" 或 "sell"
order_type	string	是	订单类型: "limit" 或 "market"
price	string	限价单必需	限价单价格
amount	string	是	订单数量
leverage	integer	是	杠杆倍数 (1-50)
timestamp	integer	是	Unix 时间戳 (秒)
signature	string	是	EIP-712 签名

EIP-712 签名结构：

const types = {
  CreateOrder: [
    { name: "wallet", type: "address" },
    { name: "symbol", type: "string" },
    { name: "side", type: "string" },
    { name: "orderType", type: "string" },
    { name: "price", type: "string" },
    { name: "amount", type: "string" },
    { name: "leverage", type: "uint32" },
    { name: "timestamp", type: "uint256" }
  ]
};

const message = {
  wallet: userAddress,
  symbol: "HYPEUSDT",
  side: "buy",        // 小写
  orderType: "limit", // 小写
  price: "25.50",     // 市价单为 "0"
  amount: "10.0",
  leverage: 10,
  timestamp: Math.floor(Date.now() / 1000)
};

响应：

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "filled",
  "filled_amount": "10.0",
  "remaining_amount": "0",
  "average_price": "25.48",
  "created_at": 1704067200000
}

订单状态：

状态	描述
pending	订单已创建，尚未进入订单簿
open	订单在订单簿中，等待撮合
partially_filled	部分成交
filled	完全成交
cancelled	用户取消
rejected	系统拒绝

获取订单

GET /api/v1/orders/:order_id

获取特定订单详情。

响应：

{
  "order_id": "550e8400-e29b-41d4-a716-446655440000",
  "symbol": "HYPEUSDT",
  "side": "buy",
  "order_type": "limit",
  "price": "25.50",
  "amount": "10.0",
  "filled_amount": "10.0",
  "remaining_amount": "0",
  "leverage": 10,
  "status": "filled",
  "created_at": "2026-01-01T12:00:00Z"
}

取消订单

DELETE /api/v1/orders/:order_id

取消挂单或部分成交的订单。

请求体：

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

EIP-712 签名结构：

const types = {
  CancelOrder: [
    { name: "wallet", type: "address" },
    { name: "orderId", type: "string" },
    { name: "timestamp", type: "uint256" }
  ]
};

const message = {
  wallet: userAddress,
  orderId: "550e8400-e29b-41d4-a716-446655440000",
  timestamp: Math.floor(Date.now() / 1000)
};

批量取消订单

POST /api/v1/orders/batch

单次请求取消多个订单。

请求体：

{
  "order_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "signature": "0x...",
  "timestamp": 1704067200
}

响应：

{
  "cancelled": ["550e8400-e29b-41d4-a716-446655440000"],
  "failed": ["550e8400-e29b-41d4-a716-446655440001"]
}

仓位 API

仓位列表

GET /api/v1/positions

获取当前用户所有持仓。

响应：

{
  "positions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "symbol": "HYPEUSDT",
      "side": "long",
      "size_in_tokens": "10.0",
      "size_in_usd": "255.00",
      "entry_price": "25.50",
      "mark_price": "26.00",
      "liquidation_price": "23.10",
      "margin": "25.50",
      "leverage": 10,
      "unrealized_pnl": "5.00",
      "realized_pnl": "0",
      "status": "open",
      "created_at": "2026-01-01T12:00:00Z"
    }
  ]
}

获取仓位

GET /api/v1/positions/:position_id

获取特定仓位详情。

开仓

POST /api/v1/positions

直接开仓（替代创建订单的方式）。

请求体：

{
  "symbol": "HYPEUSDT",
  "side": "long",
  "size": "10.0",
  "leverage": 10,
  "timestamp": 1704067200,
  "signature": "0x..."
}

平仓

POST /api/v1/positions/:position_id/close

关闭持仓。

请求体：

{
  "amount": "10.0",
  "timestamp": 1704067200,
  "signature": "0x..."
}

追加保证金

POST /api/v1/positions/:position_id/collateral/add

追加保证金以降低清算风险。

请求体：

{
  "amount": "100.00",
  "timestamp": 1704067200,
  "signature": "0x..."
}

减少保证金

POST /api/v1/positions/:position_id/collateral/remove

从仓位中减少多余保证金。

请求体：

{
  "amount": "50.00",
  "timestamp": 1704067200,
  "signature": "0x..."
}

检查清算

GET /api/v1/positions/:position_id/liquidation

检查仓位是否面临清算风险。

响应：

{
  "is_liquidatable": false,
  "margin_ratio": "0.15",
  "maintenance_margin": "0.05",
  "liquidation_price": "23.10",
  "current_price": "26.00"
}

条件单 (止盈/止损)

条件单是独立系统

条件单与普通订单是完全分离的两套系统：

系统	API 路径	数据库表	包含类型
普通订单	`/api/v1/orders`	`orders`	limit, market
条件单	`/api/v1/trigger-orders`	`trigger_orders`	take_profit, stop_loss, trailing_stop

前端必须分别查询这两个接口才能展示用户的所有订单！

详细文档请参阅 止盈止损 API 文档。

创建条件单

POST /api/v1/trigger-orders

创建止损或止盈订单。

请求体：

{
  "symbol": "HYPEUSDT",
  "side": "sell",
  "trigger_type": "stop_loss",
  "trigger_price": "24.00",
  "amount": "10.0",
  "timestamp": 1704067200,
  "signature": "0x..."
}

条件单类型：

类型	描述
stop_loss	价格跌破触发价时执行
take_profit	价格涨过触发价时执行
stop_limit	止损限价单
trailing_stop	追踪止损

仓位止盈止损 (Position TP/SL)

关于持仓止盈止损的详细 CRUD 接口说明，请参阅专门的止盈止损文档。

条件单列表

GET /api/v1/trigger-orders

获取所有活跃的条件单。

取消条件单

DELETE /api/v1/trigger-orders/:order_id

取消条件单。

账户 API

获取资料

GET /api/v1/account/profile

获取用户资料信息。

获取余额

GET /api/v1/account/balances

获取账户余额。

响应：

{
  "balances": [
    {
      "token": "USDT",
      "available": "1000.00",
      "frozen": "100.00",
      "total": "1100.00"
    }
  ]
}

获取用户订单

GET /api/v1/account/orders

获取用户所有普通订单（限价单、市价单）。

重要提示

此接口只返回普通订单，不包含止盈止损等条件单！

条件单（止盈、止损、追踪止损）存储在独立的 trigger_orders 表中，必须通过 /api/v1/trigger-orders 接口查询。

详见止盈止损 API 文档。

查询参数：

参数	类型	描述
symbol	string	按交易对筛选
status	string	按状态筛选
limit	integer	最大结果数 (默认: 50)
offset	integer	分页偏移

获取用户成交

GET /api/v1/account/trades

获取用户成交历史。

市场数据 API (公开)

市场列表

GET /api/v1/markets

获取所有可用交易对。

响应：

{
  "markets": [
    {
      "symbol": "HYPEUSDT",
      "base_asset": "HYPE",
      "quote_asset": "USDT",
      "status": "trading",
      "min_order_size": "0.1",
      "max_leverage": 50,
      "maker_fee": "0.0002",
      "taker_fee": "0.0005"
    }
  ]
}

获取订单簿

GET /api/v1/markets/:symbol/orderbook

获取订单簿深度。

查询参数：

参数	类型	描述
depth	integer	档位数量 (默认: 20)

响应：

{
  "symbol": "HYPEUSDT",
  "bids": [
    ["25.45", "100.5"],
    ["25.44", "200.3"]
  ],
  "asks": [
    ["25.46", "150.2"],
    ["25.47", "180.1"]
  ],
  "timestamp": 1704067200000
}

获取最近成交

GET /api/v1/markets/:symbol/trades

获取最近成交记录。

查询参数：

参数	类型	描述
limit	integer	最大结果数 (默认: 50)

响应：

{
  "trades": [
    {
      "id": "123456",
      "price": "25.45",
      "amount": "10.0",
      "side": "buy",
      "timestamp": 1704067200000
    }
  ]
}

获取行情

GET /api/v1/markets/:symbol/ticker

获取 24 小时行情统计。

响应：

{
  "symbol": "HYPEUSDT",
  "last_price": "25.45",
  "price_change": "0.50",
  "price_change_percent": "2.00",
  "high_24h": "26.00",
  "low_24h": "24.50",
  "volume_24h": "1000000.00",
  "quote_volume_24h": "25450000.00",
  "open_interest": "5000000.00",
  "funding_rate": "0.0001",
  "next_funding_time": 1704096000000
}

获取价格

GET /api/v1/markets/:symbol/price

获取当前标记价格。

响应：

{
  "symbol": "HYPEUSDT",
  "price": "25.45",
  "timestamp": 1704067200000
}

错误码

错误码	HTTP 状态	描述
INVALID_SYMBOL	400	不支持的交易对
INVALID_LEVERAGE	400	杠杆超出范围 (1-50)
INVALID_AMOUNT	400	无效订单数量
PRICE_REQUIRED	400	限价单需要价格
TIMESTAMP_EXPIRED	400	签名时间戳过期
SIGNATURE_INVALID	401	EIP-712 签名验证失败
INSUFFICIENT_BALANCE	400	可用余额不足
ORDER_NOT_FOUND	404	订单不存在
ORDER_NOT_OWNED	403	无权操作此订单
ORDER_NOT_CANCELLABLE	400	订单无法取消
POSITION_NOT_FOUND	404	仓位不存在
MATCHING_ERROR	500	撮合引擎错误

交易配置

支持的交易对

交易对	基础资产	报价资产	最大杠杆
HYPEUSDT	HYPE	USDT	50x
BTCUSDT	BTC	USDT	50x
ETHUSDT	ETH	USDT	50x

费率结构

类型	费率
Maker 费率	0.02%
Taker 费率	0.05%
资金费率	动态 (8小时间隔)

保证金要求

初始保证金: 仓位价值 / 杠杆
维持保证金: 仓位价值的 5%
清算阈值: 保证金比率 < 维持保证金

TypeScript 示例

import { ethers } from 'ethers';

const API_BASE = 'https://api.axblade.com/api/v1';

const domain = {
  name: "AXBlade",
  version: "1",
  chainId: 421614,
  verifyingContract: "0xFDe43f8e6e082975d246844DEF4fE8E704403d43"
};

const createOrderTypes = {
  CreateOrder: [
    { name: "wallet", type: "address" },
    { name: "symbol", type: "string" },
    { name: "side", type: "string" },
    { name: "orderType", type: "string" },
    { name: "price", type: "string" },
    { name: "amount", type: "string" },
    { name: "leverage", type: "uint32" },
    { name: "timestamp", type: "uint256" }
  ]
};

async function createLimitOrder(
  signer: ethers.Signer,
  jwtToken: string,
  symbol: string,
  side: 'buy' | 'sell',
  price: string,
  amount: string,
  leverage: number
) {
  const address = await signer.getAddress();
  const timestamp = Math.floor(Date.now() / 1000);

  const message = {
    wallet: address.toLowerCase(),
    symbol,
    side,
    orderType: 'limit',
    price,
    amount,
    leverage,
    timestamp
  };

  const signature = await signer.signTypedData(
    domain,
    createOrderTypes,
    message
  );

  const response = await fetch(`${API_BASE}/orders`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${jwtToken}`
    },
    body: JSON.stringify({
      symbol,
      side,
      order_type: 'limit',
      price,
      amount,
      leverage,
      timestamp,
      signature
    })
  });

  return response.json();
}

// 使用示例
const order = await createLimitOrder(
  signer,
  jwtToken,
  'HYPEUSDT',
  'buy',
  '25.50',
  '10.0',
  10
);
console.log('订单已创建:', order.order_id);

更新日志

版本	日期	变更
v1.1	2026-01-20	添加重要提示：条件单与普通订单分离说明
v1.0	2026-01-06	初始版本

概述​

认证​

订单 API​

创建订单​

获取订单​

取消订单​

批量取消订单​

仓位 API​

仓位列表​

获取仓位​

开仓​

平仓​

追加保证金​

减少保证金​

检查清算​

条件单 (止盈/止损)​

创建条件单​

仓位止盈止损 (Position TP/SL)​

条件单列表​

取消条件单​

账户 API​

获取资料​

获取余额​

获取用户订单​

获取用户成交​

市场数据 API (公开)​

市场列表​

获取订单簿​

获取最近成交​

获取行情​

获取价格​

错误码​

交易配置​

支持的交易对​

费率结构​

保证金要求​

TypeScript 示例​

相关文档​

更新日志​

概述

认证

订单 API

创建订单

获取订单

取消订单

批量取消订单

仓位 API

仓位列表

获取仓位

开仓

平仓

追加保证金

减少保证金

检查清算

条件单 (止盈/止损)

创建条件单

仓位止盈止损 (Position TP/SL)

条件单列表

取消条件单

账户 API

获取资料

获取余额

获取用户订单

获取用户成交

市场数据 API (公开)

市场列表

获取订单簿

获取最近成交

获取行情

获取价格

错误码

交易配置

支持的交易对

费率结构

保证金要求

TypeScript 示例

相关文档

更新日志