# TopOne OpenAPI 代理商跟单交易接口(v1)
## 更新日誌
### 2024-11-21
- 增加代理商跟單接口
- 開倉 `POST /gateway/v1/openapi/agent/copy-trading/order`
- 平倉 `POST /gateway/v1/openapi/agent/copy-trading/order/close`
- 倉位清單 `GET /gateway/v1/openapi/future/copy-trading/position`
- 账户余额接口 `GET /gateway/v1/openapi/wallet/copy-trading/balance`
## 基本信息
### 服务器BASE URL
#### 联调环境
- https://pre.top.one
#### 生产环境
- https://top.one
### 接口访问规则
- 需要提前准备APIKEY和APISECRET（申请通过后，TOPONE通过邮件形式发送给代理商）
- 接口请求频率限制为每秒钟10次（单用户下所有APIKEY）
- 每个接口均需使用APIKEY和APISECRET计算签名signature
### 接口签名实现说明
- signature根据每个请求的timestamp, method, path, body计算sha256而来
- 时间戳为当前时间，超过1分钟的请求签名会被拒绝，不建议使用未来时间签名
- 如果是get请求需要忽略body
- path需要包含query字段
#### example-golang
```go
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"fmt"
)
func GenerateSignature(method, path, body string, timestamp int64, secret string) (string, error) {
// 组合签名原文
var message string
if method == "GET" {
message = fmt.Sprintf("%d%s%s", timestamp, method, path)
} else {
message = fmt.Sprintf("%d%s%s%s", timestamp, method, path, body)
}
// 使用 HMAC-SHA256 算法进行签名
h := hmac.New(sha256.New, []byte(secret))
if _, err := h.Write([]byte(message)); err != nil {
return "", err
}
// 返回签名结果
signature := hex.EncodeToString(h.Sum(nil))
return signature, nil
}
```
#### example-python
```python
import hmac
import hashlib
import time
def generate_signature(method, path, body, timestamp, secret):
"""
生成 HMAC-SHA256 签名
Args:
method: HTTP 方法
path: 请求路径
body: 请求体
timestamp: 时间戳
Returns:
str: 签名结果
"""
# 组合签名原文
message = f"{timestamp}{method}{path}"
if method != "GET":
message += body
# 使用 HMAC-SHA256 算法进行签名
signature = hmac.new(secret.encode('utf-8'), message.encode('utf-8'), hashlib.sha256).hexdigest()
return signature
```
#### example-java
```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
public class HmacSha256 {
public static String generateSignature(String method, String path, String body, long timestamp, String secret) throws Exception {
// 组合签名原文
StringBuilder messageBuilder = new StringBuilder();
messageBuilder.append(timestamp).append(method).append(path);
if (!method.equals("GET")) {
messageBuilder.append(body);
}
String message = messageBuilder.toString();
// 使用 HMAC-SHA256 算法进行签名
SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8),"HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(signingKey);
byte[] rawHmac = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
return bytesToHex(rawHmac);
}
private static String bytesToHex(byte[] bytes) {
StringBuilder hexString = new StringBuilder();
for (byte b : bytes) {
String hex = Integer.toHexString(0xff & b);
if (hex.length() == 1) {
hexString.append('0');
}
hexString.append(hex);
}
return hexString.toString();
}
}
```
### 通用返回接口示例
```json
{
"status": {
"code": 102000,
"error": {},
"messages": "success"
},
"data": {
}
}
```
- code = 102000表示请求成功，否则为请求失败
- 接口返回的数据在data字段中
## 代理商跟單-下委託單
### HTTP请求
**Path：** /gateway/v1/openapi/agent/copy-trading/order
**Method：** POST
### 请求参数
#### Headers
| 参数名称 | 参数值 | 是否必须 | 备注 |
| ------------ | ------------ | ------------ | ------------ |
| Content-Type | application/json | 是 | |
|signature|8bde81ceaff50e7fe2a...|是| 簽名|
| X-MBX-APIKEY | ee9aedd6a1b2a3a610fa2b1dab333d46 | 是 | ApiKey |
| timestamp | 1732003370 | 是 | 請求時間戳 |
#### Query
无
#### Body
```json!
{
"pair": "BTCUSDT", // 填入支持带单的币对
"side": "sell", // 目前只支持单向买多卖空，即buy+long，或者sell+short
"position_side": "long", // 参考side字段配置
"margin": 5.0, // 1.0 <= margin <= 1000
"leverage": 1, // 1 <= 杠杆倍数 <= 1000
"take_profit_price": 0.0, // long必须大于市价，short必须小于市价，填0则不触发
"stop_loss_price": 0.0, // long必须小于市价，short必须大于市价，填0则不触发
"price": 0.0, // price=0则为市价单，否则为限价单（需谨慎检查对应价格）
"is_simulate": false // 是否为模拟盘交易
}
```
### 响应示例
```json!
{
"status": {
"code": 102000,
"error": {},
"messages": "success"
},
"data": {
"order_id": "e0bf978a-b383-4e85-ba71-7684f81abcc7",
"position_order_id": "",
"pair": "BTCUSDT",
"contract_type": 1,
"uid": "00000034",
"side": "sell",
"position_side": "long",
"quantity": "0.01682",
"order_quantity": "0.01682",
"leverage": 10,
"price_type": "market",
"price": "59307",
"open_fee": "0",
"pre_close_fee": "0",
"take_profit_price": "0",
"stop_loss_price": "0",
"pay_margin": "100",
"status": 1,
"is_simulate": 0,
"close_time": "",
"create_time": "2024-01-01T12:23:34Z",
"update_time": "2024-01-01T12:23:45Z",
"copy_trade": {
"success": [
{
"order_id": "e0bf978a-b383-4e85-ba71-7684f81abcc7",
"position_order_id": "",
"pair": "BTCUSDT",
"contract_type": 1,
"uid": "00000034",
"side": "sell",
"position_side": "long",
"quantity": "0.01682",
"order_quantity": "0.01682",
"leverage": 10,
"price_type": "market",
"price": "59307",
"open_fee": "0",
"pre_close_fee": "0",
"take_profit_price": "0",
"stop_loss_price": "0",
"pay_margin": "100",
"status": 1,
"is_simulate": 0,
"close_time": "",
"create_time": "2024-01-01T12:23:34Z",
"update_time": "2024-01-01T12:23:45Z"
}
],
"fail": [
"00001",
"00002"
]
}
}
}
```
#### 接口描述
- ~~quantity(數量下單)與margin(保證金下單) 只能擇一選擇~~
- 普通合約才有止盈止損價，得勁沒有
- position_side 多單 止盈>成交價>止損 空單 止盈<成交價<止損
- 會根據leverage自動判斷是普通/得勁合約
<h5>Error</h5>
<table>
<thead>
<tr>
<th>Error Code</th>
<th>Message</th>
</tr>
</thead>
<tbody>
<tr>
<td>836004</td>
<td>保證金不足(餘額不足)</td>
</tr>
<tr>
<td>837000</td>
<td>目前合約無法開倉</td>
</tr>
<tr>
<td>837004</td>
<td>用戶持倉數已滿</td>
</tr>
<tr>
<td>837005</td>
<td>平台持倉數量已達上限</td>
</tr>
<tr>
<td>837006</td>
<td>標記價格於最新價格差價過大</td>
</tr>
<tr>
<td>837007</td>
<td>價格有問題(精度,限價止盈止損價格有問題)</td>
</tr>
<tr>
<td>837010</td>
<td>系統造市正在運作，不可下單</td>
</tr>
<tr>
<td>837011</td>
<td>用戶觸發風控，暫時停止交易</td>
</tr>
<tr>
<td>837002</td>
<td>止盈倍數有問題(超過上限)</td>
</tr>
<tr>
<td>904059</td>
<td>開倉功能被關閉</td>
</tr>
</tbody>
</table>
<h5>contract_type</h5>
<table>
<thead>
<tr>
<th>type</th>
<th>comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>普通合約</td>
</tr>
<tr>
<td>2</td>
<td>閃電合約</td>
</tr>
</tbody>
</table>
<h5>position_side</h5>
<table>
<thead>
<tr>
<th>code</th>
<th>comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>long</td>
<td>多</td>
</tr>
<tr>
<td>short</td>
<td>空</td>
</tr>
</tbody>
</table>
<h5>side</h5>
<table>
<thead>
<tr>
<th>code</th>
<th>comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>buy</td>
<td>買</td>
</tr>
<tr>
<td>sell</td>
<td>賣</td>
</tr>
</tbody>
</table>
<h5>price_type</h5>
<table>
<thead>
<tr>
<th>type</th>
<th>comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>market</td>
<td>市價</td>
</tr>
<tr>
<td>limit</td>
<td>限價</td>
</tr>
</tbody>
</table>
<h5>status</h5>
<table>
<thead>
<tr>
<th>status</th>
<th>comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>未成交</td>
</tr>
<tr>
<td>1</td>
<td>成交</td>
</tr>
<tr>
<td>2</td>
<td>取消</td>
</tr>
<tr>
<td>3</td>
<td>異常</td>
</tr>
</tbody>
</table>
<h5>組合關係</h5>
<table>
<thead>
<tr>
<th>side</th>
<th>position_side</th>
<th>price</th>
<th>comment</th>
</tr>
</thead>
<tbody>
<tr>
<td>buy</td>
<td>long</td>
<td>100</td>
<td>買限價多單</td>
</tr>
<tr>
<td>buy</td>
<td>long</td>
<td>0</td>
<td>買市價多單</td>
</tr>
<tr>
<td>sell</td>
<td>long</td>
<td>100</td>
<td>平倉限價多單</td>
</tr>
<tr>
<td>sell</td>
<td>long</td>
<td>0</td>
<td>平倉市價多單</td>
</tr>
<tr>
<td>buy</td>
<td>short</td>
<td>100</td>
<td>平倉限價空單</td>
</tr>
<tr>
<td>buy</td>
<td>short</td>
<td>0</td>
<td>平倉市價空單</td>
</tr>
<tr>
<td>sell</td>
<td>short</td>
<td>100</td>
<td>買限價空單</td>
</tr>
<tr>
<td>sell</td>
<td>short</td>
<td>0</td>
<td>買市價空單</td>
</tr>
</tbody>
</table>
## 代理商跟單-平倉
### HTTP请求
**Path：** /gateway/v1/openapi/agent/copy-trading/order/close
**Method：** POST
### 请求参数
#### Headers
| 参数名称 | 参数值 | 是否必须 | 备注 |
| ------------ | ------------ | ------------ | ------------ |
| Content-Type | application/json | 是 | |
|signature|8bde81ceaff50e7fe2ad69e...|是| 簽名|
| X-MBX-APIKEY | ee9aedd6a1b2a3a610fa2b1dab333d46 | 是 | ApiKey |
| timestamp | 1732003370 | 是 | 請求時間戳 |
#### Query
无
#### Body
```json!
{
"order_id": "TX0000001" //required
}
```
### 响应示例
```json!
{
"status": {
"code": 102000,
"error": {},
"messages": "success"
},
"data": {
}
}
```
## 代理商跟單-倉位清單
### HTTP请求
**Path：** /gateway/v1/openapi/future/copy-trading/position
**Method：** GET
### 请求参数
#### Headers
| 参数名称 | 参数值 | 是否必须 | 备注 |
| ------------ | ------------ | ------------ | ------------ |
| Content-Type | application/json | 是 | |
|signature|8bde81ceaff50e7fe2ad69e...|是| 簽名|
| X-MBX-APIKEY | ee9aedd6a1b2a3a610fa2b1dab333d46 | 是 | ApiKey |
| timestamp | 1732003370 | 是 | 請求時間戳 |
#### Query
| 参数名称 | 是否必须 | 类型 | 备注 |
| ------------ | ------------ | ------------ | ------------ |
| page_index | 是 | int | 第幾頁(默認1) |
| page_size | 是 | int | 每頁多少筆 |
| status | 否 | int | 倉位狀態 |
| start_time | 否 | int | 建倉開始時間 |
| end_time | 否 | int | 建倉結束時間 |
| pair | 否 | string | 交易對 |
| side | 否 | string | 多/空 |
| is_simulate | 否 | int | 是否為模擬單 默認為(不是) 1:是 2:不是 |
| create_platform | 否 | string | "agent"=帶單, "copy-trade"=跟單 |
| position_id | 否 | string | 倉位ID |
#### Body
無
### 响应示例
```json!
{
"status": {
"code": 102000,
"error": {},
"messages": "success"
},
"data": {
"list": [
{
"order_id": "TX000000001",
"uid": "00001",
"pair": "BTCUSDT",
"crypto": "BTC",
"crypto_price_unit": "USDT",
"side": "long",
"contract_type": 1,
"leverage": 10,
"quantity": "100.1",
"number": 123466,
"price": "529.01",
"price_type": "market",
"take_profit_price": "600.01",
"stop_loss_price": "450.01",
"total_funding_fee": "100",
"init_margin": "100",
"margin": "20.01",
"pay_margin": "120",
"status": 1,
"create_platform": "copy-trade",
"create_time": "2024-05-06T19:23:36Z",
"close_time": "2024-05-06T19:23:36Z"
}
],
"page": {
"total": 1,
"index": 1,
"size": 20
}
}
}
```
### 响应說明
| 名称 | 類型 | 備註 | 示例 |
| ------------ | ------------ | ------------ | ------------ |
| order_id | string | 訂單ID | |
| uid | string | 用戶ID | |
| pair | string | 幣對 | BTCUSDT |
| crypto | string | 交易幣 | BTC |
| crypto_price_unit | string | 計價幣 | USDT |
| side | string | 方向 | |
| contract_type | number | 合約類型 | |
| leverage | number | 槓桿倍數 | |
| quantity | string | 數量(幣量) | |
| number | number |總張數=數量/每張多少單位 | |
| price | string | 開倉價 | |
| price_type | string | 下單價格類型(市價/限價) | |
| close_price | string | 平倉價 | |
| take_profit_price | string | 止盈價 | |
| stop_loss_price | string | 止損價 | |
| total_funding_fee | string | 資金費 | |
| margin | string | 倉位保證金 | |
| init_margin | string | 倉位佔用保證金 | |
| pay_margin | string | 開倉成本(開倉保證金) | |
| status | number | 倉位狀態 | 1=開倉中, 2=已平倉 |
| create_platform | string | 開單平台 | "agent"=帶單, "copy-trade"=跟單 |
| create_time | string | 撮合/建立時間 | |
| close_time | string | 平倉時間 | |
## 代理商跟單-账户余额
### HTTP请求
**Path：** /gateway/v1/openapi/wallet/copy-trading/balance
**Method：** GET
### 请求示例
#### Headers
| 参数名称 | 参数值 | 是否必须 | 备注 |
| ------------ | ------------ | ------------ | ------------ |
| Content-Type | application/json | 是 | |
|signature|8bde81ceaff50e7fe2ad69e...|是| 簽名|
| X-MBX-APIKEY | ee9aedd6a1b2a3a610fa2b1dab333d46 | 是 | ApiKey |
| timestamp | 1732003370 | 是 | 請求時間戳 |
#### Query
無
#### Body
無
### 响应示例
```json!
{
"status": {
"code": 102000,
"error": {},
"messages": "success"
},
"data": {
"list": [
{
"uid": "OOOOOTRU",
"trading_available": "999016.0075683", // 合約帳戶可用金額
"trading_freeze": "0", // 合約帳戶凍結保證金
"realized_profit_and_loss": "0" // 已實現盈虧金額
},
{
"uid": "OOOOJOKT",
"trading_available": "0",
"trading_freeze": "0",
"realized_profit_and_loss": "0"
},
{
"uid": "OOOOOEDV",
"trading_available": "99000000",
"trading_freeze": "0",
"realized_profit_and_loss": "0"
},
{
"uid": "OOOOOEJV",
"trading_available": "0",
"trading_freeze": "0",
"realized_profit_and_loss": "0"
}
]
}
}
```
Sign in with Wallet
Connect another wallet