> For the complete documentation index, see [llms.txt](https://top-one-1.gitbook.io/openapi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://top-one-1.gitbook.io/openapi/wen-dang-shuo-ming.md).

# 文档说明

## <mark style="color:blue;">**API基本信息**</mark>

1. 钱包REST接口 baseurl：`openapi.top.one`
2. 所有接口都会返回一个 JSON，可以是 object 或 array
3. 所有时间和时间戳均为 Unix 时间，单位为 毫秒。

## <mark style="color:blue;">**文档入参规范**</mark>

接口对入参字符大小写敏感，在接口中会明确指明。 如写明需要输入大写的币对名称，则需要输入 BTCUSDT，输入小写的 btcusdt 是不被允许的。

文档中的入参有明确的类型说明，需要按照指定的类型输入。 如 integer 类型只能输入数字类型，3 的输入是正确的，但 "3" 的输入是不被允许的。

## <mark style="color:blue;">**接口通用信息**</mark>

1. 所有请求基于 Https 协议，请求头信息中 Content-Type 需要统一设置为：'application/json'。
2. GET 方法的接口，参数必须在 query string 中发送。
3. POST 方法的接口，参数必须在 request body 中发送。
4. 对参数的顺序不做要求。

## <mark style="color:blue;">**权限限制**</mark>

接口类型分为：公共、读取、合约、划转、提现。

1. 公共接口无权限限制。
2. 读取、合约、划转、提现接口都需要在用户中心修改api获得对应权限。
3. 90天内没有资金操作（划转、提现）的apiKey将进入休眠状态，变为只有读取权限。

## <mark style="color:blue;">**访问限制**</mark>

违反频率限制都会收到 HTTP 429，这是一个警告。

当收到 HTTP 429 告警时，调用者应当降低访问频率或者停止访问。

1. 用户的所有key使用同一个限频：**1秒20次**
2. 下单限频 : **2秒20次**

## <mark style="color:blue;">**时间同步安全**</mark>

签名接口均需要在HTTP头中以 **X-Time** 字段传递时间戳

其值应当是请求发送时刻的Unix时间戳（毫秒）\
服务器收到请求时会判断请求中的时间戳，如果是 5000 毫秒之前发出的，则请求会被认为无效。

## <mark style="color:blue;">**签名验证**</mark>

### **接口示例**

以 "获取时区" 接口的 为例

调用api时应该在HTTP头中添加字段

| 参数             | 示例                                                               | 说明     |
| -------------- | ---------------------------------------------------------------- | ------ |
| X-Time         | 1748095101543                                                    | 时间戳    |
| X-Openapi-Key  | 21eae2aacac7baab6e4aaff3587a4aa5                                 | apikey |
| X-Openapi-Sign | 4df61f81c34e9cef755cb0d6169fcbb464efa518089e9a017e686e605eba06dc | 验签签名   |

### **签名方式 SHA256**

X-Openapi-Sign = SHA256(Method=%s\&Path=%s\&Timestamp=%s\&Secret=%s)

以 "获取时区" 接口的为例签名字符串：

Method=GET\&Path=/api/v1/server-time\&Timestamp=1748095101543\&Secret=1533a8d407b17ddd4ecdd3cdbc37bf34c4a47beabca0a97bff00b253a0683ce2

| 参数        | 示例                                                               | 说明        |
| --------- | ---------------------------------------------------------------- | --------- |
| Method    | GET                                                              | 请求方式      |
| Path      | /api/v1/server-time                                              | url       |
| Timestamp | 1748095101543                                                    | 时间戳       |
| Secret    | 1533a8d407b17ddd4ecdd3cdbc37bf34c4a47beabca0a97bff00b253a0683ce2 | apiSecret |

### **HTTP返回代码的类型**

1. HTTP 4XX 错误码用于指示错误的请求内容、行为、格式。
2. HTTP 429 错误码表示警告访问频次超限。
3. HTTP 5XX 返回错误码是内部系统错误；这说明这个问题是在服务器这边。在对待这个错误时，千万不要把它当成一个失败的任务，因为执行状态未知，有可能是成功也有可能是失败。

### **返回码类型**

| code | msg                         | 说明                              |
| ---- | --------------------------- | ------------------------------- |
| 1001 | openapi key not exist       | 请求头中缺少 X-Openapi-Key 或者 key 不存在 |
| 1002 | request timeout             | 请求头中缺少 X-Time 或者 超时             |
| 1003 | insufficient permissions    | 权限不足                            |
| 1004 | IP access restricted        | IP受限                            |
| 1005 | signature validation failed | 签名错误                            |
| 1006 | account has been banned     | 用户被封禁                           |