API 参考¶

常见概念 ¶

交易量、价格、订单类型和有效期

交易量¶

交易量以美分（0.0000001 手的单位）指定。

手数	交易量（美分）
0.01	`100,000`
0.1	`1,000,000`
1.0	`10,000,000`

价格¶

价格值以点子表示。转换方式：display_price = pipette_value / 10^pipDigits

对于 EURUSD（5 位数字），点子值 112345 = 1.12345。

订单类型¶

类型	描述	必填字段
`MARKET`	以当前价格立即执行	`symbolId`、`tradeSide`、`volume`
`LIMIT`	以限价或更优价格执行	+ `limitPrice`
`STOP`	当市场达到止损价时触发	+ `stopPrice`
`MARKET_RANGE`	在价格范围内执行	+ `baseSlippagePrice`
`STOP_LIMIT`	在止损价触发的限价单	+ `stopPrice`、`limitPrice`

有效期¶

策略	描述
`GOOD_TILL_CANCEL`	订单保持活跃状态，直到成交或取消
`GOOD_TILL_DATE`	订单在指定的 `expirationTimestamp` 到期
`IMMEDIATE_OR_CANCEL`	立即成交可用部分，取消其余部分

账户信息 ¶

GET /v1/balance Get account balance

返回账户余额、净值和可用保证金。

参数

无参数。

响应

200 成功响应

Response body

{
  "balance": 10000.00,
  "equity": 10250.75,
  "freeMargin": 9800.50,
  "balanceVersion": 42,
  "moneyDigits": 2,
  "depositAssetId": 1
}

字段	类型	描述
`balance`	double	以存款货币计的账户余额
`equity`	double	余额 + 浮动盈亏
`freeMargin`	double	可用于新交易的保证金
`balanceVersion`	int64	余额版本计数器
`moneyDigits`	int32	货币值的小数位数
`depositAssetId`	int64	存款货币资产 ID

GET /v1/symbols 获取可用交易品种

返回账户上所有可供交易的交易品种。

参数

无参数。

响应

200 Symbol 对象数组

Response body

[
  {
    "symbolId": 1,
    "symbolName": "EURUSD",
    "enabled": true,
    "baseAssetId": 2,
    "quoteAssetId": 1,
    "description": "Euro vs US Dollar"
  }
]

Symbol

字段	类型	描述
`symbolId`	int64	交易品种 ID（用于其他 API 调用）
`symbolName`	string	交易品种名称（例如，"EURUSD"）
`enabled`	boolean	该交易品种是否可交易
`baseAssetId`	int64	基础资产 ID
`quoteAssetId`	int64	报价资产 ID
`description`	string	可读描述

GET /v1/assets 获取可用资产

返回可用资产（货币）。

参数

无参数。

响应

200 Asset 对象数组

Response body

[
  {
    "assetId": 1,
    "name": "USD",
    "displayName": "US Dollar"
  }
]

Asset

字段	类型	描述
`assetId`	int64	资产 ID
`name`	string	资产代码（例如，"USD"）
`displayName`	string	显示名称

市场数据 ¶

GET /v1/prices 获取现货价格

返回指定交易品种的当前买入/卖出价格。这是一个快照 – API 不支持流式传输。

参数

名称	位于	类型	必填	描述
`symbolId`	query	int64[]		逗号分隔的交易品种 ID

响应

200 SpotPrice 对象数组

Response body

[
  {
    "symbolId": 1,
    "bid": 112340,
    "ask": 112355,
    "high": 112890,
    "low": 111950,
    "sessionClose": 112100,
    "timestamp": 1700000000000
  }
]

SpotPrice

字段	类型	描述
`symbolId`	int64	符号 ID
`bid`	int64	最佳买入价格（点子）
`ask`	int64	最佳卖出价格（点子）
`high`	int64	交易时段最高价（点子）
`low`	int64	交易时段最低价（点子）
`sessionClose`	int64	上一交易时段收盘价（点子）
`timestamp`	int64	报价时间戳（纪元毫秒）

GET /v1/trendbars 获取历史 OHLCV 数据

返回交易品种的历史烛台图（OHLCV）数据。

参数

名称	位于	类型	默认	描述
`symbolId`	query	int64	–	符号 ID
`period`	query	string	–	K线周期
`fromTimestamp`	query	string	–	开始时间 (ISO-8601)
`toTimestamp`	query	string	–	结束时间 (ISO-8601)
`count`	query	int32	`100`	返回的最大K线数量

可用周期

M_1 M_2 M_3 M_4 M_5 M_10 M_15 M_30 H_1 H_2 H_3 H_4 H_6 H_8 H_12 D_1 W_1 MN_1

响应

200 Trendbar 对象数组

Response body

[
  {
    "timestamp": 1700000000000,
    "open": 112340.0,
    "high": 112890.0,
    "low": 111950.0,
    "close": 112500.0,
    "volume": 4521
  }
]

Trendbar

字段	类型	描述
`timestamp`	int64	K线开盘时间 (纪元毫秒)
`open`	double	开盘价 (点值)
`high`	double	最高价 (点值)
`low`	double	最低价 (点值)
`close`	double	收盘价 (点值)
`volume`	int64	跳动量

订单 ¶

POST /v1/orders 下新订单

下新的交易订单。返回 ExecutionResponse。

参数

无路径或查询参数。

请求正文 application/json

字段	类型	描述
`symbolId`	int64	交易的交易品种
`orderType`	string	`MARKET`, `LIMIT`, `STOP`, `MARKET_RANGE`, `STOP_LIMIT`
`tradeSide`	string	`BUY` 或 `SELL`
`volume`	int64	以分为单位的交易量
`limitPrice`	double	限价 – `LIMIT`、`STOP_LIMIT` 必填
`stopPrice`	double	止损触发价 – `STOP`、`STOP_LIMIT` 必填
`stopLoss`	double	止损价格
`takeProfit`	double	止盈价格
`comment`	string	自由文本备注 (最多 256 个字符)
`label`	string	机器人标签 (最多 100 个字符)
`timeInForce`	string	`GOOD_TILL_CANCEL`, `GOOD_TILL_DATE`, `IMMEDIATE_OR_CANCEL`
`baseSlippagePrice`	double	滑点基准价 – `MARKET_RANGE` 必填
`slippageInPoints`	int32	最大滑点(点数)
`expirationTimestamp`	int64	到期时间戳 (纪元毫秒) – 用于 `GOOD_TILL_DATE`

Example request body

{
  "symbolId": 1,
  "orderType": "MARKET",
  "tradeSide": "BUY",
  "volume": 10000000,
  "stopLoss": 112000,
  "takeProfit": 113000
}

响应

200 ExecutionResponse – 订单已接受或已成交

400 INVALID_REQUEST 或 TRADING_BAD_VOLUME

422 NOT_ENOUGH_MONEY

409 MARKET_CLOSED

Example success response

{
  "orderId": 12345,
  "positionId": 67890,
  "executionType": "ORDER_FILLED",
  "order": { "..." : "..." },
  "position": { "..." : "..." },
  "deal": { "..." : "..." }
}

GET /v1/orders 获取挂单

返回所有挂单(未成交订单)。

参数

无参数。

响应

200 挂单 Order 对象数组

PUT /v1/orders/{orderId} 修改挂单

修改现有挂单。返回 ExecutionResponse。

参数

名称	位于	类型	必填	描述
`orderId`	path	int64		要修改的订单

请求正文 application/json

以下字段的任意子集。

字段	类型	描述
`volume`	int64	新交易量(美分)
`limitPrice`	double	新限价
`stopPrice`	double	新止损价
`stopLoss`	double	新止损价
`takeProfit`	double	新止盈价
`expirationTimestamp`	int64	新到期时间戳 (纪元毫秒)

响应

200 ExecutionResponse 带 ORDER_REPLACED

404 未找到订单

DELETE /v1/orders/{orderId} 取消挂单

取消挂单。返回 ExecutionResponse。

参数

名称	位于	类型	必填	描述
`orderId`	path	int64		要取消的订单

响应

200 ExecutionResponse 带 ORDER_CANCELLED

404 未找到订单

GET /v1/orders/history 获取订单历史

返回时间范围内的历史订单。

参数

名称	位于	类型	必填	描述
`fromTimestamp`	query	string		开始时间 (ISO-8601)
`toTimestamp`	query	string		结束时间 (ISO-8601)

响应

200 OrderListResponse

字段	类型	描述
`orders`	Order[]	历史订单数组
`hasMore`	boolean	是否有其他页面可用

持仓 ¶

GET /v1/positions 获取未平仓头寸

返回所有未平仓头寸和挂单。

参数

无参数。

响应

200 Position 对象数组

Response body

[
  {
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "entryPrice": 112345.0,
    "stopLoss": 112000.0,
    "takeProfit": 113000.0,
    "unrealizedPnl": 155.25,
    "commission": -7.00,
    "swap": -1.20
  }
]

头寸

字段	类型	描述
`positionId`	int64	头寸 ID
`symbolId`	int64	符号 ID
`tradeSide`	string	`BUY` 或 `SELL`
`volume`	int64	以分为单位的交易量
`entryPrice`	double	VWAP 入场价格
`stopLoss`	double	止损价格
`takeProfit`	double	止盈价格
`unrealizedPnl`	double	浮动盈亏
`commission`	double	已收取的佣金
`swap`	double	掉期金额

GET /v1/positions/{positionId} 获取头寸明细

返回头寸及其相关订单和成交。

参数

名称	位于	类型	必填	描述
`positionId`	path	int64		头寸 ID

响应

200 PositionDetailResponse

字段	类型	描述
`position`	Position	Position 对象
`orders`	Order[]	相关订单
`deals`	Deal[]	相关成交

PUT /v1/positions/{positionId} 修改头寸止损/止盈

更新未平仓头寸的止损和/或止盈。返回 ExecutionResponse。

参数

名称	位于	类型	必填	描述
`positionId`	path	int64		头寸 ID

请求正文 application/json

字段	类型	描述
`stopLoss`	double	新止损价格（`null` 表示移除）
`takeProfit`	double	新止盈价格（`null` 表示移除）
`trailingStopLoss`	boolean	启用移动止损

Example request body

{
  "stopLoss": 111500,
  "takeProfit": 113500,
  "trailingStopLoss": false
}

响应

200 ExecutionResponse

POST /v1/positions/{positionId}/close 平仓头寸

全部或部分平仓未平仓头寸。使用小于头寸完整交易量的值进行部分平仓。返回 ExecutionResponse。

参数

名称	位于	类型	必填	描述
`positionId`	path	int64		头寸 ID

请求正文 application/json

字段	类型	必填	描述
`volume`	int64		要平仓的交易量（以美分为单位）

Example – full close (1 lot)

{
  "volume": 10000000
}

响应

200 ExecutionResponse

422 NOT_ENOUGH_MONEY – 部分平仓的保证金不足

交易 ¶

GET /v1/deals 获取成交历史

返回时间范围内已执行的成交。

参数

名称	位于	类型	默认	描述
`fromTimestamp`	query	string	–	开始时间 (ISO-8601)
`toTimestamp`	query	string	–	结束时间 (ISO-8601)
`maxRows`	query	int32	`50`	返回的最大成交数

响应

200 Deal 对象数组

Response body

[
  {
    "dealId": 11111,
    "orderId": 12345,
    "positionId": 67890,
    "symbolId": 1,
    "tradeSide": "BUY",
    "volume": 10000000,
    "filledVolume": 10000000,
    "executionPrice": 112345.0,
    "executionTimestamp": 1700000000000,
    "dealStatus": "FILLED",
    "commission": -7.00
  }
]

Deal

字段	类型	描述
`dealId`	int64	交易 ID
`orderId`	int64	触发此成交的订单
`positionId`	int64	头寸 ID
`symbolId`	int64	符号 ID
`tradeSide`	string	`BUY` 或 `SELL`
`volume`	int64	请求的交易量（以美分为单位）
`filledVolume`	int64	已成交交易量（以美分为单位）
`executionPrice`	double	执行价格
`executionTimestamp`	int64	执行时间（纪元毫秒）
`dealStatus`	string	状态 – 见下方值
`commission`	double	已收取的佣金

dealStatus 值

价值	含义
`FILLED`	订单完全成交
`PARTIALLY_FILLED`	订单已部分成交
`REJECTED`	被交易服务器拒绝
`INTERNALLY_REJECTED`	在到达服务器之前被内部拒绝
`ERROR`	执行期间发生错误
`MISSED`	订单错过（例如，市场跳空）

架构 { #execution-response-schema } ¶

ExecutionResponse ¶

所有订单下单、修改和取消操作都返回此对象。

字段	类型	描述
`orderId`	int64	受影响的订单 ID
`positionId`	int64	受影响头寸 ID
`executionType`	string	结果类型 – 见下方值
`order`	Order	订单详情（如适用）
`position`	Position	持仓详情（如适用）
`deal`	Deal	交易详情（如适用）

executionType 值

价值	含义
`ORDER_ACCEPTED`	挂单已接受
`ORDER_FILLED`	订单完全成交
`ORDER_REPLACED`	订单已修改
`ORDER_CANCELLED`	订单已取消
`ORDER_EXPIRED`	订单已到期
`ORDER_REJECTED`	订单被拒绝
`ORDER_CANCEL_REJECTED`	取消请求被拒绝
`ORDER_PARTIAL_FILL`	订单已部分成交
`SWAP`	持仓掉期已应用
`DEPOSIT`	账户入金
`WITHDRAW`	账户出金
`BONUS_DEPOSIT_WITHDRAW`	赠金入金或出金

速率限制 ¶

网关在多个级别强制执行速率限制。

级别	描述
每个 IP	限制来自单个 IP 地址的总请求数
每个用户	限制单个令牌所有账户的总请求数
每个账户	限制针对单个交易账户的请求数

超出速率限制

当超出速率限制时，API 返回 429 Too Many Requests 并带有 Retry-After 标头。

错误处理 ¶

当请求失败时，API 返回 JSON 错误响应。

Error response format

{
  "error": {
    "code": "NOT_ENOUGH_MONEY",
    "message": "Insufficient free margin for this order",
    "httpStatus": 422,
    "retryAfter": null
  }
}

错误代码 ¶

代码	HTTP	描述
`INVALID_REQUEST`	400	无效或缺失的请求参数
`UNAUTHORIZED`	401	无效、过期或缺失的令牌
`TRADING_BAD_VOLUME`	400	交易量无效（低于最小值或超过持仓）
`NOT_ENOUGH_MONEY`	422	可用保证金不足
`SYMBOL_NOT_FOUND`	404	品种 ID 不存在
`MARKET_CLOSED`	409	该品种的市场当前已关闭
`MAINTENANCE`	503	交易服务器处于维护模式
`TIMEOUT`	504	交易服务器未及时响应
`GATEWAY_RATE_LIMIT`	429	超出速率限制 – 见 `Retry-After` 标头

速率限制处理

当您收到 429 响应时，Retry-After 标头和 retryAfter 字段指示您在发送下一个请求之前需要等待的秒数。