入门指引
欢迎使用CRYPTEX GLOBAL开发者文档。此文档目前为V3 Beta版，会继续更新，请大家及时关注。
此文档为用户提供了一整套简单而又强大的开发工具，旨在帮助用户快速、高效地将CRYPTEX GLOBAL交易功能整合到自己的应用当中。
CRYPTEX GLOBAL接口是提供服务的基础，API分为账户、交易和行情三类。开发者在CRYPTEX GLOBAL网站创建账号后，可以根据自身需求建立不同权限的API，并利用API进行自动交易或者提现。
账户和交易API需要身份验证，提供下单、撤单，查询订单和帐户信息等功能。行情API提供市场的行情数据，所有行情接口都是公开的。
接口调用方式说明
CRYPTEX GLOBAL为用户提供两种调用接口的方式，开发者可根据自己的使用场景和偏好选择适合自己的方式来查询行情、进行交易或提现。目前只开放REST接口，WebSocket接口将会随后提供。
Rest API
REST，即Representational State Transfer的缩写，是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，正得到越来越多网站的采用。其优点如下：
- 在RESTful架构中，每一个URL代表一种资源；
- 客户端和服务器之间，传递这种资源的某种表现层；
- 客户端通过四个HTTP指令，对服务器端资源进行操作，实现"表现层状态转化"。 建议开发者使用Rest API进行币币交易或者资产提现等操作。
WebSocket API
WebSocket是HTML5一种新的协议（Protocol）。它实现了客户端与服务器全双工通信，使得数据可以快速地双向传播。通过一次简单的握手就可以建立客户端和服务器连接，服务器根据业务规则可以主动推送信息给客户端。其优点如下：
- 客户端和服务器进行数据传输时，请求头信息比较小，大概2个字节;
- 客户端和服务器皆可以主动地发送数据给对方；
- 不需要多次创建TCP请求和销毁，节约宽带和服务器的资源。
联系我们
如需帮助请添加微信号：ApiSupport 备注：API+CRYPTEX GLOBAL，拉你进API问题交流群
API概述
市场概况和基础信息
撮合引擎
本章节主要为撮合引擎的细节分以下三个方面：
- 成交价
- 订单生命周期
- 币币交易限价规则
成交价
CRYPTEX GLOBAL撮合系统撮合订单的优先级按照价格优于时间的优先级来撮合，优先撮合价格更有优势的订单。当价格一致时按照下单时间顺序撮合，先下单的先撮合。
比如深度列表中目前有3笔挂单等待成交，分别为1: 9900USDT买1BTC，2: 10100USDT买2BTC，3: 9900USDT买1.5BTC。他们是按时间顺序1-2-3进入撮合系统的，根据价格优先，系统优先撮合订单2，根据时间优先，1跟3优先撮合1。所以系统撮合顺序是2-1-3。
订单撮合时成交价将按maker挂单价格成交，而非taker吃单价格。
例如：A用户在10000USDT挂了1BTC的买单，然后B用户以8000USDT的价格下了1BTC的卖单，因为A用户的订单先进入撮合系统挂在深度列表上，所以以A的价格为准，最终这笔订单最终以10000USDT成交。
订单生命周期
订单进入撮合引擎后是"未成交"状态；
如果一个订单被撮合而全部成交，那么它会变成"已成交"状态；
一个订单被撮合可能出现部分成交，那么他的状态会变成"部分成交"状态，并且继续留在撮合队列中进行撮合；
一个留在撮合队伍中等待撮合的订单被撤销，那么他的状态会变成"已撤销"状态；
发起撤消到完成撤消的过程中有一个过程状态"撤单中"；
被撤消或者全部成交的订单将被从撮合队列中剔除。
币币交易限价规则
为了防止用户下错大单造成市场异常波动和个人资金损失，CRYPTEX GLOBAL币币交易设置了FOK限价规则：如果用户在币币交易所下的市价单/限价单可以与当前买卖盘内订单直接成交，那么系统会判断成交深度对应的价格与同方向盘口价的偏差是否超出30%。如果超过，则此订单将被系统立即全数撤销，否则此订单正常进行撮合。
例如：某用户在XRP/BTC交易区下了100BTC的市价买单(此时卖一价为0.00012)，系统判断订单完成成交后最新成交价为0.0002。此时，(0.0002-0.00012)/0.00012=66.7%>30%，用户的这笔市价买单将被立即撤销，不会和买卖盘内订单进行撮合。
费用
本章节主要为费用的细节分以下两个方面：
- 交易费用
- 充/提币费用
交易费用
详情请参考CRYPTEX GLOBAL官网费率说明。
充/提币费用
CRYPTEX GLOBAL不收取任何充币/提币费用，但是提币到数字货币地址的过程中产生的矿工手续费需要用户自己承担。
服务器
CRYPTEX GLOBAL的数据库和服务器运行在香港。为了最大限度地减少API访问延迟，建议您使用与香港通讯通畅的服务器。
请求
本章节主要为请求的细节分以下三个方面：
- 介绍
- 错误
- 成功
介绍
Rest API提供账户管理、行情查询和交易功能。
Rest API终端URL https://www.cryptexglobal.io/
同时CRYPTEX GLOBAL还提供了WebSocket流，订阅WebSocket可以获取行情数据的推送。
所有请求基于Https协议，请求头信息中contentType需要统一设置为:’application/json’
错误
除非特殊说明，错误请求都通过HTTP 4xx或者状态码进行返回，返回内容还将包含错误原因、参数信息。您的HTTP库应配置为非2xx请求提供消息主体，以便您可以从主体读取消息字段。
常见错误码
| 400 | Bad Request — Invalid request fotmat |
|---|---|
| 401 | Unauthorized — Invalid APIKey |
| 403 | Forbidden — You do not have access to the requested resou-rce |
| 404 | Not Found |
| 500 | Intermal Server Error — We had a problem with our server |
成功
HTTP状态码200表示成功响应，并可能包含内容。如果响应含有内容，则将显示在相应的返回内容里面。
分页
CRYPTEX GLOBAL为所有返回数据集的REST请求使用分页。分页允许在结果的当前页面之前和之后获取结果，并且非常适合于实时数据。像/ trades，/ fill，/ orders这样默认返回最新内容的请求。根据当前的返回结果，后续请求可以在他的基础之上指定请求数据的方向，可以请求在这之前的，也可以请求在这之后的数据。
from和to可通过响应头OK-FROM和OK-TO使用。在请求初始请求页面之后，请求应使用这些值。
From游标指向的是返回结果页的第一条内容，To游标指向的是返回结果页的最后一条内容。(页面内容是按照最新的排在最上面的顺序)
如果你希望请求当前返回结果页最后的新数据，需要用from参数。你的第一个请求可以省略这个参数来获得默认的第一页。
返回结果将会包含一个OK-FROM头这里会包含当前返回结果页里面最新的一条的数据的ID。
返回结果将会包含一个OK-TO头这里会包含当前返回结果页里面最后的一条的数据的ID。
举例如果你请求返回的结果每一条内容的id是111，112，113，114，115，116，117，118，119，120
那么在返回结果里面这些内容的排列顺序是120，119，118，117，116，115，114，113，112，111
这时OK-FROM记录的ID是111，OK-TO记录的ID是120，如果你想访问更新的数据，如120以后的数据那么你需要使用from参数，如：orders?from=120&limit=5,则返回的是120以后的5条数据，且排列顺序为：125，124，123，122，121
参数
| 参数名 | 描述 |
|---|---|
| from | 请求此id之后（更新的数据）的分页内容（举例一列数：1，2，3，4，5。from 4 只有5，to 4有1，2，3） |
| to | 请求此id之前（更旧的数据）的分页内容 |
| limit | 分页返回的结果集数量，默认为100，最大为100（具体参见分页处的描述） |
例子
GET /orders?from=2&limit=30
标准规范
本章节主要为标准规范的细节分以下三个方面：
- 时间戳
- 数字
- ID
时间戳
除非另外指定，API中的所有时间戳均以毫秒为单位返回，符合ISO 8601标准。请确保您可以解析ISO 8601格式。
例子
2014-11-06T10:34:47.123Z
数字
为了保持跨平台时精度的完整性，十进制数字作为字符串返回。建议您在发起请求时也将数字转换为字符串以避免截断和精度错误。
整数（如交易编号和顺序）不加引号。
ID
除非另有说明，大多数标识符是UUID。当提出一个需要UUID的请求时，以下两个形式（有和没有破折号）都被接受。
132fb6ae-456b-4654-b4e0-d681ac05cea1或者132fb6ae456b4654b4e0d681ac05cea1
接口类型
本章节主要为接口类型的细节分以下两个方面：
- 公共接口
- 私有接口
公共接口
公共接口可用于获取配置信息和行情数据。公共请求无需认证即可调用。
私有接口
私有接口可用于订单管理和账户管理。每个私有请求必须使用规范的验证形式进行签名。
私有接口需要使用您的APIKey进行验证。您可以在这里生成APIKey。
访问限制
本章节主要为访问限制的细节分以下两个方面：
- Rest API
- WebSocket
当访问超过频率限制时，将返回429状态：请求太频繁。
Rest API
如果传入有效的APIKey 用UserID限速；如果没有则拿公网IP限速。
限速规则：各个接口上有单独的说明，如果没有一般接口限速为 6次/秒。
特殊说明：批量下单时，若下4个币对，每个币对10个订单时，计为一次请求。
WebSocket
WebSocket将每个命令类型限制为每秒50条命令。
验证
本章节主要为验证的细节分以下五个方面：
- 生成APIKey
- 发起请求
- 签名
- 时间戳
- 获取服务器时间
生成APIKey
在对任何请求进行签名之前，您必须通过CRYPTEX GLOBAL网站创建一个APIKey。创建APIKey后，您将获得3个必须记住的信息：
- APIKey
- Secret
- Passphrase
APIKey和Secret将由CRYPTEX GLOBAL随机生成和提供，Passphrase将由您提供以确保API访问的安全性。CRYPTEX GLOBAL将存储Passphrase加密后的哈希值进行验证，但如果您忘记Passphrase，则无法恢复，请您通过CRYPTEX GLOBAL网站重新生成新的APIKey。
发起请求
所有REST请求头都必须包含以下内容：
OK-ACCESS-KEY字符串类型的APIKey。
OK-ACCESS-SIGN使用Base64编码签名(请参阅签名)。
OK-ACCESS-TIMESTAMP发起请求的时间戳。
OK-ACCESS-PASSPHRASE您在创建API密钥时指定的Passphrase。
所有请求都应该含有application/json类型内容，并且是有效的JSON。
签名
OK-ACCESS-SIGN的请求头是对timestamp + method + requestPath + body字符串(+表示字符串连接)使用HMAC SHA256方法加密，通过Base64编码输出而得到的。
其中，timestamp的值与OK-ACCESS-TIMESTAMP请求头相同。
method是请求方法，字母全部大写。
requestPath是请求接口路径。
body是指请求主体的字符串，如果请求没有主体(通常为GET请求)则body可省略。
public enum ContentTypeEnum {
APPLICATION_JSON("application/json"),
APPLICATION_JSON_UTF8("application/json; charset=UTF-8"),
// The server does not support types
APPLICATION_FORM("application/x-www-form-urlencoded; charset=UTF-8"),;
private String contentType;
ContentTypeEnum(String contentType) {
this.contentType = contentType;
}
public String contentType() {
return contentType;
}
}
public enum HttpHeadersEnum {
OK_ACCESS_KEY("OK-ACCESS-KEY"),
OK_ACCESS_SIGN("OK-ACCESS-SIGN"),
OK_ACCESS_TIMESTAMP("OK-ACCESS-TIMESTAMP"),
OK_ACCESS_PASSPHRASE("OK-ACCESS-PASSPHRASE"),
OK_FROM("OK-FROM"),
OK_TO("OK-TO"),
OK_LIMIT("OK-LIMIT"),;
private String header;
HttpHeadersEnum(String header) {
this.header = header;
}
public String header() {
return header;
}
}
import com.okcoin.commons.cryptexglobal.open.api.config.APIConfiguration;
import com.okcoin.commons.cryptexglobal.open.api.constant.APIConstants;
import com.okcoin.commons.cryptexglobal.open.api.enums.ContentTypeEnum;
import com.okcoin.commons.cryptexglobal.open.api.enums.HttpHeadersEnum;
import com.okcoin.commons.cryptexglobal.open.api.exception.APIException;
import com.okcoin.commons.cryptexglobal.open.api.utils.DateUtils;
import com.okcoin.commons.cryptexglobal.open.api.utils.HmacSHA256Base64Utils;
import okhttp3.*;
import okio.Buffer;
public class APIHttpClient {
private APIConfiguration config;
private APICredentials credentials;
public APIHttpClient(APIConfiguration config, APICredentials credentials) {
this.config = config;
this.credentials = credentials;
}
public OkHttpClient client() {
OkHttpClient.Builder clientBuilder = new OkHttpClient.Builder();
clientBuilder.connectTimeout(this.config.getConnectTimeout(), TimeUnit.SECONDS);
clientBuilder.readTimeout(this.config.getReadTimeout(), TimeUnit.SECONDS);
clientBuilder.writeTimeout(this.config.getWriteTimeout(), TimeUnit.SECONDS);
clientBuilder.retryOnConnectionFailure(this.config.isRetryOnConnectionFailure());
clientBuilder.addInterceptor((Interceptor.Chain chain) -> {
Request.Builder requestBuilder = chain.request().newBuilder();
String timestamp = DateUtils.getUnixTime();
requestBuilder.headers(headers(chain.request(), timestamp));
Request request = requestBuilder.build();
if (this.config.isPrint()) {
printRequest(request, timestamp);
}
return chain.proceed(request);
});
return clientBuilder.build();
}
private Headers headers(Request request, String timestamp) {
Headers.Builder builder = new Headers.Builder();
builder.add(APIConstants.ACCEPT, ContentTypeEnum.APPLICATION_JSON.contentType());
builder.add(APIConstants.CONTENT_TYPE, ContentTypeEnum.APPLICATION_JSON_UTF8.contentType());
builder.add(APIConstants.COOKIE, getCookie());
if (StringUtils.isNotEmpty(this.credentials.getSecretKey())) {
builder.add(HttpHeadersEnum.OK_ACCESS_KEY.header(), this.credentials.getApiKey());
builder.add(HttpHeadersEnum.OK_ACCESS_SIGN.header(), sign(request, timestamp));
builder.add(HttpHeadersEnum.OK_ACCESS_TIMESTAMP.header(), timestamp);
builder.add(HttpHeadersEnum.OK_ACCESS_PASSPHRASE.header(), this.credentials.getPassphrase());
}
return builder.build();
}
private String getCookie() {
StringBuilder cookie = new StringBuilder();
cookie.append(APIConstants.LOCALE).append(this.config.getI18n().i18n());
return cookie.toString();
}
private String sign(Request request, String timestamp) {
String sign;
try {
sign = HmacSHA256Base64Utils.sign(timestamp, method(request), requestPath(request),
queryString(request), body(request), this.credentials.getSecretKey());
} catch (IOException e) {
throw new APIException("Request get body io exception.", e);
} catch (CloneNotSupportedException e) {
throw new APIException("Hmac SHA256 Base64 Signature clone not supported exception.", e);
} catch (InvalidKeyException e) {
throw new APIException("Hmac SHA256 Base64 Signature invalid key exception.", e);
}
return sign;
}
private String url(Request request) {
return request.url().toString();
}
private String method(Request request) {
return request.method().toUpperCase();
}
private String requestPath(Request request) {
String url = url(request);
url = url.replace(this.config.getEndpoint(), APIConstants.EMPTY);
String requestPath = url;
if (requestPath.contains(APIConstants.QUESTION)) {
requestPath = requestPath.substring(0, url.lastIndexOf(APIConstants.QUESTION));
}
if(this.config.getEndpoint().endsWith(APIConstants.SLASH)){
requestPath = APIConstants.SLASH + requestPath;
}
return requestPath;
}
private String queryString(Request request) {
String url = url(request);
String queryString = APIConstants.EMPTY;
if (url.contains(APIConstants.QUESTION)) {
queryString = url.substring(url.lastIndexOf(APIConstants.QUESTION) + 1);
}
return queryString;
}
private String body(Request request) throws IOException {
RequestBody requestBody = request.body();
String body = APIConstants.EMPTY;
if (requestBody != null) {
Buffer buffer = new Buffer();
requestBody.writeTo(buffer);
body = buffer.readString(APIConstants.UTF_8);
}
return body;
}
}
import retrofit2.Call;
import retrofit2.http.GET;
import retrofit2.http.Path;
import retrofit2.http.Query;
import java.util.List;
interface FuturesMarketAPI {
@GET("/api/futures/v3/products/{product_id}/candles")
Call<JSONArray> getProductCandles(@Path("product_id") String productId, @Query("start") String start, @Query("end") String end, @Query("granularity") String granularity);
}
import com.alibaba.fastjson.JSONArray;
import com.okcoin.commons.cryptexglobal.open.api.bean.futures.result.*;
import com.okcoin.commons.cryptexglobal.open.api.client.APIClient;
import com.okcoin.commons.cryptexglobal.open.api.config.APIConfiguration;
import com.okcoin.commons.cryptexglobal.open.api.service.futures.FuturesMarketAPIService;
public class FuturesMarketAPIServiceImpl implements FuturesMarketAPIService {
private APIClient client;
private FuturesMarketAPI api;
public FuturesMarketAPIServiceImpl(APIConfiguration config) {
this.client = new APIClient(config);
this.api = client.createService(FuturesMarketAPI.class);
}
@Override
public JSONArray getProductCandles(String productId, long start, long end, long granularity) {
return this.client.executeSync(this.api.getProductCandles(productId, String.valueOf(start), String.valueOf(end), String.valueOf(granularity)));
}
}
import okhttp3.Headers;
import okhttp3.OkHttpClient;
import org.apache.commons.lang3.StringUtils;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import retrofit2.Call;
import retrofit2.Response;
import retrofit2.Retrofit;
import java.io.IOException;
import java.util.List;
import java.util.Optional;
public class APIClient {
/**
* Synchronous send request
*/
public <T> T executeSync(Call<T> call) {
try {
Response<T> response = call.execute();
if (this.config.isPrint()) {
printResponse(response);
}
int status = response.code();
String message = new StringBuilder().append(response.code()).append(" / ").append(response.message()).toString();
if (response.isSuccessful()) {
return response.body();
} else if (APIConstants.resultStatusArray.contains(status)) {
HttpResult result = JSON.parseObject(new String(response.errorBody().bytes()), HttpResult.class);
result.setStatusCode(status);
throw new APIException(result.message());
} else {
throw new APIException(message);
}
} catch (IOException e) {
throw new APIException("APIClient executeSync exception.", e);
}
}
}
public class FuturesAPIBaseTests extends BaseTests {
public APIConfiguration config() {
APIConfiguration config = new APIConfiguration();
config.setEndpoint("https://www.cryptexglobal.com/");
config.setApiKey("");
config.setSecretKey("");
config.setPassphrase("");
config.setPrint(true);
config.setI18n(I18nEnum.ENGLISH);
return config;
}
String productId = "BTC-USD-180928";
}
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONArray;
import com.okcoin.commons.cryptexglobal.open.api.bean.futures.result.*;
import com.okcoin.commons.cryptexglobal.open.api.service.futures.FuturesMarketAPIService;
import com.okcoin.commons.cryptexglobal.open.api.service.futures.impl.FuturesMarketAPIServiceImpl;
import org.junit.Before;
import org.junit.Test;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.List;
public class FuturesMarketAPITests extends FuturesAPIBaseTests {
private FuturesMarketAPIService marketAPIService;
@Before
public void before() {
config = config();
marketAPIService = new FuturesMarketAPIServiceImpl(config);
}
@Test
public void testGetProductCandles() {
long start = System.currentTimeMillis();
long end = System.currentTimeMillis() + 2000L;
JSONArray array = marketAPIService.getProductCandles(productId, 1530323640000L, 0, 180L);
toResultString(LOG, "Product-Candles", array);
}
}
package cryptexglobal
import (
"bytes"
"errors"
"fmt"
"io/ioutil"
"net/http"
"strconv"
"strings"
"time"
)
type Client struct {
Config Config
HttpClient *http.Client
}
type ApiMessage struct {
Message string `json:"message"`
}
/*
Get a http client
*/
func NewClient(config Config) *Client {
var client Client
client.Config = config
timeout := config.TimeoutSecond
if timeout <= 0 {
timeout = 30
}
client.HttpClient = &http.Client{
Timeout: time.Duration(timeout) * time.Second,
}
return &client
}
/*
Send a http request to remote server and get a response data
*/
func (client *Client) Request(method string, requestPath string,
params, result interface{}) (response *http.Response, err error) {
config := client.Config
// uri
endpoint := config.Endpoint
if strings.HasSuffix(config.Endpoint, "/") {
endpoint = config.Endpoint[0:len(config.Endpoint)-1]
}
url := endpoint + requestPath
// get json and bin styles request body
var jsonBody string
var binBody = bytes.NewReader(make([]byte, 0))
if params != nil {
jsonBody, binBody, err = ParseRequestParams(params)
if err != nil {
return response, err
}
}
// get a http request
request, err := http.NewRequest(method, url, binBody)
if err != nil {
return response, err
}
// Sign and set request headers
timestamp := IsoTime()
preHash := PreHashString(timestamp, method, requestPath, jsonBody)
sign, err := HmacSha256Base64Signer(preHash, config.SecretKey)
if err != nil {
return response, err
}
Headers(request, config, timestamp, sign)
if config.IsPrint {
printRequest(config, request, jsonBody, preHash)
}
// send a request to remote server, and get a response
response, err = client.HttpClient.Do(request)
if err != nil {
return response, err
}
defer response.Body.Close()
// get a response results and parse
status := response.StatusCode
message := response.Status
body, err := ioutil.ReadAll(response.Body)
if err != nil {
return response, err
}
if config.IsPrint {
printResponse(status, message, body)
}
response.Header.Add(ResultJsonString, string(body))
if status >= 200 && status < 300 {
if body != nil && result != nil {
err := JsonBytes2Struct(body, result)
if err != nil {
return response, err
}
}
return response, nil
} else if status == 400 || status == 401 || status == 500 {
if body != nil {
var apiMessage ApiMessage
err := JsonBytes2Struct(body, &apiMessage)
if err != nil {
return response, err
}
message = strconv.Itoa(status) + " " + apiMessage.Message
}
return response, errors.New(message)
} else {
return response, errors.New(message)
}
return response, nil
}
type Config struct {
// Rest API endpoint url. eg: http://www.cryptexglobal.com/
Endpoint string
// The user's APIKey provided by cryptexglobal.
ApiKey string
// The user's secret key provided by cryptexglobal. The secret key used to sign your request data.
SecretKey string
// The Passphrase will be provided by you to further secure your API access.
Passphrase string
// Http request timeout.
TimeoutSecond int
// Whether to print API information
IsPrint bool
// Internationalization @see file: constants.go
I18n string
}
func (client *Client) GetFuturesProductCandles(productId string, start, end, granularity int64) ([][] float64, error) {
var candles [][] float64
params := NewParams()
params["start"] = Int642String(start)
params["end"] = Int642String(end)
params["granularity"] = Int642String(granularity)
requestPath := BuildParams(FuturesPathPrefix+"products/"+productId+"/candles", params)
_, err := client.Request(GET, requestPath, nil, &candles)
return candles, err
}
func NewTestClient() *Client {
// Set cryptexglobal API's config
var config Config
config.Endpoint = "https://www.cryptexglobal.com/"
config.ApiKey = ""
config.SecretKey = ""
config.Passphrase = ""
config.TimeoutSecond = 45
config.IsPrint = false
config.I18n = ENGLISH
client := NewClient(config)
return client
}
import "testing"
const (
productId = "BTC-USD-180928"
currency = "BTC"
)
func TestGetFuturesProductCandles(t *testing.T) {
start := int64(0)
end := int64(0)
candles, err := NewTestClient().GetFuturesProductCandles(productId, start, end, 180)
if err != nil {
t.Error(err)
}
FmtPrintln(GUnitTest+"Futures product candles: ", candles)
}
string cryptexglobalAPI::GetSign(string timestamp, string method, string requestPath, string body) {
string sign;
unsigned char * mac = NULL;
unsigned int mac_length = 0;
string data = timestamp + method + requestPath + body;
string key = m_config.SecretKey;
int ret = HmacEncode("sha256", key.c_str(), key.length(), data.c_str(), data.length(), mac, mac_length);
sign = Base64_encode(mac, mac_length);
return sign;
}
string cryptexglobalAPI::Request(const string &method, const string &requestPath, const string ¶ms) {
/************************** set request method ***************************/
http_request request;
request.set_method(method);
/************************** set request uri ***************************/
uri_builder builder;
builder.append_path(requestPath);
request.set_request_uri(builder.to_uri());
/************************** set request headers ***************************/
char * timestamp = new char[32];
timestamp = GetTimestamp(timestamp, 32);
string sign = GetSign(timestamp, method, builder.to_string(), params);
request.headers().clear();
request.headers().add(U("OK-ACCESS-KEY"), m_config.ApiKey);
request.headers().add(U("OK-ACCESS-SIGN"), sign);
request.headers().add(U("OK-ACCESS-TIMESTAMP"), timestamp);
request.headers().add(U("OK-ACCESS-PASSPHRASE"), m_config.Passphrase);
request.headers().add(U("Accept"), U("application/json"));
request.headers().set_content_type(U("application/json; charset=UTF-8"));
request.headers().add(U("Cookie"),U("locale="+m_config.I18n));
/************************** set request body ***************************/
request.set_body(params,"application/json; charset=UTF-8");
/************************** get response ***************************/
http_response response;
string str;
http_client client(m_config.Endpoint);
response = client.request(request).get();
str = response.extract_string(true).get();
delete []timestamp;
return str;
}
string GetSpotOrdersExample() {
cryptexglobalAPI cryptexglobalapi;
/************************** set config **********************/
struct Config config;
config.Endpoint = "https://www.cryptexglobal.com";
config.SecretKey = "";
config.ApiKey = "";
config.Passphrase = "";
okapi.SetConfig(config);
/************************** set parameters **********************/
string method(GET);
map<string,string> m;
m.insert(make_pair("productId", "BTC-USD"));
m.insert(make_pair("status", "all"));
/************************** request and response **********************/
string request_path = BuildParams("/api/spot/v3/orders", m);
return cryptexglobalapi.Request(method, request_path);
}
string AddSpotOrderExample() {
cryptexglobalAPI cryptexglobalapi;
/************************** set config **********************/
struct Config config;
config.Endpoint = "https://www.cryptexglobal.com";
config.SecretKey = "";
config.ApiKey = "";
config.Passphrase = "";
okapi.SetConfig(config);
/************************** set parameters **********************/
value obj;
obj["size"] = value::number(1);
obj["price"] = value::number(8);
obj["side"] = value::string("buy");
obj["product_id"] = value::string("BTC-USD");
/************************** request and response **********************/
string params = obj.serialize();
return cryptexglobalapi.Request(POST, "/api/spot/v3/orders", params);
}
}
import hmac
import Base64
import requests
import json
CONTENT_TYPE = 'Content-Type'
OK_ACCESS_KEY = 'OK-ACCESS-KEY'
OK_ACCESS_SIGN = 'OK-ACCESS-SIGN'
OK_ACCESS_TIMESTAMP = 'OK-ACCESS-TIMESTAMP'
OK_ACCESS_PASSPHRASE = 'OK-ACCESS-PASSPHRASE'
APPLICATION_JSON = 'application/json'
# signature
def signature(timestamp, method, request_path, body, secret_key):
if str(body) == '{}' or str(body) == 'None':
body = ''
message = str(timestamp) + str.upper(method) + request_path + str(body)
mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod='sha256')
d = mac.digest()
return Base64.b64encode(d)
# set request header
def get_header(api_key, sign, timestamp, passphrase):
header = dict()
header[CONTENT_TYPE] = APPLICATION_JSON
header[OK_ACCESS_KEY] = api_key
header[OK_ACCESS_SIGN] = sign
header[OK_ACCESS_TIMESTAMP] = str(timestamp)
header[OK_ACCESS_PASSPHRASE] = passphrase
return header
def parse_params_to_str(params):
url = '?'
for key, value in params.items():
url = url + str(key) + '=' + str(value) + '&'
return url[0:-1]
# Example Request
# set the request url
base_url = 'https://www.cryptexglobal.com'
request_path = '/api/account/v3/currencies'
# set request header
header = get_header('your_api_key', signature('timestamp', 'GET', request_path, 'your_secret_key'), 'timestamp', 'your_passphrase')
# do request
response = requests.get(base_url + request_path, headers=header)
# json
print(response.json())
# [{
# "id": "BTC",
# "name": "Bitcoin"，
# "deposit": "1",
# "withdraw": "1",
# "withdraw_min":"0.000001btc"
# }, {
# "id": "ETH",
# "name": "Ethereum",
# "deposit": "1",
# "withdraw": "1"，
# "withdraw_min":"0.0001eth"
# }
# …
# ]
########################################################
# take order
base_url = 'https://www.cryptexglobal.com'
request_path = '/api/spot/v3/orders'
# request params
params = {'type': 'market', 'side': 'buy', 'product_id': 'usdt_okb', 'size': '10', 'client_oid': '',
'price': '10', 'funds': ''}
# request path
request_path = request_path + parse_params_to_str(params)
url = base_url + request_path
# request header and body
header = get_header('your_api_key', signature('timestamp', 'POST', request_path, 'your_secret_key'), 'timestamp', 'your_passphrase')
body = json.dumps(params)
# do request
response = requests.post(url, data=body, headers=header)
#########################################################
# get order info
base_url = 'https://www.cryptexglobal.com'
request_path = '/api/spot/v3/orders'
params = {'status':'all', 'product_id': 'okb_usdt'}
# request path
request_path = request_path + parse_params_to_str(params)
url = base_url + request_path
# request header and body
header = get_header('your_api_key', signature('timestamp', 'GET', request_path, 'your_secret_key'), 'timestamp', 'your_passphrase')
# do request
response = requests.get(url, headers=header)
时间戳
OK-ACCESS-TIMESTAMP请求头必须是UTC时区Unix时间戳的十进制秒数格式或ISO8601标准的时间格式。
时间戳和服务器时间相差30秒以上的请求将被系统视为过期并拒绝。如果您认为服务器和API服务器之间存在较大的时间偏差，那么我们建议您使用获取服务器时间的接口来查询API服务器时间。
获取服务时间
获取API服务器的时间。此接口为公共接口，不需要身份验证。
HTTP请求
GET /api/general/v3/time
返回参数
| 参数名 | 描述 |
|---|---|
| iso | ISO8601标准的时间格式 |
| epoch | UTC时区Unix时间戳的十进制秒数格式 |
[{
"iso": "2015-01-07T23:47:25.201Z",
"epoch": 1420674445.201
}]
资金账户API
资金账户主账户与交易账户/子账户之间的资金划转，获取充值地址，提现等功能。
获取币种列表
获取平台所有币种列表。并非所有币种都可被用于交易。在ISO 4217标准中未被定义的币种代码可能使用的是自定义代码。
限速规则：6次/s
HTTP请求
GET/api/account/v3/currencies
请求示例
GET/api/account/v3/currencies
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| currency | String | 币种名称，如btc |
| name | String | 币种中文名称，不显示则无对应名称 |
| can_deposit | String | 是否可充值，0表示不可充值，1表示可以充值 |
| can_withdraw | String | 是否可提币，0表示不可提币，1表示可以提币 |
| min_withdrawal | String | 币种最小提币量 |
返回示例
[
{
"can_deposit":"1",
"can_withdraw":"1",
"currency":"BTC",
"min_withdrawal":"0.01",
"name":""
},
{
"can_deposit":"1",
"can_withdraw":"1",
"currency":"LTC",
"min_withdrawal":"0.1",
"name":""
}
]
钱包账户信息
获取资金账户所有资产列表，查询各币种的余额、冻结和可用等信息。
限速规则：6次/s
HTTP请求
GET/api/account/v3/wallet
请求示例
GET/api/account/v3/wallet
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| currency | String | 币种，如BTC |
| balance | String | 余额 |
| hold | String | 冻结（不可用） |
| available | String | 可用余额 |
返回示例
[
{
"available":"37.11827078",
"balance":"37.11827078",
"currency":"ETH",
"hold":"0"
},
{
"available":"0",
"balance":"0",
"currency":"BTC",
"hold":"0"
}
]
单一币种账户信息
获取资金账户单个币种的余额、冻结和可用等信息。
限速规则：6次/s
HTTP请求
GET/api/account/v3/wallet/<currency>
请求示例
GET/api/account/v3/wallet/XMR
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| currency | String | 是 | 币种 |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| balance | String | 余额 |
| hold | String | 冻结（不可用） |
| available | String | 可用余额 |
| currency | String | 币种，如BTC |
返回示例
[{
"balance":"300.00000000",
"available":"300.00000000",
"currency":"BTC",
"hold":"0.00000000"
}]
资金划转
OKEx站内在资金账户、交易账户和子账户之间进行资金划转。
限速规则：1次/2s（每个币种）
HTTP请求
POST /api/account/v3/transfer
请求示例
POST /api/account/v3/transfer{"amount":0.0001,"currency":"eos","from":6,"to":5,"instrument_id":"eos-usdt"}
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 | |
|---|---|---|---|---|
| currency | String | 是 | 币种，如eos |
|
| amount | String | 是 | 划转数量 | |
| from | String | 是 | 转出账户(0:子账户 1:币币 4:C2C 6:资金账户 ) | |
| to | String | 是 | 转入账户 (0:子账户 1:币币 4:C2C 6:资金账户 ) |
|
| sub_account | String | 否 | 子账号登录名，from或to指定为0时，sub_account为必填项， | |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| transfer_id | String | 划转ID |
| currency | String | 划转币种 |
| from | String | 转出账户 |
| amount | String | 划转量 |
| to | String | 转入账户 |
| result | Boolean | 划转结果。若是划转失败，将给出错误码提示 |
解释说明
from或to指定为0时，sub_account为必填项。
当from为0时，to只能填6，即子账户的资金账户只能转到母账户的资金账户。
当from指定为6，to指定为1-9，且sub_account填写子账户名时，可从母账户直接划转至子账户对应的币币、合约等账户。
from或to指定为5时，instrument_id为必填项。
返回示例
{
"transfer_id": "754147",
"currency"："ETC"
"from": "6",
"amount": "0.1",
"to": "1",
"result": true
}
提币
限速规则：6次/s
HTTP请求
POST/api/account/v3/withdrawal
请求示例
POST/api/account/v3/withdrawal{"amount":"1","fee":"0.0005","trade_pwd":"123456","destination":4,"currency":"btc","to_address":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw"}
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| currency | String | 是 | 币种 |
| amount | String | 是 | 数量 |
| destination | String | 是 | 提币到3:; 4:数字货币地址; 68:币全CoinAll;89: Korea; 90:4A交易平台;104:MY1EX;107:BFEX;108:99EX;113:ETHEX.COM以太坊交易所;116:雷爵爾交易所; 125:PICKCOIN;136:FT交易所;152:xFutures; 153:Float SV; 158:理想国;161:币爱交易所;163:BOOMEX; 172:币可富; 173:VVCOIN; 174:Huoblock;175:JIAMIX; 176:币海; 177:币尚; 178:七十三街交易所 |
| to_address | String | 是 | 认证过的数字货币地址、邮箱或手机号。某些数字货币地址格式为:地址+标签，例：ARDOR-7JF3-8F2E-QUWZ-CAN7F:123456 |
| trade_pwd | String | 是 | 交易密码 |
| fee | String | 是 | 网络手续费≥0，提币到数字货币地址所需网络手续费可通过提币手续费接口查询 |
关于标签：某些币种如xrp充币时同时需要一个充值地址和标签(又名tag/memo/payment_id/标签等)，标签是一种保证您的充币地址唯一性的数字串，与充币地址成对出现并一一对应。请您务必遵守正确的充值步骤，在提币时输入完整信息，否则将面临丢失币的风险！
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| currency | String | 提币币种 |
| amount | String | 提币数量 |
| withdraw_id | String | 提币申请ID |
| result | Boolean | 提币申请结果。若是提现申请失败，将给出错误码提示 |
返回示例
{
"amount":"0.1",
"withdrawal_id":"67485",
"currency":"btc",
"result":true
}
提币手续费
查询提现到数字货币地址时，建议网络手续费信息。手续费越高，网络确认越快。
限速规则：6次/s
HTTP请求
GET/api/account/v3/withdrawal/fee
请求示例
GET/api/account/v3/withdrawal/fee?currency=btc
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| currency | String | 否 | 币种，不填则返回所有 |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| currency | String | 币种 |
| min_fee | String | 最小提币手续费数量 |
| max_fee | String | 最大提币手续费数量 |
返回示例
[
{
"currency":"BTC",
"max_fee":"0.02",
"min_fee":"0.0005"
},
{
"currency":"LTC",
"max_fee":"0.2",
"min_fee":"0.001"
},
{
"currency":"ETH",
"max_fee":"0.2",
"min_fee":"0.01"
}
]
查询最近所有币种的提币记录
查询最近所有币种的提币记录，为最近100条记录。
限速规则：6次/s
HTTP请求
GET/api/account/v3/withdrawal/history
请求示例
GET/api/account/v3/withdrawal/history
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| currency | String | 币种 |
| amount | String | 数量 |
| timestamp | String | 提币申请时间 |
| from | String | 提币地址（如果收币地址是平台地址，则此处将显示用户账户） |
| to | String | 收币地址 |
| tag | String | 部分币种提币需要标签，若不需要则不返回此字段 |
| payment_id | String | 部分币种提币需要此字段，若不需要则不返回此字段 |
| memo | String | 部分币种提币需要此字段，若不需要则不返回此字段 |
| txid | String | 提币哈希记录（内部转账将不返回此字段） |
| fee | String | 提币手续费 |
| status | String | 提现状态-3:撤销中-2:已撤销-1:失败0:等待提现1:提现中2:已汇出3:邮箱确认4:人工审核中5:等待身份认证 |
| withdrawal_id | String | 提币申请ID |
解释说明
此处的from显示的是用户账户，并不等于区块链上实际的发币地址，如果提币到则to显示为账户，此时将不返回txid
返回所有币种最近100条提币记录，若想查询更多请分币对查询。
注意此处显示的最新提币记录可能还没有在区块上打包成功，若此处有提币记录而实际未到账，请耐心等待
返回示例
[
{
"amount":"0.094",
"withdrawal_id": "4703879",
"fee":"0.01000000eth",
"txid":"0x62477bac6509a04512819bb1455e923a60dea5966c7caeaa0b24eb8fb0432b85",
"currency":"ETH",
"from":"13426335357",
"to":"0xA41446125D0B5b6785f6898c9D67874D763A1519",
"timestamp":"2018-04-22T23:09:45.000Z",
"status":"2"
},
{
"amount":"0.01",
"withdrawal_id": "4703879",
"fee":"0.00000000btc",
"txid":"",
"currency":"BTC",
"from":"13426335357",
"to":"13426335357",
"timestamp":"2018-05-17T02:43:08.000Z",
"status":"2"
}
]
查询单个币种提币记录
查询单个币种的提币记录。
限速规则：6次/s
HTTP请求
GET/api/account/v3/withdrawal/history/<currency>
请求示例
GET/api/account/v3/withdrawal/history/btc
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| currency | String | 是 | 币种 |
返回参数
| 参数名 | 参数类型 | 描述 | |
|---|---|---|---|
| amount | String | 数量 | |
| currency | String | 币种 | |
| timestamp | String | 提币申请时间 | |
| from | String | 提币地址（如果收币地址是平台地址，则此处将显示用户账户） | |
| to | String | 收币地址 | |
| tag | String | 部分币种提币需要标签，若不需要则不返回此字段 | |
| payment_id | String | 部分币种提币需要此字段，若不需要则不返回此字段 | |
| memo | String | 部分币种提币需要此字段，若不需要则不返回此字段 | |
| txid | String | 提币哈希记录（内部转账将不返回此字段） | |
| fee | String | 提币手续费和对应币种，如0.00000009btc |
|
| status | String | 提现状态-3:撤销中-2:已撤销-1:失败0:等待提现1:提现中2:已汇出3:邮箱确认4:人工审核中5:等待身份认证 |
|
| withdrawal_id | String | 提币申请ID |
解释说明
此处的from显示的是用户账户，并不等于区块链上实际的发币地址，如果提币到则to也显示为账户，此时将不返回txid
返回所有币种最近100条提币记录，若想查询更多请分币对查询。
注意此处显示的最新提币记录可能还没有在区块上打包成功，若此处有提币记录而实际未到账，请耐心等待
返回示例
[
{
"amount":"0.01105486",
"withdrawal_id": "4703879",
"fee":"0.00000000btc",
"txid": "66602e279569ba319a929f5bda731d228962bc67cd89dfa0d432d82722681d66",
"currency": "BTC",
"from":"13426335357",
"to":"13426335357",
"timestamp":"2018-09-30T02:49:29.000Z",
"status":"2"
},
{
"amount":"0.01144408",
"withdrawal_id": "4703859",
"fee":"0.00000000btc",
"txid": "66602e279569ba319a929f5bda731d228962456475467d89dfa0d432d82722681d66",
"currency": "BTC",
"from":"13426335357",
"to":"13426335357",
"timestamp":"2018-09-18T00:44:56.000Z",
"status":"2"
}
]
账单流水查询
查询资金账户账单流水，可查询最近三个月的数据。
限速规则：20次/2s
HTTP请求
GET /api/account/v3/ledger
请求示例
GET /api/account/v3/ledger?type=2¤cy=btc&from=4&limit=10
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 | |
|---|---|---|---|---|
| currency | String | 否 | 币种，如BTC，不填时返回所有的账单流水 |
|
| type | String | 否 | 填写相应数字：1:充值2:提现13:撤销提现20:转入子账户21:子账户转出 37:转入币币账户 38:币币账户转出 | |
| from | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的order_id、ledger_id或trade_id等 |
|
| to | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的order_id、ledger_id或trade_id等 |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| ledger_id | String | 账单ID |
| currency | String | 币种 |
| balance | String | 余额 |
| amount | String | 变动数量 |
| typename | String | 账单类型 |
| fee | String | 手续费 |
| timestamp | String | 账单创建时间 |
返回示例
[
{
"amount":"-0.00100941",
"balance":"0",
"currency":"BTC",
"fee":"0",
"ledger_id":"9260348",
"timestamp":"2018-10-19T01:12:21.000Z",
"typename":"To: spot account"
},
{
"amount":"0.00051843",
"balance":"0.00100941",
"currency":"BTC",
"fee":"0",
"ledger_id":"8987285",
"timestamp":"2018-10-12T11:01:14.000Z",
"typename":"Get from activity"
}
]
获取充值地址
获取各个币种的充值地址，包括曾使用过的老地址。
限速规则：6次/s
HTTP请求
GET/api/account/v3/deposit/address
请求示例
GET/api/account/v3/deposit/address?currency=eos
请求参数
| 参数 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| currency | String | 是 | 币种，如BTC |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| address | String | 充值地址 |
| tag | String | 部分币种充值需要标签，若不需要则不返回此字段 |
| memo | String | 部分币种充值需要标签，若不需要则不返回此字段 |
| payment_id | String | 部分币种充值需要此字段，若不需要则不返回此字段 |
| currency | String | 币种，如BTC |
| to | String | 转入账户 1:币币3:交割合约4:C2C6:资金账户8:余币宝9:永续合约12:期权 |
解释说明
IOTA充值地址不能重复使用！在向IOTA地址发起充值后，再次充值到此相同地址将不会被确认到账。
某些币充值到账，需要同时填写返回的充值地址和一个tag/payment_id/memo。如果未遵守正确的充值步骤，币会丢失！
返回示例
[
{
"address": "okbtothemoon",
"memo": "971668",
"currency": "eos",
"to": 6
}
]
获取所有币种充值记录
获取所有币种的充值记录，为最近一百条数据（一年内）。
限速规则：6次/s
HTTP请求
GET/api/account/v3/deposit/history
请求示例
GET/api/account/v3/deposit/history
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| currency | String | 币种名称，如：btc |
| amount | String | 充值数量 |
| from | String | 充值地址，只显示内部账户转账地址，不显示区块链充值地址 |
| to | String | 到账地址 |
| txid | String | 区块转账哈希记录 |
| timestamp | String | 充值到账时间 |
| status | String | 充值状态0:等待确认1:确认到账2:充值成功 |
| deposit_id | String | 充值记录ID |
返回示例
[
{
"amount":"0.01044408",
"txid":"1915737_3_0_0_WALLET",
"currency":"BTC",
"from": "13801825426",
"to":"",
"timestamp":"2018-09-30T02:45:50.000Z",
"status":"2"
"deposit_id": "4703879",
},
{
"amount":"491.6784211",
"txid":"1744594_3_184_0_WALLET",
"currency":"OKB",
"from": "",
"to":"",
"timestamp":"2018-08-21T08:03:10.000Z",
"status":"2"
"deposit_id": "4703809",
},
{
"amount":"223.18782496",
"txid":"6d892c669225b1092c780bf0da0c6f912fc7dc8f6b8cc53b003288624c",
"currency":"USDT",
"from": "",
"to":"39kK4XvgEuM7rX9frgyHoZkWqx4iKu1spD",
"timestamp":"2018-08-17T09:18:40.000Z",
"status":"2"
"deposit_id": "4703779",
}
]
获取单个币种充值记录
获取单个币种的充值记录，最多可查询最近三个月的数据。
限速规则：6次/s
HTTP
GET/api/account/v3/deposit/history/<currency>
请求示例
GET/api/account/v3/deposit/history/btc
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 | |
|---|---|---|---|---|
| currency | String | 是 | 币种 | |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的deposit_id等 |
|
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的deposit_id等 |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| amount | String | 充值数量 |
| from | String | 充值地址，只显示内部账户转账地址，不显示区块链充值地址 |
| to | String | 此笔充值到账地址 |
| txid | String | 区块转账哈希记录 |
| timestamp | String | 充值到账时间 |
| currency | String | 币种名称，如btc |
| status | String | 充值状态0:等待确认1:确认到账2:充值成功 |
| deposit_id | String | 充值记录ID |
返回示例
[
{
"amount":"0.0835",
"txid":"6d892c669225b1092c780bf0da0c6f912fc3e8f997dc8f6b8cc53b003288624c",
"currency":"BTC",
"from":"13800138000"
"to":"39kK4XvgEuM7rX9frgyHoZkWqx4iKu1spD",
"timestamp":"2018-06-09T07:57:09.000Z",
"status":"2"
"deposit_id": "4703879",
},
{
"amount":"0.01",
"txid":"590426_1_0_WALLET",
"currency":"BTC",
"from":""
"to":"",
"timestamp":"2018-05-30T01:33:40.000Z",
"status":"2"
"deposit_id": "4708879",
}
]
币币API
币币交易的行情信息，账户信息，订单操作，订单查询，账单明细查询。
说明：因为要和老版本做兼融，实际有些接口返回参数会有多余，请以文档中返回参数说明为准。
例如币币账户信息接口返回frozen，hold和holds参数值相同，以hold为准；
币币账户信息
获取币币账户资产列表(仅展示拥有资金的币对)，查询各币种的余额、冻结和可用等信息。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/accounts
签名请求示例
GET/api/spot/v3/accounts
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| currency | String | 币种 |
| balance | String | 余额 |
| id | String | 账户 id |
| hold | String | 冻结（不可用） |
| available | String | 可用于交易的数量 |
解释说明
当你下市价单或限价单时，订单所需的资金将被冻结。这部分数量将不能被用于其他订单或者资金划转。资金将一直被冻结直至订单被成交或者取消。
返回示例
[
{
"frozen":"0",
"hold":"0",
"id": "",
"currency":"BTC",
"balance":"0.0049925",
"available":"0.0049925",
"holds":"0"
},
{
"frozen":"0",
"hold":"0",
"id": "",
"currency":"USDT",
"balance":"226.74061435",
"available":"226.74061435",
"holds":"0"
},
{
"frozen":"0",
"hold":"0",
"id": "",
"currency":"EOS",
"balance":"0.4925",
"available":"0.4925",
"holds":"0"
}
]
单一币种账户信息
获取币币账户单个币种的余额、冻结和可用等信息。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/accounts/<currency>
签名请求示例
GET/api/spot/v3/accounts/btc
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| currency | String | 是 | 币种 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| currency | String | 币种 |
| balance | String | 余额 |
| hold | String | 冻结（不可用） |
| available | String | 可用于交易的数量 |
| id | String | 账户id |
返回示例
{
"frozen":"0",
"hold":"0",
"id":"",
"currency":"BTC",
"balance":"0.0049925",
"available":"0.0049925",
"holds":"0"
}
账单流水查询
列出账户资产流水。账户资产流水是指导致账户余额增加或减少的行为。流水会分页，并且按时间倒序排序和存储，最新的排在最前面。请参阅分页部分以获取第一页之后的其他记录。 本接口能查询最近3个月的数据。
限速规则：20次/2s
HTTP请求
GET /api/spot/v3/accounts/<currency>/ledger
签名请求示例
GET /api/spot/v3/accounts/btc/ledger?limit=3&from=2&to=4
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 | |
|---|---|---|---|---|
| currency | String | 是 | 币种 | |
| from | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的order_id、ledger_id或trade_id等 |
|
| to | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的order_id、ledger_id或trade_id等 |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 | |
| type | String | 否 | 1 .充值; 2 .提现; 7 .买入; 8 .卖出; 13 .撤销提现; 20 .转入子账户; 21 .转出至子账户; 25 .otc买入; 26 .otc卖出; 29 .转出至资金账户 |
30 .资金账户转入 31 .转出至法币 32 .法币转入 46 .币币账户转入 47 .转出至币币账户
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ledger_id | String | 账单ID |
| balance | String | 余额 |
| currency | String | 币种 |
| amount | String | 变动数量 |
| type | String | 流水来源 |
| timestamp | String | 账单创建时间 |
| details | String | 如果type是trade或者fee，则会有该details字段将包含order，instrument信息 |
| order_id | String | 交易的ID |
| instrument_id | String | 交易的币对 |
解释说明
以下内容是参数名type的枚举值
| 流水来源类型 | 描述 |
|---|---|
| transfer | 资金转入/转出 |
| trade | 交易产生的资金变动 |
| rebate | 返佣 |
返回示例
[
{
"timestamp":"2019-03-18T07:26:50.000Z",
"ledger_id":"3995466151",
"created_at":"2019-03-18T07:26:50.000Z",
"currency":"BTC",
"amount":"0.0009985",
"balance":"0.0049925",
"type":"trade",
"details":{
"instrument_id":"BTC-USDT",
"order_id":"2500723297813504",
"product_id":"BTC-USDT"
}
},
{
"timestamp":"2019-03-18T07:26:50.000Z",
"ledger_id":"3995466150",
"created_at":"2019-03-18T07:26:50.000Z",
"currency":"BTC",
"amount":"0.0009985",
"balance":"0.003994",
"type":"trade",
"details":{
"instrument_id":"BTC-USDT",
"order_id":"2500723297223680",
"product_id":"BTC-USDT"
}
},
{
"timestamp":"2019-03-18T07:08:25.000Z",
"ledger_id":"3995334780",
"created_at":"2019-03-18T07:08:25.000Z",
"currency":"BTC",
"amount":"0.0009985",
"balance":"0.0029955",
"type":"trade",
"details":{
"instrument_id":"BTC-USDT",
"order_id":"2500650881647616",
"product_id":"BTC-USDT"
}
}
]
下单
币币交易提供限价单和市价单和高级限价单下单模式。只有当您的账户有足够的资金才能下单。
一旦下单，您的账户资金将在订单生命周期内被冻结。被冻结的资金以及数量取决于订单指定的类型和参数。
限速规则：100次/2s （不同币对之间限速不累计）
HTTP请求
POST /api/spot/v3/orders
签名请求示例
POST /api/spot/v3/orders{"type": "limit", "side": "buy", "instrument_id": "BTC-USDT", "size":"0.001", "client_oid": "oktspot79", "price": "4638.51", "notional": "", "order_type": "3"}
请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| client_oid | String | 否 | 由您设置的订单ID来识别您的订单,格式是字母（区分大小写）+数字 或者 纯字母（区分大小写），1-32位字符 （不能重复） |
| type | String | 否 | limit或market（默认是limit）。当以market（市价）下单，order_type只能选择0（普通委托） |
| side | String | 是 | buy 或 sell |
| instrument_id | String | 是 | 币对名称 |
| order_type | String | 否 | 参数填数字0：普通委托（order type不填或填0都是普通委托） 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
限价单特殊参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| price | String | 是 | 价格 |
| size | String | 是 | 买入或卖出的数量 |
市价单特殊参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| size | String | 是 | 卖出数量，市价卖出时必填size |
| notional | String | 是 | 买入金额，市价买入时必填notional |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| result | Boolean | 下单结果。若是下单失败，将给出错误码提示 |
| error_code | String | 错误码，下单成功时为0，下单失败时会显示相应错误码 |
| error_message | String | 错误信息，下单成功时为空，下单失败时会显示错误信息 |
解释说明
client_oid
client_oid用户需要自己保证此ID不重复，不会进行排重提示，如有重复，撤单和查询订单时只能撤销或者查询出最新的一条数据。
instrument_id
instrument_id必须是有效的币对。币对列表可通过GET/api/spot/v3/instruments接口获取。
type
下单时，您可以指定订单类型。您指定的订单类型将决定是否需要其他订单参数以及撮合引擎如何执行您的订单。如果type没有指定，订单类型将默认为limit。限价单既是默认订单类型，也是基本订单类型。限价单需要指定price和size。size是买入或卖出交易货币的数量，price表示每个交易货币相对计价货币的价格。限价单会按指定价格或更好的价格成交。根据市场条件，卖单可以按照指定价格或者更高价格来成交，买单可以按照指定价格或更低价格成交。如果限价单不能立即成交，那么限价单将进入深度列表，直到被另一个新订单成交或被用户撤单。
市价单不同于限价单，因为它们不提供价格控制。市价单提供了一种不必指定价格，而以固定数量的货币进行买入或者卖出的方式。市价单下单后会立即撮合，而不会被挂入深度列表。市价单总是吃单方taker并按taker收取手续费用。(注：如果你计划买入卖出的数量巨大时，将会对价格产生巨大影响，此时不推荐使用市价单)
price
price表示买入或卖出的价格。价格必须是价格步长tick_size的倍数。价格步长tick_size是价格的最小增量，可通过instruments接口获取。
size
size表示买入或卖出交易货币的数量。数量必须大于min_size。size_increment是交易货币数量的最小增量。上述参数都可通过instruments接口获取。
举例：假设 okb/usdt 的min_size是10，size_increment是0.0001。那么不能交易9.9个okb，但是可以交易10.0001个okb
notional
notional表示被用于市价买入的计价货币的数量，市价买入时必填。例如，在BTC-USDT交易时，市价单指定5000 USDT表示将花费5000 USDT购买BTC。
hold
对于限价买单，系统将冻结计价货币的数量 = 限定价格 x 买入数量。对于限价卖单，系统将冻结你想卖出的交易货币的数量。对于市价买单，notional数量的计价货币将被冻结。对于市价卖单，size数量的交易货币将被冻结。如果您取消部分成交或未成交的订单，剩余资金将被解除冻结。
订单生命周期
HTTP请求将在订单被拒绝（资金不足，参数无效等）或下单成功（由匹配引擎接受）时作出响应。一个200响应表示该订单被接收并且进入撮合。进入撮合的订单可以部分或全部立即成交（取决于价格和市场条件）。部分成交的时候将把订单的剩余数量继续进行撮合。完全成交的订单将进入已成交状态。
监听行情数据的用户建议使用client_oid字段以便在接受到的信息中标识对应的数据。
响应
成功接受的订单将被分配一个订单ID。订单是否成功接受取决于撮合引擎是否接受。 未成交的订单不会过期，并将保持撮合状态，直到被成交或取消。
返回示例
{
"client_oid":"oktspot79",
"error_message": "",
"error_code": "0",
"order_id":"2510789768709120",
"result":true
}
批量下单
下指定币对的多个订单（每次只能下最多4个币对且每个币对可批量下10个单）
限速规则：50次/2s （不同币对之间限速累计）
HTTP请求
POST /api/spot/v3/batch_orders
签名请求示例
POST /api/spot/v3/batch_orders[{"client_oid":"ww20180728","instrument_id":"btc-usdt","side":"sell","type":"limit","size":"0.001","price":"10001","margin_trading ":"1"},{"client_oid":"w20180728","instrument_id":"btc-usdt","side":"sell","type":"limit","size":"0.001","price":"10002","margin_trading ":"1"}]
请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| client_oid | String | 否 | 由您设置的订单ID来识别您的订单,格式是字母（区分大小写）+数字 或者 纯字母（区分大小写），1-32位字符 （不能重复） |
| type | String | 否 | limit或market（默认是limit），当以market（市价）下单，order_type只能选择0（普通委托） |
| side | String | 是 | buy 或 sell |
| instrument_id | String | 是 | 币对名称 |
| order_type | String | 否 | 参数填数字0：普通委托（order_type不填或填0都是普通委托） 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
限价单特殊参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| price | String | 是 | 价格 |
| size | String | 是 | 买入或卖出的数量 |
市价单特殊参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| size | String | 否 | 否 卖出数量，市价卖出必填size |
| notional | String | 否 | 否 买入金额，市价买入时必填notional |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| result | Boolean | 下单结果。若是下单失败，将给出错误码提示。 |
| error_code | String | 错误码，下单成功时为0，下单失败时会显示相应错误码 |
| error_message | String | 错误信息，下单成功时为空，下单失败时会显示错误信息 |
解释说明
client_oid的类型为字母（大小写）+数字或者纯字母（大小写），1-32位字符 ，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，撤单和查询订单时只能撤销或者查询最新的一条数据。
每次最多4个币对且每个币对最多10个订单，建议用户调用批量撤单接口后，再调用获取订单列表接口确认已撤销成功。
返回示例
{
"btc_usdt":[
{
"client_oid":"oktspot80",
"error_code":"0",
"error_message":"",
"order_id":"2510832677159936",
"result":true
},
{
"client_oid":"oktspot81",
"error_code":"0",
"error_message":"",
"order_id":"2510832677225472",
"result":true
},
{
"client_oid":"oktspot82",
"error_code":"0",
"error_message":"",
"order_id":"2510832677225473",
"result":true
}
]
}
撤销指定订单
撤销之前下的未完成订单。
限速规则：100次/2s （不同币对之间限速不累计）
HTTP请求
POST /api/spot/v3/cancel_orders/<order_id> or <client_oid>
签名请求示例
2018-10-12T07:34:30.223ZPOST/api/spot/v3/cancel_orders/a123{"instrument_id":"btc-usdt"}
请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 提供此参数则撤销指定币对的相应订单，如果不提供此参数则返回错误码 |
| client_oid | String | 否 | order_id和client_oid必须且只能选一个填写，由您设置的订单ID来识别您的订单 , 类型为字母（大小写）+数字或者纯字母（大小写）1-32位字符 |
| order_id | String | 否 | order_id和client_oid必须且只能选一个填写，订单ID |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| result | Boolean | 撤单申请结果。若是撤单失败，将给出错误码提示 |
| error_code | String | 错误码，撤单成功时为0，撤单失败时会显示相应错误码 |
| error_message | String | 错误信息，撤单成功时为空，撤单失败时会显示错误信息 |
解释说明
order_id和client_oid必须且只能选一个填写
使用client_oid撤单时，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，撤单时只能撤销最新的一条数据
如果订单无法取消（已经成交或已取消），那么返回的报错内容里将显示相应的原因。
返回示例
{
"client_oid": "order123",
"error_message": "",
"error_code": "0",
"order_id": "4407638476788736",
"result": true
}
批量撤销订单
撤销指定的某一种或多种币对的未完成订单（每次只能下最多4个币对且每个币对可批量下10个单）。
限速规则：50次/2s （不同币对之间限速累计）
HTTP请求
POST /api/spot/v3/cancel_batch_orders
签名请求示例
2018-10-12T07:30:49.664ZPOST /api/spot/v3/cancel_batch_orders[{"instrument_id":"btc-usdt","client_oids":["a123","a1234"]},{"instrument_id":"eth-usdt","client_oids":["a12345","a123456"]}]
请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| order_ids | List<String> | 否 | order_id和client_oid必须且只能选一个填写，订单ID |
| client_oids | List<String> | 否 | order_id和client_oid必须且只能选一个填写，由您设置的订单ID来识别您的订单，类型为字母（大小写）+数字或者纯字母（大小写），1-32位字符 |
| instrument_id | String | 是 | 币种 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| instrument_id | String | 币种，如btc-usdt |
| result | Boolean | 撤单申请结果 |
| error_code | String | 错误码，撤单成功时为0，撤单失败时会显示相应错误码 |
| error_message | String | 错误信息，撤单成功时为空，撤单失败时会显示错误信息 |
解释说明
批量撤单时候，要么都是order_id要么都是client_oid，否则会提示错误
使用client_oid批量撤单时，目前只支持一个币对下撤一个client_oid ，一次4个币对，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，撤单时只能撤销最新的一条数据
使用order_id撤单时，每次最多4个币对且每个币对最多10个订单，建议用户调用批量撤单接口后，再调用获取订单列表接口确认已撤销成功。
返回示例
{
"btc-usdt":[
{
"result":true,
"client_oid":"a123",
"error_message": "",
"error_code": "0",
"order_id": "2510832677225473"
},
{
"result":true,
"client_oid":"a1234",
"error_message": "",
"error_code": "0",
"order_id": "2510832677225474"
}
],
"eth-usdt":[
{
"result":true,
"client_oid":"a12345",
"error_message": "",
"error_code": "0",
"order_id": "2510832677225475"
},
{
"result":true,
"client_oid":"a123456",
"error_message": "",
"error_code": "0",
"order_id": "2510832677225476"
}
]
}
获取订单列表
列出您当前的订单信息（本接口能查询最近3个月订单信息）。这个请求支持分页，并且按委托时间倒序排序和存储，最新的排在最前面。
限速规则：10次/2s
HTTP请求
GET/api/spot/v3/orders
签名请求示例
2019-03-18T07:49:43.306ZGET/api/spot/v3/orders?instrument_id=BTC-USDT&state=-2&after=2500723297223680
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 | |
|---|---|---|---|---|
| instrument_id | String | 是 | 币对名称 | |
| state | String | 是 | 订单状态-2:失败-1:撤单成功0:等待成交1:部分成交2:完全成交3:下单中4:撤单中6: 未完成（等待成交+部分成交）7:已完成（撤单成功+完全成交） |
|
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的order_id |
|
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的order_id |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 用户设置的订单ID |
| price | String | 委托价格 |
| size | String | 委托数量（交易货币数量） |
| notional | String | 买入金额，市价买入时返回 |
| instrument_id | String | 币对名称 |
| type | String | limit或market（默认是limit） |
| side | String | buy 或 sell |
| timestamp | String | 订单创建的时间 |
| filled_size | String | 已成交数量 |
| filled_notional | String | 已成交金额 |
| order_type | String | 0：普通委托 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
| state | String | 订单状态-2：失败 -1：撤单成功 0：等待成交 1：部分成交 2：完全成交 3：下单中 4：撤单中 |
| price_avg | String | 成交均价 |
| fee_currency | String | 交易手续费币种，如果是买的话，就是收取的BTC；如果是卖的话，收取的就是USDT |
| fee | String | 订单交易手续费。平台向用户收取的交易手续费，为负数，例如：-0.01 |
| rebate_currency | String | 返佣金币种 USDT |
| rebate | String | 返佣金额，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”，为正数，例如：0.5 |
解释说明
status为state旧版参数，会短期兼容，建议尽早切换state。
client_oid的类型为字母（大小写）+数字或者纯字母（大小写），1-32位字符 ，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，查询订单时只能查询出最新的一条数据。
如果订单在其生命周期内没有任何成交，其记录可能被清除。这表示订单详细信息将不可用本接口来获取。
未成交的订单可能会根据市场情况在你发起请求和服务器响应之间改变状态。
返回示例
[
{
"client_oid":"oktspot76",
"created_at":"2019-03-18T07:26:49.000Z",
"filled_notional":"3.9734",
"filled_size":"0.001",
"funds":"",
"instrument_id":"BTC-USDT",
"notional":"",
"order_id":"2500723297813504",
"order_type":"0",
"price":"4013",
"price_avg": "4013",
"product_id":"BTC-USDT",
"side":"buy",
"size":"0.001",
"status":"filled",
"fee_currency":"BTC",
"fee":"-0.01",
"rebate_currency":"open",
"rebate":"0.05",
"state":"-2",
"timestamp":"2019-03-18T07:26:49.000Z",
"type":"limit"
}
]
获取所有未成交订单
列出您当前所有的订单信息。这个请求支持分页，并且按时间倒序排序和存储，最新的排在最前面。请参阅分页部分以获取第一页之后的其他纪录。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/orders_pending
签名请求示例
2018-09-12T07:51:51.138ZGET/api/spot/v3/orders_pending?limit=2&instrument_id=BTC-USDT&after=2500723297223680
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 | |
|---|---|---|---|---|
| instrument_id | String | 是 | 币对名称 | |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的order_id |
|
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的order_id |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 用户设置的订单ID |
| price | String | 委托价格 |
| size | String | 委托数量（交易货币数量） |
| notional | String | 买入金额，市价买入时返回 |
| order_type | String | 0：普通委托 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
| instrument_id | String | 币对名称 |
| side | String | buy 或 sell |
| type | String | limit或market（默认是limit） |
| timestamp | String | 订单创建时间 |
| filled_size | String | 已成交数量 |
| filled_notional | String | 已成交金额 |
| state | String | 订单状态0:等待成交 |
| fee_currency | String | 交易手续费币种，如果是买的话，就是收取的BTC；如果是卖的话，收取的就是USDT |
| fee | String | 订单交易手续费。平台向用户收取的交易手续费，为负数，例如：-0.01 |
| rebate_currency | String | 返佣金币种 USDT |
| rebate | String | 返佣金额，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”，为正数，例如：0.5 |
| price_avg | String | 成交均价 |
解释说明
status为state旧版参数，会短期兼容，建议尽早切换state。
client_oid的类型为字母（大小写）+数字或者纯字母类型 ，1-32位字符 ，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，查询订单时只能查询出最新的一条数据。
本接口只能查询所有未成交或者部分成交的订单
未成交的订单可能会根据市场情况在你发起请求和服务器响应之间改变状态。
返回示例
[
{
"client_oid":"oktspot86",
"created_at":"2019-03-20T03:28:14.000Z",
"filled_notional":"0",
"filled_size":"0",
"funds":"",
"instrument_id":"BTC-USDT",
"notional":"",
"order_id":"2511109744100352",
"order_type":"0",
"price":"3594.7",
"price_avg":"",
"product_id":"BTC-USDT",
"side":"buy",
"size":"0.001",
"status":"open",
"fee_currency":"BTC",
"fee":"-0.01",
"rebate_currency":"open",
"rebate":"0.05",
"state":"0",
"timestamp":"2019-03-20T03:28:14.000Z",
"type":"limit"
}
]
获取订单信息
通过订单ID获取单个订单信息。可以获取近3个月订单信息。已撤销的未成交单只保留2个小时。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/orders/<order_id>
或
GET/api/spot/v3/orders/<client_oid>
签名请求示例
2018-09-12T07:54:01.582ZGET/api/spot/v3/orders/23356?instrument_id=BTC-USDT
或
2018-09-12T07:54:01.582ZGET/api/spot/v3/orders/2e3356?instrument_id=BTC-USDT
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 币对 |
| order_id | String | 否 | 订单ID ,order_id和client_oid必须且只能选一个填写 |
| client_oid | String | 否 | order_id和client_oid必须且只能选一个填写.由您设置的订单ID来识别您的订单 ， 类型为字母（大小写）+数字或者纯字母（大小写）1-32位字符 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| price | String | 委托价格 |
| size | String | 委托数量（交易货币数量） |
| order_type | String | 0：普通委托 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
| notional | String | 买入金额，市价买入时返回 |
| instrument_id | String | 币对名称 |
| side | String | buy 或 sell |
| type | String | limit或market（默认是limit） |
| timestamp | String | 订单创建时间 |
| filled_size | String | 已成交数量 |
| filled_notional | String | 已成交金额 |
| state | String | 订单状态-2:失败-1:撤单成功0:等待成交1:部分成交2:完全成交3:下单中4:撤单中 |
| price_avg | String | 成交均价 |
| fee_currency | String | 交易手续费币种，如果是买的话，就是收取的BTC；如果是卖的话，收取的就是USDT |
| fee | String | 订单交易手续费。平台向用户收取的交易手续费，为负数，例如：-0.01 |
| rebate_currency | String | 返佣金币种 USDT |
| rebate | String | 返佣金额，平台向达到指定lv交易等级的用户支付的挂单奖励（返佣），如果没有返佣金，该字段为“”，为正数，例如：0.5 |
解释说明
status为state旧版参数，会短期兼容，建议尽早切换state。
client_oid的类型为字母（大小写）+数字或者纯字母（大小写）类型1-32位字符 ，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，查询订单时只能查询出最新的一条数据。
如果订单在其生命周期内没有任何成交，其记录可能被清除，则响应可能因为没有相应的匹配而返回状态码404。
未成交的订单可能会根据市场情况在你发起请求和服务器响应之间改变状态。
返回示例
{
"client_oid":"oktspot70",
"created_at":"2019-03-15T02:52:56.000Z",
"filled_notional":"3.8886",
"filled_size":"0.001",
"funds":"",
"instrument_id":"BTC-USDT",
"notional":"",
"order_id":"2482659399697408",
"order_type":"0",
"price":"3927.3",
"price_avg":"3927.3",
"product_id":"BTC-USDT",
"side":"buy",
"size":"0.001",
"status":"filled",
"fee_currency":"BTC",
"fee":"-0.01",
"rebate_currency":"open",
"rebate":"0.05",
"state":"2",
"timestamp":"2019-03-15T02:52:56.000Z",
"type":"limit"
}
获取成交明细
获取最近的成交明细表。这个请求支持分页，并且按时间倒序排序和存储，最新的排在最前面。请参阅分页部分以获取第一页之后的其他记录。 本接口能查询最近3月的数据。
限速规则：20次/2s
HTTP请求
GET /api/spot/v3/fills
签名请求示例
2018-09-12T07:56:11.922ZGET/api/spot/v3/fills?order_id=23212&instrument_id=btc-usdt&limit=2&from=2&to=4
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 | |
|---|---|---|---|---|
| order_id | String | 是 | 订单ID | |
| instrument_id | String | 是 | 币对名称 | |
| from | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的order_id、ledger_id或trade_id等 |
|
| to | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的order_id、ledger_id或trade_id等 |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ledger_id | String | 账单ID |
| instrument_id | String | 币对名称 |
| price | String | 成交价格 |
| size | String | 成交数量 |
| order_id | String | 订单ID |
| timestamp | String | 订单创建时间 |
| exec_type | String | 流动性方向（T 或 M） |
| fee | String | 手续费 |
| side | String | 账单方向（buy、sell 或 points_fee） |
解释说明
手续费
fee字段表示这条账单记录所收取的手续费。
流动性
exec_type字段表示该账单是maker还是taker产生的。M表示Maker，T表示Taker。
分页
返回账单列表的ledger_id按降序排列，从最大ledger_id到最小ledger_id。OK-FROM都会有这样的第一笔ledger_id，以便将来的请求使用OK-FROM参数将获取一个更大的ledger_id（新的账单）。
返回示例
[
[
{
"created_at":"2019-03-15T02:52:56.000Z",
"exec_type":"T",
"fee":"0",
"instrument_id":"BTC-USDT",
"ledger_id":"3963052722",
"liquidity":"T",
"order_id":"2482659399697408",
"price":"3888.6",
"product_id":"BTC-USDT",
"side":"buy",
"size":"0.00044694",
"timestamp":"2019-03-15T02:52:56.000Z"
},
{
"created_at":"2019-03-15T02:52:56.000Z",
"exec_type":"T",
"fee":"0",
"instrument_id":"BTC-USDT",
"ledger_id":"3963052721",
"liquidity":"T",
"order_id":"2482659399697408",
"price":"3888.6",
"product_id":"BTC-USDT",
"side":"buy",
"size":"0.00055306",
"timestamp":"2019-03-15T02:52:56.000Z"
},
{
"created_at":"2019-03-15T02:52:56.000Z",
"exec_type":"T",
"fee":"0",
"instrument_id":"BTC-USDT",
"ledger_id":"3963052719",
"liquidity":"T",
"order_id":"2482659399697408",
"price":"3888.6",
"product_id":"BTC-USDT",
"side":"sell",
"size":"1.73797088",
"timestamp":"2019-03-15T02:52:56.000Z"
},
{
"created_at":"2019-03-15T02:52:56.000Z",
"exec_type":"T",
"fee":"0",
"instrument_id":"BTC-USDT",
"ledger_id":"3963052718",
"liquidity":"T",
"order_id":"2482659399697408",
"price":"3888.6",
"product_id":"BTC-USDT",
"side":"sell",
"size":"2.15062911",
"timestamp":"2019-03-15T02:52:56.000Z"
}
],
{
"created_at":"2019-03-15T02:52:56.000Z",
"exec_type":"T",
"fee":"0.00000067",
"instrument_id":"BTC-USDT",
"ledger_id":"3963052722",
"liquidity":"T",
"order_id":"2482659399697408",
"price":"3888.6",
"product_id":"BTC-USDT",
"side":"points_fee",
"size":"0",
"timestamp":"2019-03-15T02:52:56.000Z"
},
{
"created_at":"2019-03-15T02:52:56.000Z",
"exec_type":"T",
"fee":"0.00000082",
"instrument_id":"BTC-USDT",
"ledger_id":"3963052722",
"liquidity":"T",
"order_id":"2482659399697408",
"price":"3888.6",
"product_id":"BTC-USDT",
"side":"points_fee",
"size":"0",
"timestamp":"2019-03-15T02:52:56.000Z"
},
{
"before":"3963052722",
"after":"3963052718"
}
]
委托策略下单
委托策略下单
提供止盈止损、跟踪委托、冰山委托和时间加权委托策略
限速规则：40次/2s
HTTP请求
POST /api/spot/v3/order_algo
请求示例
POST /api/spot/v3/order_algo{"instrument_id":"BTC-USDT","order_type":"1","mode":"1","side":"sell","size":"0.005","trigger_price":"8000","algo_price":"7500"}（止盈止损）
请求参数（通用）
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 币对名称 |
| mode | String | 是 | 1：币币 2：杠杆 |
| order_type | String | 是 | 1：计划委托 2：跟踪委托3：冰山委托 4：时间加权 5：止盈止损 |
| size | String | 是 | 委托总数，最小交易数量0<=\X\<=1000000的数 |
| side | String | 是 | buy 或 sell |
计划委托参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| trigger_price | String | 是 | 触发价格，填写值0\<X\<=1000000 |
| algo_price | String | 是 | 委托价格，填写值0\<X\<=1000000 |
| algo_type | String | 是 | 1:限价 2:市场价；触发价格类型，默认是1:限价，为2:市场价时，委托价格不必填； |
跟踪委托参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| callback_rate | String | 是 | 回调幅度，填写值0.001（0.1%）\<=X\<=0.05（5%） |
| trigger_price | String | 是 | 激活价格 ，填写值0\<X\<=1000000 |
冰山委托参数 （最多同时存在6单）
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| algo_variance | String | 是 | 委托深度，填写值0.0001(0.01%)\<=X\<=0.01（1%） |
| avg_amount | String | 是 | 单笔均值，填写值 本次委托总量的1/1000\<=X\<=本次委托总量 |
| limit_price | String | 是 | 价格限制 ，填写值0\<X\<=1000000 |
时间加权参数 （最多同时存在6单）
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| sweep_range | String | 是 | 扫单范围，填写值0.005（0.5%）\<=X\<=0.01（1%） |
| sweep_ratio | String | 是 | 扫单比例，填写值 0.01\<=X\<=1 |
| single_limit | String | 是 | 单笔上限，填写值 本次委托总量的1/1000\<=X\<=本次委托总量 |
| limit_price | String | 是 | 价格限制，填写值0\<X\<=1000000 |
| time_interval | String | 是 | 委托间隔，填写值5\<=X\<=120 |
止盈止损参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| tp_trigger_price | String | 否 | 止盈触发价格，填写值0\<X\<=1000000 |
| tp_price | String | 否 | 止盈委托价格，填写值0\<X\<=1000000 |
| tp_trigger_type | String | 否 | 1:限价 2:市场价；止盈触发价格类型，默认是限价；为市场价时，委托价格不必填； |
| sl_trigger_type | String | 否 | 1:限价 2:市场价；止损触发价格类型，默认是限价；为市场价时，委托价格不必填； |
| sl_trigger_price | String | 否 | 止损触发价格，填写值0\<X\<=1000000 |
| sl_price | String | 否 | 止损委托价格，填写值0\<X\<=1000000 |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| result | String | 调用接口返回结果 |
| algo_id | String | 订单ID，下单失败时，此字段值为-1 |
| error_code | String | 错误码，下单成功时为0，下单失败时会显示相应错误码 |
| error_message | String | 错误信息，下单成功时为空，下单失败时会显示错误信息 |
返回示例
{
"algo_id": 329967,
"error_message": "",
"error_code": "0",
"result": true
}
委托策略撤单
委托策略撤单
根据指定的algo_id撤销某个币的未完成订单，每次最多可撤6（冰山/时间）/10（计划/跟踪）个。
限速规则：20 次/2s
HTTP请求
POST /api/spot/v3/cancel_batch_algos
请求示例
单个撤单：POST /api/spot/v3/cancel_batch_algos{"instrument_id": "BTC-USDT","order_type":"1","algo_ids": ["1600593327162368"]}
批量撤单：POST /api/spot/v3/cancel_batch_algos{"instrument_id": "BTC-USDT","order_type":"1","algo_ids":["1600593327162368","1600593327162369"]}
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 撤销指定的币对 |
| algo_ids | List<String> | 是 | 撤销指定的委托单ID |
| order_type | String | 是 | 1：计划委托 2：跟踪委托3：冰山委托 4：时间加权 5：止盈止损 |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| instrument_id | String | 指定的币对 |
| order_type | String | 1：计划委托 2：跟踪委托3：冰山委托 4：时间加权 5：止盈止损 |
| algo_ids | List<String> | 撤销指定的委托单ID |
| result | String | 调用接口返回结果 |
| error_code | String | 错误码，撤单成功时为0，撤单失败时会显示相应错误码 |
| error_message | String | 错误信息，撤单成功时为空，撤单失败时会显示错误信息 |
返回参数
返回值是已发起撤销操作的委托单ID，不代表这些委托单已成功撤销，正在成交中的无法撤销，未成交的可成功撤销。
解释说明
无法保证一定会成功撤销，建议用户调用撤单接口后，再调用获取委托单列表接口确认。
返回示例
{
"result": true,
"error_message": "",
"error_code": "0",
"algo_ids": [
"329967"
],
"instrument_id": "BTC-USDT",
"order_type": "1"
}
获取当前账户费率
获取您当前账户交易等级对应的手续费费率，母账户下的子账户的费率和母账户一致。每天凌晨0点更新一次
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/trade_fee
请求示例
2019-11-12T07:28:43.497ZGET/api/spot/v3/trade_fee
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| category | String | 否 | 手续费档位 1：第一档，2：第二档， 3：第三档 ；category和instrument_id仅选填写一个参数 |
| instrument_id | String | 否 | 币对，e.g BTC-USDT ； category和instrument_id仅选填写一个参数 |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| category | String | 手续费档位 1：第一档，2：第二档， 3：第三档 |
| taker | String | 吃单手续费率 |
| maker | String | 挂单手续费率 |
| timestamp | String | 数据返回时间 |
备注：maker 的值：负数，代表是返佣的费率，正数，代表平台扣除的费率。
返回示例
{
"category": "1",
"maker": "0.0002",
"taker": "0.0005",
"timestamp": "2019-12-11T11:02:31.360Z"
}
获取委托单列表
获取委托单列表
列出您当前所有的订单信息。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/algo
请求示例
GET/api/spot/v3/algo?instrument_id=BTC-USDT&order_type=1
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 指定的币对 |
| order_type | String | 是 | 1：计划委托 2：跟踪委托3：冰山委托 4：时间加权 5：止盈止损 |
| status | String | 否 | 【status和algo_id必填且只能填其一】订单状态 1：待生效 2：已生效 3：已撤销 4：部分生效5：暂停生效6：委托失败【只有冰山和加权有 4、5状态】 |
| algo_ids | String | 否 | 【status和algo_id必填且只能填其一】查询指定的委托单ID |
| before | String | 否 | 请求此id之后（更新的数据）的分页内容 |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容 |
| limit | String | 否 | 分页返回的结果集数量，默认为100，最大为100 |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| instrument_id | String | 指定的币对 |
| order_type | String | 1：计划委托 2：跟踪委托3：冰山委托 4：时间加权 5：止盈止损 |
| timestamp | String | 委托时间 |
| rejected_at | String | 委托失效时间 |
| algo_id | String | 委托单ID |
| status | String | 订单状态1: 待生效2: 已生效3: 已撤销4: 部分生效5: 暂停生效 |
| size | String | 委托数量,填写值1\<=X\<=1000000的整数 |
| algo_price | String | 策略委托价格 |
| mode | String | 1：币币 2：杠杆 |
| order_id | String | 订单 ID |
| side | String | Buy 或 Sell |
| trigger_price | String | 策略委托触发价格 |
计划委托
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| trigger_price | String | 触发价格，填写值0\<X |
| algo_price | String | 委托价格，填写值0\<X\<=1000000 |
| algo_type | String | 1:限价 2:市场价； |
跟踪委托
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| callback_rate | String | 回调幅度，填写值0.001（0.1%）\<=X\<=0.05（5%） |
| trigger_price | String | 激活价格 ，填写值0\<X\<=1000000 |
冰山委托
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| algo_variance | String | 委托深度，填写值0\<=X\<=0.01（1%） |
| avg_amount | String | 单笔均值，填写2-500的整数（永续2-500的整数） |
| limit_price | String | 价格限制 ，填写值0\<X\<=1000000 |
| deal_value | String | 已成交量 |
时间加权
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| sweep_range | String | 扫单范围，填写值0.005（0.5%）\<=X\<=0.01（1%） |
| sweep_ratio | String | 扫单比例，填写值 0.01\<=X\<=1 |
| single_limit | String | 单笔上限，填写值10\<=X\<=2000（永续2-500的整数） |
| limit_price | String | 价格限制，填写值0\<X\<=1000000 |
| time_interval | String | 委托间隔，填写值5\<=X\<=120 |
| deal_value | String | 已委托量 |
止盈止损参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| tp_trigger_price | String | 止盈触发价格，填写值0\<X\<=1000000 |
| tp_price | String | 止盈委托价格，填写值0\<X\<=1000000 |
| tp_trigger_type | String | 1:限价 2:市场价；止盈触发价格类型，默认是限价；为市场价时，委托价格不必填； |
| sl_trigger_type | String | 1:限价 2:市场价；止损触发价格类型，默认是限价；为市场价时，委托价格不必填； |
| sl_trigger_price | String | 止损触发价格，填写值0\<X\<=1000000 |
| sl_price | String | 止损委托价格，填写值0\<X\<=1000000 |
| trigger_side | String | 触发方向：1:止盈 2:止损, |
| order_side | String | 下单委托方向：1:止盈 2:止损, 3双向 |
返回示例
{
"btc_usdt": [
{
"algo_id": "329967",
"algo_price": "7500",
"instrument_id": "btc_usdt",
"mode": "1",
"order_id": "",
"order_type": "1",
"rejected_at": "2019-10-09T15:59:59.000Z",
"side": "sell",
"size": "0.005",
"status": "3",
"timestamp": "2019-10-08T09:43:56.000Z",
"trigger_price": "8000"
},
{
"algo_id": "329997",
"algo_price": "7500",
"instrument_id": "btc_usdt",
"mode": "1",
"order_id": "",
"order_type": "1",
"rejected_at": "2019-10-09T15:59:59.000Z",
"side": "sell",
"size": "0.005",
"status": "1",
"timestamp": "2019-10-08T10:10:44.000Z",
"trigger_price": "8000"
}
]
}
公共-获取币对信息
获取交易币对的列表，查询各币对的交易限制和价格步长等信息。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/instruments
请求示例
GET/api/spot/v3/instruments
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instrument_id | String | 币对名称 |
| base_currency | String | 交易货币币种 |
| quote_currency | String | 计价货币币种 |
| min_size | String | 最小交易数量 |
| size_increment | String | 交易货币数量精度 |
| tick_size | String | 交易价格精度 |
| category | String | 手续费档位，1：第一档，2：第二档， 3：第三档 |
解释说明
min_size指下单数量的最小值（交易货币）。size_increment（交易数量步长）是指下单数量的最小增量。例如，当size_increment为0.000001，委托数量传入0.0000126将被系统按截尾法修正为0.000012。
tick_size（交易价格精度）是指下单价格的最小增量，委托价格必须是tick_size的倍数。例如，当tick_size为0.0001，委托价格传入0.02237将被系统按截尾法修正为0.0223。
返回示例
[
{
"base_currency":"BTC",
"instrument_id":"BTC-USDT",
"min_size":"0.001",
"quote_currency":"USDT",
"size_increment":"0.00000001",
"category":"1",
"tick_size":"0.1"
},
{
"base_currency":"ETH",
"instrument_id":"ETH-USDT",
"min_size":"0.001",
"quote_currency":"USDT",
"size_increment":"0.000001",
"category":"1",
"tick_size":"0.01"
}
]
公共-获取深度数据
获取币对的深度列表。这个请求不支持分页，一个请求返回整个深度列表。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/instruments/<instrument_id>/book
请求示例
GET/api/spot/v3/instruments/BTC-USDT/book?size=5&depth=0.2
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| size | String | 是 | 返回深度档位数量，最多返回200 |
| depth | String | 是 | 按价格合并深度，例如：0.1或0.001 |
| instrument_id | String | 是 | 币对 |
返回参数
返回数据
| 参数名 | 类型 | 描述 |
|---|---|---|
| asks | List<String> | 卖方深度 |
| bids | List<String> | 买方深度 |
| timestamp | String | 时间戳 |
解释说明
asks和bids值数组举例说明： ["411.8","10","8"] 411.8为深度价格，10为此价格数量，8为此深度由几笔订单组成。
当size不传时，返回200条；size传0时，返回0条；size最大200，传大于200的数时，返回200条。
按价格合并深度是指每个价格区间将仅返回一个数量，就像在该价格区间上只有一个订单。
asks: 卖方深度
bids: 买方深度
返回示例
{
"asks":[
[
"3993.2",
"0.41600068",
"1"
],
[
"3993.4",
"1.24807818",
"3"
]
],
"bids":[
[
"3993",
"0.15149658",
"2"
],
[
"3992.8",
"1.19046818",
"1"
]
],
"timestamp":"2019-03-20T03:55:37.888Z"
}
公共-获取全部ticker信息
获取平台全部币对的最新成交价、买一价、卖一价和24小时交易量的快照信息。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/instruments/ticker
请求示例
GET/api/spot/v3/instruments/ticker
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instrument_id | String | 币对名称 |
| last | String | 最新成交价 |
| last_qty | String | 最新成交的数量 |
| best_ask | String | 卖一价 |
| best_ask_size | String | 卖一价对应的量 |
| best_bid | String | 买一价 |
| best_bid_size | String | 买一价对应的数量 |
| open_24h | String | 24小时开盘价 |
| high_24h | String | 24小时最高价 |
| low_24h | String | 24小时最低价 |
| base_volume_24h | String | 24小时成交量，按交易货币统计 |
| quote_volume_24h | String | 24小时成交量，按计价货币统计 |
| timestamp | String | 系统时间戳 |
解释说明
最高价、最低价和成交量都是按最近24小时为维度统计的。
24小时开盘价取值来自24小时前那一分钟的K线的开盘价。即 2018年7月23日08:23:45，此时的涨跌幅依靠的是开盘价是2018年7月22日08:23:00时的价格。
返回示例
{
"best_ask": "7222.2",
"best_bid": "7222.1",
"instrument_id": "BTC-USDT",
"product_id": "BTC-USDT",
"last": "7222.2",
"last_qty": "0.00136237",
"ask": "7222.2",
"best_ask_size": "0.09207739",
"bid": "7222.1",
"best_bid_size": "3.61314948",
"open_24h": "7356.8",
"high_24h": "7367.7",
"low_24h": "7160",
"base_volume_24h": "18577.2",
"timestamp": "2019-12-11T07:48:04.014Z",
"quote_volume_24h": "134899542.8"
}
公共-获取某个ticker信息
获取币对的最新成交价、买一价、卖一价和24小时交易量的快照信息。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/instruments/<instrument-id>/ticker
请求示例
GET/api/spot/v3/instruments/BTC-USDT/ticker
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 币对 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instrument_id | String | 币对名称 |
| last | String | 最新成交价 |
| last_qty | String | 最新成交的数量 |
| best_ask | String | 卖一价 |
| best_ask_size | String | 卖一价对应的量 |
| best_bid | String | 买一价 |
| best_bid_size | String | 买一价对应的数量 |
| open_24h | String | 24小时开盘价 |
| high_24h | String | 24小时最高价 |
| low_24h | String | 24小时最低价 |
| base_volume_24h | String | 24小时成交量，按交易货币统计 |
| quote_volume_24h | String | 24小时成交量，按计价货币统计 |
| timestamp | String | 系统时间戳 |
解释说明
最高价、最低价和成交量都是按最近24小时为维度统计的。
24小时开盘价取值来自24小时前那一分钟的K线的开盘价。即 2018年7月23日08:23:45，此时的涨跌幅依靠的是开盘价是2018年7月22日08:23:00时的价格。
返回示例
{
"best_ask": "7222.2",
"best_bid": "7222.1",
"instrument_id": "BTC-USDT",
"product_id": "BTC-USDT",
"last": "7222.2",
"last_qty": "0.00136237",
"ask": "7222.2",
"best_ask_size": "0.09207739",
"bid": "7222.1",
"best_bid_size": "3.61314948",
"open_24h": "7356.8",
"high_24h": "7367.7",
"low_24h": "7160",
"base_volume_24h": "18577.2",
"timestamp": "2019-12-11T07:48:04.014Z",
"quote_volume_24h": "134899542.8"
}
公共-获取成交数据
本接口能查询最近100条数据。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/instruments/<instrument_id>/trades
签名请求示例
GET/api/spot/v3/instruments/LTC-USDT/trades?limit=20
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 币对名称 |
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| timestamp | String | 成交时间 |
| trade_id | String | 成交ID |
| price | String | 成交价格 |
| size | String | 成交数量 |
| side | String | 成交方向 |
解释说明
成交方向side是指Taker订单的下单方向，Taker表示主动与深度列表中挂单进行成交。buy表示价格上涨，因为Taker是买单吃掉深度，所以价格将上行。相反，sell表示价格下跌。
返回示例
[
{
"time":"2019-04-12T02:07:30.523Z",
"timestamp":"2019-04-12T02:07:30.523Z",
"trade_id":"1296412902",
"price":"4913.4",
"size":"0.00990734",
"side":"buy"
},
{
"time":"2019-04-12T02:07:30.455Z",
"timestamp":"2019-04-12T02:07:30.455Z",
"trade_id":"1296412899",
"price":"4913.2",
"size":"0.17820096",
"side":"sell"
}
]
公共-获取K线数据
获取币对的K线数据。K线数据按请求的粒度分组返回，K线数据最多可获取最近1440条。
限速规则：20次/2s
HTTP请求
GET/api/spot/v3/instruments/<instrument_id>/candles
签名请求示例
GET/api/spot/v3/instruments/BTC-USDT/candles?granularity=86400&start=2019-03-19T16:00:00.000Z&end=2019-03-20T16:00:00.000Z
请求参数
| 参数名 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 币对 |
| start | String | 否 | 开始时间（ISO 8601标准） |
| end | String | 否 | 结束时间（ISO 8601标准） |
| granularity | String | 否 | 时间粒度，以秒为单位，默认值60。如[60/180/300/900/1800/3600/7200/14400/21600/43200/86400/604800]，详见下解释说明 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| time | String | 开始时间 |
| open | String | 开盘价格 |
| high | String | 最高价格 |
| low | String | 最低价格 |
| close | String | 收盘价格 |
| volume | String | 交易量 |
解释说明
如果用户没有提供开始时间或结束时间中的任一字段，则两个字段都将被忽略。未提供开始时间和结束时间的请求，则系统按时间粒度返回最近的200条数据。
时间粒度granularity必须是[60 180 300 900 1800 3600 7200 14400 21600 43200 86400 604800 2678400 8035200 16070400 31536000]]中的任一值，否则请求将被拒绝。这些值分别对应的是[1min 3min 5min 15min 30min 1hour 2hour 4hour 6hour 12hour 1day 1week 1 month 3 months 6 months and 1 year]的时间段。
K线数据可能不完整。K线数据不应该轮询调用。
单次请求的最大数据量是200。如果您选择的开始/结束时间和时间粒度导致超过单次请求的最大数据量，您的请求将只会返回200个数据。如果您希望在更大的时间范围内获取足够精细的数据，则需要使用多个开始/结束范围进行多次请求。
返回示例
[
[
"2019-03-19T16:00:00.000Z",
"3997.3",
"4031.9",
"3982.5",
"3998.7",
"26175.21141385"
],
[
"2019-03-18T16:00:00.000Z",
"3980.6",
"4014.6",
"3968.9",
"3997.3",
"33053.48725643"
]
]
币币杠杆API
币币杠杆交易的行情信息，账户信息，订单操作，订单查询，账单明细查询。
说明：因为要和老版本做兼融，实际有些接口返回参数会有多余，请以文档中返回参数说明为准。
例如币币账户信息接口返回frozen，hold和holds参数值相同，以hold为准；获取借币记录接口返回参数 repay_amount 和 returned_amount，repay_interest 和paid_interest 参数的值相同，product_id和instrument_id相同等等
币币杠杆账户信息
获取币币杠杆账户资产列表，查询各币种的余额、冻结和可用等信息。
限速规则：20次/2s
HTTP请求
GET/api/margin/v3/accounts
签名请求示例
2018-09-13T02:25:41.946ZGET/api/margin/v3/accounts
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instrument_id | String | 杠杆币对名称 |
| currency | String | 杠杆币对下的币种名称 |
| balance | String | 余额 |
| hold | String | 冻结（不可用） |
| available | String | 可用于交易数量 |
| risk_rate | String | 风险率 |
| can_withdraw | String | 可划转数量 |
| liquidation_price | String | 强平价 |
| borrowed | String | 已借币（已借未还的部分） |
| lending_fee | String | 利息（未还的利息） |
| margin_ratio | String | 保证金率 |
| maint_margin_ratio | String | 维持保证金率 |
| tiers | String | 当前借币数量档位 |
解释说明
当你下市价单或限价单时，订单所需的资金将被冻结。这部分数量将不能被用于其他订单或者资金划转。资金将一直被冻结直至订单被成交或者取消。
返回示例
{
"currency:BTC": {
"available": "0",
"balance": "0",
"borrowed": "0",
"can_withdraw": "0",
"frozen": "0",
"hold": "0",
"holds": "0",
"lending_fee": "0"
},
"currency:USDT": {
"available": "0",
"balance": "0",
"borrowed": "0",
"can_withdraw": "0",
"frozen": "0",
"hold": "0",
"holds": "0",
"lending_fee": "0"
},
"liquidation_price": "0",
"maint_margin_ratio": "0.05",
"margin_ratio": "",
"risk_rate": "",
"tiers": "1"
}
单一币对账户信息
获取币币杠杆某币对账户的余额、冻结和可用等信息。
限速规则：20次/2s
HTTP请求
GET/api/margin/v3/accounts/<instrument_id>
签名请求示例
2018-09-13T02:25:41.946ZGET/api/margin/v3/accounts/eos-usdt
请求参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instrument_id | String | [ 必填 ] 币对 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| balance | String | 余额 |
| currency | String | 该币对下的币种名称 |
| hold | String | 冻结（不可用） |
| available | String | 可用于交易的数量 |
| risk_rate | String | 风险率 |
| can_withdraw | String | 可划转数量 |
| liquidation_price | String | 强平价 |
| borrowed | String | 已借币（已借未还的部分） |
| lending_fee | String | 利息（未还的利息） |
| margin_ratio | String | 保证金率 |
| maint_margin_ratio | String | 维持保证金率 |
| tiers | String | 当前借币数量档位 |
返回示例
{
"currency:BTC": {
"available": "0",
"balance": "0",
"borrowed": "0",
"can_withdraw": "0",
"frozen": "0",
"hold": "0",
"holds": "0",
"lending_fee": "0"
},
"currency:USDT": {
"available": "0",
"balance": "0",
"borrowed": "0",
"can_withdraw": "0",
"frozen": "0",
"hold": "0",
"holds": "0",
"lending_fee": "0"
},
"liquidation_price": "0",
"maint_margin_ratio": "0.05",
"margin_ratio": "",
"risk_rate": "",
"tiers": "1"
}
账单流水查询
列出杠杆帐户资产流水。帐户资产流水是指导致帐户余额增加或减少的行为。流水会分页，并且按时间倒序排序和存储，最新的排在最前面。请参阅分页部分以获取第一页之后的其他纪录。 本接口能查询最近3个月的数据。
限速规则：10次/2s
HTTP请求
GET/api/margin/v3/accounts/<instrument_id>/ledger
签名请求示例
2019-03-18T03:45:56.000ZGET/api/margin/v3/accounts/btc-usdt/ledger?limit=10&type=1&after=2
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 | |
|---|---|---|---|---|
| instrument_id | String | 是 | 币对 | |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的ledger_id |
|
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的ledger_id |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 | |
| type | String | 否 | 1.转入 2.转出 3.借币 4.还币 5.计息 7.买入 8.卖出 9.资金账户转入 10.法币转入 12.币币转入 14.转出至资金账户 15.转出至法币 16.转出至币币 19.强制还息 24.强平费 59.还糖果 61.币币杠杆账户转入 62.转出至币币杠杆账户 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ledger_id | String | 账单ID |
| instrument_id | String | 杠杆币对名称 |
| currency | String | 币种 |
| balance | String | 余额 |
| amount | String | 变动数量 |
| type | String | 流水来源 |
| timestamp | String | 账单创建时间 |
| details | String | 如果type是trade或者fee，则会有该details字段将包含order，instrument信息 |
| order_id | String | 交易的ID |
| 流水来源类型 | 描述 |
|---|---|
| transfer | 资金转入/转出 |
| trade | 交易产生的资金变动 |
| rebate | 返佣 |
返回示例
[
[
{
"created_at":"2019-03-20T05:45:10.000Z",
"ledger_id":"78965766",
"timestamp":"2019-03-20T05:45:10.000Z",
"currency":"EOS",
"amount":"0",
"balance":"0.59957711",
"type":"transfer",
"details":{
"instrument_id":"EOS-USDT",
"order_id":"787057",
"product_id":"EOS-USDT"
}
},
{
"created_at":"2019-03-20T04:45:07.000Z",
"ledger_id":"78942699",
"timestamp":"2019-03-20T04:45:07.000Z",
"currency":"EOS",
"amount":"0",
"balance":"0.59957711",
"type":"transfer",
"details":{
"instrument_id":"EOS-USDT",
"order_id":"787057",
"product_id":"EOS-USDT"
}
},
{
"created_at":"2019-03-20T03:45:05.000Z",
"ledger_id":"78918186",
"timestamp":"2019-03-20T03:45:05.000Z",
"currency":"EOS",
"amount":"0",
"balance":"0.59957711",
"type":"transfer",
"details":{
"instrument_id":"EOS-USDT",
"order_id":"787057",
"product_id":"EOS-USDT"
}
}
],
{
"OK-BEFORE":"78965766",
"OK-AFTER":"78918186"
}
]
杠杆配置信息
获取币币杠杆账户的借币配置信息，包括当前最大可借、借币利率、最大杠杆倍数。
限速规则：20次/2s
HTTP请求
GET/api/margin/v3/accounts/availability
签名请求示例
2018-09-13T02:27:05.580ZGET/api/margin/v3/accounts/availability
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instrument_id | String | 杠杆币对名称 |
| currency | String | 币种 |
| available | String | 当前最大可借 |
| rate | String | 借币利率 |
| leverage | String | 最大杠杆倍数 |
返回示例
[
{
"currency:BTC":{
"available":"0.09995502",
"leverage":"5",
"leverage_ratio":"5",
"rate":"0.00009984"
},
"currency:USDT":{
"available":"400.00000000",
"leverage":"5",
"leverage_ratio":"5",
"rate":"0.00019992"
},
"instrument_id":"BTC-USDT",
"product_id":"BTC-USDT"
},
{
"currency:EOS":{
"available":"1.9343",
"leverage":"5",
"leverage_ratio":"5",
"rate":"0.00009984"
},
"currency:USDT":{
"available":"7.1571",
"leverage":"5",
"leverage_ratio":"5",
"rate":"0.00019992"
},
"instrument_id":"EOS-USDT",
"product_id":"EOS-USDT"
}
]
某个杠杆配置信息
获取某个币币杠杆账户的借币配置信息，包括当前最大可借、借币利率、最大杠杆倍数。
限速规则：20次/2s
HTTP请求
GET/api/margin/v3/accounts/<instrument_id>/availability
签名请求示例
2019-03-18T02:27:37.723ZGET/api/margin/v3/accounts/BTC-USDT/availability
请求参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instrument_id | String | [ 必填 ] 币对 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| currency | String | 币种 |
| available | String | 当前最大可借 |
| rate | String | 借币利率 |
| leverage | String | 最大杠杆倍数 |
| instrument_id | String | 币对 |
返回示例
[
{
"currency:BTC":{
"available":"0.09989261",
"leverage":"5",
"leverage_ratio":"5",
"rate":"0.00009984"
},
"currency:USDT":{
"available":"400.00000000",
"leverage":"5",
"leverage_ratio":"5",
"rate":"0.00019992"
},
"instrument_id":"BTC-USDT",
"product_id":"BTC-USDT"
}
]
获取借币记录
获取币币杠杆帐户的借币记录。这个请求支持分页，并且按时间倒序排序和存储，最新的排在最前面。请参阅分页部分以获取第一页之后的其他纪录。
限速规则：20次/2s
HTTP请求
GET/api/margin/v3/accounts/borrowed
签名请求示例
2018-09-13T02:28:14.618ZGET/api/margin/v3/accounts/borrowed?status=0&limit=1&after=2
请求参数
| 参数名 | 类型 | 描述 | |
|---|---|---|---|
| status | String | [ 非必填 ] 状态0：未还清 1：已还清 |
|
| after | String | [ 非必填 ] 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的borrow_id |
|
| before | String | [ 非必填 ] 请求此id之后（更新的数据）的分页内容，传的值为对应接口的borrow_id |
|
| limit | String | [ 非必填 ] 分页返回的结果集数量，默认为100，最大为100（具体参见分页处的描述） |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| borrow_id | String | 借币记录ID |
| instrument_id | String | 杠杆币对名称 |
| currency | String | 币种 |
| timestamp | String | 借币时间 |
| amount | String | 借币总数量 |
| interest | String | 利息总数量 |
| returned_amount | String | 已还借币数量 |
| paid_interest | String | 已还利息数量 |
| last_interest_time | String | 最后一次计息时间 |
| force_repay_time | String | 强制还息时间 |
| rate | String | 利率 |
返回示例
[
{
"amount":"0.5",
"borrow_id":"787057",
"created_at":"2019-03-18T09:41:44.000Z",
"currency":"EOS",
"force_repay_time":"2019-03-25T09:42:19.000Z",
"instrument_id":"EOS-USDT",
"interest":"0.0000386883807232",
"last_interest_time":"2019-03-20T05:45:11.000Z",
"paid_interest":"0.00000208",
"product_id":"EOS-USDT",
"rate":"0.00000416",
"repay_amount":"0.29999792",
"repay_interest":"0.00000208",
"returned_amount":"0.29999792",
"timestamp":"2019-03-18T09:41:44.000Z"
}
]
某币对借币记录
获取币币杠杆帐户某币对的借币记录。这个请求支持分页，并且按时间倒序排序和存储，最新的排在最前面。请参阅分页部分以获取第一页之后的其他纪录。
限速规则：20次/2s
HTTP请求
GET/api/margin/v3/accounts/<instrument_id>/borrowed
签名请求示例
2018-09-13T02:29:06.610ZGET/api/margin/v3/accounts/BTC-USDT/borrowed?limit=2&status=1&after=2
请求参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| status | String | [ 非必填 ] 状态0：未还清 1：已还清 |
| after | String | [ 非必填 ] 请求此id之前（更旧的数据）的分页内容（举例一列数：1，2，3，4，5。after 4 只有5，to 4有1，2，3） |
| before | String | [ 非必填 ] 请求此id之后（更新的数据）的分页内容 |
| limit | String | [ 非必填 ] 分页返回的结果集数量，默认为100，最大为100（具体参见分页处的描述） |
| instrument_id | String | [ 必填 ] 币对 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| borrow_id | String | 借币记录ID |
| instrument_id | String | 杠杆币对名称 |
| currency | String | 币种 |
| timestamp | String | 借币时间 |
| amount | String | 借币总数量 |
| interest | String | 利息总数量 |
| returned_amount | String | 已还借币数量 |
| paid_interest | String | 已还利息数量 |
| last_interest_time | String | 最后一次计息时间 |
| force_repay_time | String | 强制还息时间 |
| rate | String | 利率 |
返回示例
[
{
"amount":"0.5",
"borrow_id":"787057",
"created_at":"2019-03-18T09:41:44.000Z",
"currency":"EOS",
"force_repay_time":"2019-03-25T09:42:19.000Z",
"instrument_id":"EOS-USDT",
"interest":"0.0000386883807232",
"last_interest_time":"2019-03-20T05:45:11.000Z",
"paid_interest":"0.00000208",
"product_id":"EOS-USDT",
"rate":"0.00000416",
"repay_amount":"0.29999792",
"repay_interest":"0.00000208",
"returned_amount":"0.29999792",
"timestamp":"2019-03-18T09:41:44.000Z"
}
]
借币
在某个币币杠杆账户里进行借币。
限速规则：100次/2s
HTTP请求
POST /api/margin/v3/accounts/borrow
签名请求示例
2018-10-08T03:00:56.799ZPOST/api/margin/v3/accounts/borrow{"instrument_id":"ltc-usdt","currency":"usdt","amount":"0.1"}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 杠杆币对名称 |
| client_oid | String | 否 | 由您设置的订单ID来识别您的订单 |
| currency | String | 是 | 币种 |
| amount | String | 是 | 借币数量 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| borrow_id | String | 借币记录ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| result | Boolean | 结果 |
返回示例
{
"borrow_id":"791434",
"client_oid":"",
"result":true
}
还币
在某个币币杠杆账户里进行还币。
限速规则：100次/2s
HTTP请求
POST /api/margin/v3/accounts/repayment
签名请求示例
2018-10-08T03:04:52.002ZPOST/api/margin/v3/accounts/repayment{"instrument_id":"ltc-usdt","currency":"usdt","amount":"0.1","borrow_id":"185759"}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| borrow_id | String | 否 | 借币记录ID，不填时还整个币对的币 |
| client_oid | String | 否 | 由您设置的订单ID来识别您的订单 |
| instrument_id | String | 是 | 杠杆币对名称 |
| currency | String | 是 | 币种 |
| amount | String | 是 | 还币数量 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| repayment_id | String | 还币记录ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| result | Boolean | 结果 |
返回示例
{
"client_oid":"",
"repayment_id":"791434",
"result":true
}
下单
API提供limit和market和高级限价委托等下单模式。只有当您的账户有足够的资金才能下单。一旦下单，您的账户资金将在订单生命周期内被冻结。被冻结的资金以及数量取决于订单指定的类型和参数。
限速规则：100次/2s
HTTP请求
POST /api/margin/v3/orders
签名请求示例
2018-09-12T07:46:47.098ZPOST/api/margin/v3/orders{"client_oid":"yt20180728","order_type":"0","instrument_id":"btc-usdt","side":"buy","type":"market","size":"0.1","notional":"100","margin_trading":"2"}
请求参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| client_oid | String | 否 | 由您设置的订单ID来识别您的订单 ，类型为字母（大小写）+数字或者纯字母（大小写），1-32位字符 |
| type | String | 否 | limit 或 market（默认是limit）。当以market（市价）下单，order_type只能选择0（普通委托） |
| side | String | 是 | buy 或 sell |
| instrument_id | String | 是 | 币对名称 |
| order_type | String | 否 | 参数填数字0：普通委托（order type不填或填0都是普通委托） 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
| margin_trading | String | 是 | 下单类型（当前为币币杠杆交易，请求值为2） |
限价单特殊参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| price | String | 是 | 价格 |
| size | String | 是 | 买入或卖出的数量 |
市价单特殊参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| size | String | 否 | 卖出数量，市价卖出必填size |
| notional | String | 否 | 买入金额，市价买入时必填notional |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| error_code | String | 错误码，下单成功时为0，下单失败时会显示相应错误码 |
| error_message | String | 错误信息，下单成功时为空，下单失败时会显示错误信息 |
| result | Boolean | 下单结果。若是下单失败，将给出错误码提示。 |
解释说明
client_oid的类型为字母+数字或者纯字母（大小写），1-32位字符 ，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，撤单和查询订单时只能撤销或者查询出最新的一条数据。
instrument_id
instrument_id必须是有效的币对。币对列表可通过/ instruments接口获取。
type
下单时，您可以指定订单类型。您指定的订单类型将决定是否需要其他订单参数以及撮合引擎如何执行您的订单。如果type没有指定，订单类型将默认为limit。限价单既是默认订单类型，也是基本订单类型。限价单需要指定price和size。size是买入或卖出交易货币的数量，price表示每个交易货币相对计价货币的价格。限价单会按指定价格或更好的价格成交。根据市场条件，卖单可以按照指定价格或者更高价格来成交，买单可以按照指定价格或更低价格成交。如果限价单不能立即成交，那么限价单将进入深度列表，直到被另一个新订单成交或被用户撤单。
市价单不同于限价单，因为它们不提供价格控制。市价单提供了一种不必指定价格，而以固定数量的货币进行买入或者卖出的方式。市价单下单后会立即撮合，而不会被挂入深度列表。市价单总是吃单方（taker）并承担taker费用。
price
price表示买入或卖出的价格。价格必须是价格步长size_increment的倍数。价格步长size_increment是价格的最小增量，可通过instruments接口获取。
size
size表示买入或卖出交易货币的数量。数量必须大于min_size。交易数量步长size_increment是数量的最小增量。上述参数都可通过instruments接口获取。
notional
notional表示被用于市价买入的计价货币的数量，市价买入时必填。例如，在BTC-USDT交易时，市价单指定5000 USDT表示将花费5000 USDT购买BTC。
hold
对于限价买单，系统将冻结计价货币的数量 = 限定价格 x 买入数量。对于限价卖单，系统将冻结你想卖出的交易货币的数量。对于市价买单，funds数量的计价货币将被冻结。对于市价卖单，size数量的交易货币将被冻结。如果您取消部分成交或未成交的订单，剩余资金将被解除冻结。
订单生命周期
HTTP请求将在订单被拒绝（资金不足，参数无效等）或下单成功（由匹配引擎接受）时作出响应。一个200响应表示该订单被接收并且进入撮合。进入撮合的订单可以部分或全部立即成交（取决于价格和市场条件）。部分成交的时候将把订单的剩余数量继续进行撮合。完全成交的订单将进入已成交状态。
监听行情数据的用户建议使用client_oid字段以便在接受到的信息中标识对应的数据。
响应
成功接受的订单将被分配一个订单ID。成功接受的订单表示撮合引擎已经接受的订单。 未成交的订单不会过期，并将保持撮合状态，直到被成交或取消。
返回示例
{
"client_oid":"oktlever50",
"error_message": "",
"error_code": "0",
"order_id":"2512084870235136",
"result":true
}
批量下单
下指定币对的多个订单（每次只能下最多4个币对且每个币对可批量下10个单）。
限速规则：50次/2s
HTTP请求
POST /api/margin/v3/batch_orders
签名请求示例
市价单：POST /api/margin/v3/batch_orders[{"client_oid":"t20180728","order_type":"1","instrument_id":"btc-usdt","side":"sell","type":"market"," size ":"0.001"," notional ":"10001","margin_trading ":"2"},{"client_oid":"yy20180728","instrument_id":"btc-usdt","side":"sell","type":"limit"," size ":"0.001","notional":"10002","margin_trading ":"2"}
限价单：POST /api/margin/v3/batch_orders[{"client_oid":"y20180728","order_type":"1","instrument_id":"btc-usdt","side":"sell","type":"limit","size":"0.001","price":"10001","margin_trading ":"2"},{"client_oid":"yt20180728","instrument_id":"btc-usdt","side":"sell","type":"limit","size":"0.001","price":"10002","margin_trading ":"2"}
请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| client_oid | String | 否 | 由您设置的订单ID来识别您的订单， 类型为字母（大小写）+数字或者纯字母（大小写）1-32位字符 |
| type | String | 否 | limit 或 market（默认是limit）。当以market（市价）下单，order_type只能选择0（普通委托） |
| side | String | 是 | buy 或 sell |
| instrument_id | String | 是 | 币对名称 |
| order_type | String | 否 | 参数填数字0：普通委托（order_type不填或填0都是普通委托）1：只做Maker（Post only）2：全部成交或立即取消（FOK）3：立即成交并取消剩余（IOC） |
| margin_trading | String | 是 | 下单类型（当前为币币杠杆交易，请求值为2） |
限价单特殊参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| price | String | 是 | 价格 |
| size | String | 是 | 买入或卖出的数量 |
市价单特殊参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| size | String | 否 | [ 非必填 ] 卖出数量，市价卖出必填size |
| notional | String | 否 | [ 非必填 ] 买入金额，市价买入时必填notional |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| error_code | String | 错误码，下单成功时为0，下单失败时会显示相应错误码 |
| error_message | String | 错误信息，下单成功时为空，下单失败时会显示错误信息 |
| result | Boolean | 下单结果。若是下单失败，将给出错误码提示。 |
解释说明
client_oid的类型为字母（大小写）+数字或者纯字母（大小写）1-32位字符 ，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，撤单和查询订单时只能撤销或者查询最新的一条数据。
每次最多4个币对且每个币对最多10个订单，建议用户调用批量撤单接口后，再调用获取订单列表接口确认已撤销成功。
返回示例
{
"BTC-USDT":[
{
"client_oid":"oktlever51",
"error_message": "",
"error_code": "0",
"order_id":"2512113685627904",
"result":true
},
{
"client_oid":"oktlever52",
"error_message": "",
"error_code": "0",
"order_id":"2512113687135232",
"result":true
}
]
}
撤销指定订单
撤销之前下的未完成订单。
限速规则：100次/2s
HTTP请求
POST /api/margin/v3/cancel_orders/<order_id> or <client_oid>
签名请求示例
2018-10-12T07:34:30.223ZPOST/api/margin/v3/cancel_orders/a123{"instrument_id":"btc-usdt"}
请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 提供此参数则撤销指定币对的相应订单，如果不提供此参数则返回错误码 |
| client_oid | String | 非必填 | order_id和client_oid必须且只能选一个填写，由您设置的订单ID来识别您的订单 , 类型为字母（大小写）+数字或者纯字母（大小写）1-32位字符 |
| order_id | String | 非必填 | order_id和client_oid必须且只能选一个填写，订单ID |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| error_code | String | 错误码，撤单成功时为0，撤单失败时会显示相应错误码 |
| error_message | String | 错误信息，撤单成功时为空，撤单失败时会显示错误信息 |
| result | Boolean | 撤单申请结果。若是撤单失败，将给出错误码提示 |
解释说明
order_id和client_oid必须且只能选一个填写
使用client_oid撤单时，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，撤单时只能撤销最新的一条数据
如果订单无法取消（已经成交或已取消），那么返回的报错内容里将显示相应的原因。
返回示例
{
"result":true,
"client_oid":"a123",
"order_id": "2510832677225473",
"error_message": "",
"error_code": "0"
}
批量撤销订单
撤销指定的某一种或多种币对的所有未完成订单，每个币对可批量撤10个单。
限速规则：50次/2s
HTTP请求
POST /api/margin/v3/cancel_batch_orders
使用orderid撤单 签名请求示例
2018-10-12T07:30:49.664ZPOST/api/margin/v3/cancel_batch_orders[{"instrument_id":"btc-usdt","client_oids":["a123","a1234"]},{"instrument_id":"ltc-usdt","client_oids":["a12345","a123456"]}]
请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 提供此参数则撤销指定一个或多个币对的订单，如果不提供此参数则返回错误码，此字段支持传多个值。此参数为[''btc-usdt'',''ltc-eth'']，推荐使用中横线连接币种，下划线连接的方式也同时兼容 |
| order_ids | List<String> | 否 | order_id和client_oid必须且只能选一个填写，订单ID |
| client_oids | List<String> | 否 | order_id和client_oid必须且只能选一个填写，由您设置的订单ID来识别您的订单，类型为字母（大小写）+数字或者纯字母（大小写）1-32位字符 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| instrument_id | String | 币种，如btc-usdt |
| result | Boolean | 撤单申请结果。若是撤单失败，将给出错误码提示 |
| error_code | String | 错误码，撤单成功时为0，撤单失败时会显示相应错误码 |
| error_message | String | 错误信息，撤单成功时为空，撤单失败时会显示错误信息 |
解释说明
批量撤单一次性时候，要么都是order_id要么都是client_oid，否则会提示错误
使用client_oid批量撤单时，目前只支持一个币对下撤一个client_oid ，一次四个币对，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，撤单时只能撤销最新的一条数据
使用order_id撤单时，每次最多4个币对且每个币对最多10个订单，建议用户调用批量撤单接口后，再调用获取订单列表接口确认已撤销成功。
返回示例
{
"btc-usdt":[
{
"result":true,
"client_oid":"a123",
"order_id": "2510832677225473",
"error_message": "",
"error_code": "0"
},
{
"result":true,
"client_oid":"a1234",
"order_id": "2510832677225474",
"error_message": "",
"error_code": "0"
}
],
"ltc-usdt":[
{
"result":true,
"client_oid":"a12345",
"order_id": "2510832677225475",
"error_message": "",
"error_code": "0"
},
{
"result":true,
"client_oid":"a123456",
"order_id": "2510832677225476",
"error_message": "",
"error_code": "0"
}
]
}
获取订单列表
列出您当前所有的订单信息（本接口能查询最近3个月订单信息）。这个请求支持分页，并且按委托时间倒序排序和存储，最新的排在最前面。
限速规则：10次/2s
HTTP请求
GET/api/margin/v3/orders
签名请求示例
2018-09-12T07:49:43.306ZGET/api/margin/v3/orders?instrument_id=BTC-USDT&state=0&limit=2&after=2500723297223680
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 | |
|---|---|---|---|---|
| instrument_id | String | 是 | 币对名称 | |
| state | String | 是 | 订单状态-2:失败-1:撤单成功0:等待成交1:部分成交2:完全成交3:下单中4:撤单中6: 未完成（等待成交+部分成交）7:已完成（撤单成功+完全成交） |
|
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的order_id |
|
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的order_id |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 用户设置的订单ID |
| price | String | 委托价格 |
| size | String | 委托数量（交易货币数量） |
| notional | String | 买入金额，市价买入时返回 |
| instrument_id | String | 币对名称 |
| side | String | buy 或 sell |
| type | String | limit或market（默认是limit） |
| timestamp | String | 订单创建时间 |
| filled_size | String | 已成交数量 |
| filled_notional | String | 已成交金额 |
| order_type | String | 0：普通委托 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
| state | String | 订单状态-2：失败 -1：撤单成功 0：等待成交 1：部分成交 2：完全成交 3：下单中 4：撤单中 |
| price_avg | String | 成交均价 |
解释说明
client_oid的类型为字母（大小写）+数字或者纯字母（大小写），1-32位字符 ，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，查询订单时只能查询出最新的一条数据。
最新的定义为 先从未成交表查，如果未成交表没有，再查已成交表的最新数据。
如果订单在其生命周期内没有任何成交，其记录可能被清除。这表示订单详细信息将不可用本接口来获取。
未成交的订单可能会根据市场情况在你发起请求和服务器响应之间改变状态。
返回示例
[
{
"client_oid":"oktlever56",
"created_at":"2019-03-20T08:21:49.000Z",
"filled_notional":"0",
"filled_size":"0",
"funds":"",
"instrument_id":"BTC-USDT",
"notional":"",
"order_id":"2512264176206848",
"order_type":"0",
"price":"3613.3",
"price_avg": "3613.3",
"product_id":"BTC-USDT",
"side":"buy",
"size":"0.001",
"status":"open",
"state":"0",
"timestamp":"2019-03-20T08:21:49.000Z",
"type":"limit"
},
{
"client_oid":"oktlever55",
"created_at":"2019-03-20T08:21:49.000Z",
"filled_notional":"0",
"filled_size":"0",
"funds":"",
"instrument_id":"BTC-USDT",
"notional":"",
"order_id":"2512264174306304",
"order_type":"0",
"price":"3613.3",
"price_avg": "3613.3",
"product_id":"BTC-USDT",
"side":"buy",
"size":"0.001",
"status":"open",
"state":"0",
"timestamp":"2019-03-20T08:21:49.000Z",
"type":"limit"
}
]
获取订单信息
通过订单ID获取单个订单信息。已撤销的未成交单只保留2个小时。
限速规则：20次/2s
HTTP请求
GET/api/margin/v3/orders/<order_id>
或者
GET/api/margin/v3/orders/<client_oid>
签名请求示例
2018-09-13T02:39:22.475ZGET/api/margin/v3/orders/23458?instrument_id=btc-usdt
或
2018-09-13T02:39:22.475ZGET/api/margin/v3/orders/etyery8?instrument_id=btc-usdt
请求参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instrument_id | String | [ 必填 ] 币对 |
| order_id | String | [非必填 ] 订单ID order_id和client_oid必须且只能选一个填写 |
| client_oid | String | [非必填 ] order_id和client_oid必须且只能选一个填写 由您设置的订单ID来识别您的订单 ， 类型为字母（大小写）+数字或者纯字母（大小写）1-32位字符 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由您设置的订单ID来识别您的订单 |
| price | String | 委托价格 |
| size | String | 委托数量（交易货币数量） |
| notional | String | 买入金额，市价买入时返回 |
| instrument_id | String | 币对名称 |
| side | String | buy 或 sell |
| type | String | limit或market（默认是limit） |
| timestamp | String | 订单创建时间 |
| filled_size | String | 已成交数量 |
| filled_notional | String | 已成交金额 |
| order_type | String | 0：普通委托 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
| state | String | -2:失败-1:撤单成功0:等待成交1:部分成交2:完全成交3:下单中4:撤单中 |
| price_avg | String | 成交均价 |
解释说明
status为state旧版参数，会短期兼容，建议尽早切换state。
order_id和client_oid必须且只能选一个填写
client_oid的类型为字母（大小写）+数字或者纯字母（大小写），1-32位字符 ，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，查询订单时只能查询出最新的一条数据。
最新的定义为 先从未成交表查，如果未成交表没有，再查已成交表的最新数据。
如果订单在其生命周期内没有任何成交，其记录可能被清除，则响应可能因为没有相应的匹配而返回状态码404。
未成交的订单可能会根据市场情况在你发起请求和服务器响应之间改变状态。
返回示例
{
"client_oid":"",
"created_at":"2019-03-18T03:45:55.000Z",
"filled_notional":"1.504",
"filled_size":"0.4",
"funds":"",
"instrument_id":"EOS-USDT",
"notional":"",
"order_id":"2499854635054080",
"order_type":"0",
"price":"3.76",
"price_avg":"3.76",
"product_id":"EOS-USDT",
"side":"buy",
"size":"0.4",
"status":"filled",
"state": "0",
"timestamp":"2019-03-18T03:45:55.000Z",
"type":"limit"
}
获取所有未成交订单
列出您当前所有的订单信息。这个请求支持分页，并且按时间倒序排序和存储，最新的排在最前面。请参阅分页部分以获取第一页之后的其他纪录。
限速规则：20次/2s
HTTP请求
GET/api/margin/v3/orders_pending
签名请求示例
2019-03-20T07:51:51.138ZGET/api/margin/v3/orders_pending?limit=2&instrument_id=BTC-USDT&after=2500723297223680
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 | |
|---|---|---|---|---|
| instrument_id | String | 是 | 币对名称 | |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的order_id |
|
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的order_id等 |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 用户设置的订单ID |
| price | String | 委托价格 |
| size | String | 委托数量（交易货币数量） |
| notional | String | 买入金额，市价买入时返回 |
| instrument_id | String | 币对名称 |
| order_type | String | 0：普通委托 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
| side | String | buy 或 sell |
| type | String | limit或market（默认是limit） |
| timestamp | String | 订单创建时间 |
| filled_size | String | 已成交数量 |
| filled_notional | String | 已成交金额 |
| state | String | 订单状态0:等待成交 |
解释说明
status为state旧版参数，会短期兼容，建议尽早切换state。
client_oid的类型为字母（大小写）+数字或者纯字母（大小写）1-32位字符 ，用户需要自己保证此ID不重复，不会进行排重提示，如有重复，查询订单时只能查询出最新的一条数据。
本接口只能查询所有未成交或者部分成交的订单
未成交的订单可能会根据市场情况在你发起请求和服务器响应之间改变状态。
返回示例
[
{
"client_oid":"oktlever56",
"created_at":"2019-03-20T08:21:49.000Z",
"filled_notional":"0",
"filled_size":"0",
"funds":"",
"instrument_id":"BTC-USDT",
"notional":"",
"order_id":"2512264176206848",
"order_type":"0",
"price":"3613.3",
"price_avg":"",
"product_id":"BTC-USDT",
"side":"buy",
"size":"0.001",
"status":"open",
"state":"0",
"timestamp":"2019-03-20T08:21:49.000Z",
"type":"limit"
},
{
"client_oid":"oktlever55",
"created_at":"2019-03-20T08:21:49.000Z",
"filled_notional":"0",
"filled_size":"0",
"funds":"",
"instrument_id":"BTC-USDT",
"notional":"",
"order_id":"2512264174306304",
"order_type":"0",
"price":"3613.3",
"price_avg":"",
"product_id":"BTC-USDT",
"side":"buy",
"size":"0.001",
"status":"open",
"state":"0",
"timestamp":"2019-03-20T08:21:49.000Z",
"type":"limit"
}
]
获取成交明细
获取最近的成交明细列表。这个请求支持分页，并且按时间倒序排序和存储，最新的排在最前面。请参阅分页部分以获取第一页之后的其他纪录。 本接口能查询最近3月的数据。
限速规则：10次/2s
HTTP请求
GET/api/margin/v3/fills
签名请求示例
2018-09-13T02:44:54.823ZGET/api/margin/v3/fills?order_id=23239&instrument_id=btc-usdt&limit=1&after=2
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 | |
|---|---|---|---|---|
| order_id | String | 否 | 订单ID，不填写order_id，返回当前instrument_id下的所有订单成交明细 |
|
| instrument_id | String | 是 | 币对名称 | |
| after | String | 否 | 请求此id之前（更旧的数据）的分页内容，传的值为对应接口的ledger_id |
|
| before | String | 否 | 请求此id之后（更新的数据）的分页内容，传的值为对应接口的ledger_id |
|
| limit | String | 否 | 分页返回的结果集数量，最大为100，不填默认返回100条 |
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| ledger_id | String | 账单ID |
| instrument_id | String | 币对名称 |
| price | String | 价格 |
| size | String | 数量 |
| order_id | String | 订单ID |
| timestamp | String | 订单成交时间 |
| exec_type | String | 流动性方向（T 或 M） |
| fee | String | 手续费 |
| side | String | 订单方向（buy 或 sell） |
| currency | String | 币种 |
解释说明
此接口一笔成交会返回2条数据，一个以计价货币计算的，一个是以交易货币计算的。
手续费
fee字段表示这条账单记录所收取的手续费。
流动性
exec_type字段表示该账单是maker还是taker产生的。M表示Maker，T表示Taker。
分页
返回账单列表的ledger_id按降序排列，从最大ledger_id到最小ledger_id。OK-AFTER都会有这样的第一笔ledger_id，以便将来的请求使用OK-after参数将获取一个更大的ledger_id（新的账单）。
返回示例
[
{
"created_at": "2019-11-25T07:45:05.000Z",
"currency": "USDT",
"exec_type": "M",
"fee": "-0.01915417",
"instrument_id": "OKB-USDT",
"ledger_id": "8161858573",
"liquidity": "M",
"order_id": "3927696997697536",
"price": "1.7793",
"product_id": "OKB-USDT",
"side": "buy",
"size": "19.1541645",
"timestamp": "2019-11-25T07:45:05.000Z"
},
{
"created_at": "2019-11-25T07:45:05.000Z",
"currency": "OKB",
"exec_type": "M",
"fee": "0",
"instrument_id": "OKB-USDT",
"ledger_id": "8161858572",
"liquidity": "M",
"order_id": "3927696997697536",
"price": "1.7793",
"product_id": "OKB-USDT",
"side": "sell",
"size": "10.765",
"timestamp": "2019-11-25T07:45:05.000Z"
}
]
获取杠杆倍数
获取币币杠杆账户币种杠杆倍数
限速规则：5次/2s
HTTP请求
GET/api/margin/v3/accounts/<instrument_id>/leverage
请求示例
GET/api/margin/v3/accounts/btc-usdt/leverage
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 币对名称，如：BTC-USDT |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| instrument_id | String | 币对名称，如：BTC-USDT |
| leverage | String | 杠杆倍数 |
| error_code | String | 错误码 |
| error_message | String | 错误信息 |
| result | Boolean | 请求结果 |
返回示例
{
"error_code": "",
"error_message": "",
"instrument_id": "btc-usdt",
"leverage": "3",
"result": true
}
设置杠杆倍数
设置币币杠杆账户币对杠杆倍数。
限速规则：5次/2s
HTTP请求
POST /api/margin/v3/accounts/<instrument_id>/leverage
请求示例
POST /api/margin/v3/accounts/BTC-USDT/leverage{"leverage":"10"}
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 |
|---|---|---|---|
| leverage | String | 是 | 要设定的杠杆倍数，填写2-10的数值 |
| instrument_id | String | 是 | 币对，如：BTC-USDT,LTC-USDT |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| leverage | String | 已设定的杠杆倍数，2-10的数值 |
| instrument_id | String | 币对，如：BTC-USDT |
| error_code | String | 错误码 |
| error_message | String | 错误信息 |
| result | Boolean | 请求结果 |
返回示例
{
"error_code": "",
"error_message": "",
"instrument_id": "BTC-USDT",
"leverage": "7",
"result": true
}
公共-币币杠杆行情
要实时更新市场数据，请参阅WebSocket文档，以便获取并创建更完整的深度和交易数据。
币币杠杆交易和币币交易共享行情和深度数据，请移步币币行情查看接口。
公共-获取标记价格
获取现货杠杆标记价格。此接口为公共接口，不需要身份验证。
限速规则：20次/2s
HTTP请求
GET/api/margin/v3/instruments/<instrument_id>/mark_price
请求示例
GET/api/margin/v3/instruments/EOS-USDT/mark_price
请求参数
| 参数名 | 参数类型 | 是否必须 | 描述 |
|---|---|---|---|
| instrument_id | String | 是 | 杠杆币对名称 |
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| instrument_id | String | 杠杆币对名称 |
| mark_price | String | 指定杠杆的标记价格 |
| timestamp | String | 返回请求时间 |
返回示例
{
"mark_price":"3.591",
"instrument_id":"EOS-USDT",
"timestamp":"2019-06-22T06:28:53.208Z"
}
WebSocketAPI
现货
以下是现货V3 WebscoketAPI，除了account有单独频道，其余频道数据对币币通用。
概述
WebSocket是HTML5一种新的协议（Protocol）。它实现了客户端与服务器全双工通信， 使得数据可以快速地双向传播。通过一次简单的握手就可以建立客户端和服务器连接， 服务器根据业务规则可以主动推送信息给客户端。其优点如下：
- 客户端和服务器进行数据传输时，请求头信息比较小，大概2个字节。
- 客户端和服务器皆可以主动地发送数据给对方。
- 不需要多次创建TCP请求和销毁，节约宽带和服务器的资源。
强烈建议开发者使用WebSocket API获取市场行情和买卖深度等信息。
地址：wss://real.okex.com:8443/ws/v3?brokerId=
访问时需要科学上网
连接说明：
所有返回数据都进行了压缩，需要用户将接收到的数据进行解压。解压缩请参考demo
连接上ws后30s未订阅或订阅后30s内服务器未向用户推送数据，系统会自动断开连接
指令格式
请求格式：
{"op": "<value>", "args": ["<value1>","<value2>"]}
其中 op 的取值为 1--subscribe 订阅； 2-- unsubscribe 取消订阅 ；3--login 登录
args: 取值为频道名，可以定义一个或者多个频道
成功响应格式:
{"event": "<value>","channel":"<value>"}
{"table":"channel","data":"[{"<value1>","<value2>"}]"}
其中spot/depth 频道为了区分是首次全量和后续的增量返回格式将会是
{"table":"channel", "action":"<value>","data":"[{"<value1>","<value2>"}]"}
失败响应格式:
{"event":"error","message":"<error_message>","errorCode":"<errorCode>"}
订阅
用户可以选择订阅一个或者多个频道，多个频道总长度不能超过4096个字节
{"op": "subscribe", "args": ["<SubscriptionTopic>"]}
说明 ：op 的取值是 subscribe
args 数组内容为频道名称 ：<channelname>:<filter>
其中`channelname 是以 business/channel组成
现货推送业务business为spot， channel为此业务下每个具体的名称，如果channel的名字不能以一个字母区分将会以 " _ " 进行连接
例：
"spot/ticker:BTC-USDT"or "spot/margin_account:BTC-USDT"
filter 是可筛选数据，具体参考每个频道说明
示例：
send:
{"op": "subscribe", "args": ["spot/ticker:ETH-USDT","spot/candle60s:ETH-USDT"]}
response:
{"event":"subscribe","channel":"spot/ticker:ETH-USDT"}
{"event":"subscribe","channel":"spot/candle60s:ETH-USDT"}
{"table":"spot/ticker","data":[{"instrument_id":"ETH-USDT","last":"8.8","best_bid":"3","best_ask":"8.1","open_24h":"5.1","high_24h":"8.8","low_24h":"3",
"base_volume_24h":"13.77340909","quote_volume_24h":"78.49886361","timestamp":"2018-12-20T03:13:41.664Z"}]}
{"table":"spot/candle60s","data":[{"candle":["2018-12-20T06:18:00.000Z","8.8","8.8","8.8","8.8","0"],"instrument_id":"ETH-USDT"}]}
取消订阅
可以取消一个或者多个频道
{"op": "unsubscribe", "args": [<SubscriptionTopic>]}
例如：
请求：
{"op": "unsubscribe", "args": ["spot/ticker:BTC-USDT", "spot/candle60s:BTC-USDT"]}
返回：
{"event":"unsubscribe","channel":"spot/ticker:BTC-USDT"}
{"event":"unsubscribe","channel":"spot/candle60s:BTC-USDT"}
登录
签名方式说明参考API概述里的验证部分
登录订阅格式：
{"op":"login","args":["<api_key>","<passphrase>","<timestamp>","<sign>"]}
响应：
{"event":"login","success":true}
例：
{"op":"login","args":["985d5b66-57ce-40fb-b714-afc0b9787083","123456","1538054050.975",
"7L+zFQ+CEgGu5rzCj4+BdV2/uUHGqddA9pI6ztsRRPs="]}
api_key:为用户申请的APIKey
Passphrase:为申请v3 api时所填写
timestamp:为时间戳 是Unix Epoch时间，单位是秒， 时间戳30秒后会过期 推荐使用time endponit 查询API 服务器的时间，如果你的服务器时间和API 服务器时间有偏差的话
sign:为签名字符串，签名规则参照请求说明（API概述验证部分）
其中timestamp示例:const timestamp = '' + Date.now() / 1000
其中sign 示例 : sign=CryptoJS.enc.Base64.Stringify(CryptoJS.HmacSHA256(timestamp +'GET'+ '/users/self/verify', secret))
method一律默认为'GET'。
requestPath 一律默认为'/users/self/verify'
如果登录失败会自动断开链接
连接限制
连接限制：1次/s
订阅限制：每小时240次
连接上ws后如果一直没有数据返回，30s 后自动断开链接， 建议用户进行以下操作:
1，每次接收到消息后，用户设置一个定时器 ，定时N秒。
2，如果定时器被触发（N 秒内没有收到新消息），发送字符串 'ping'。
3，期待一个文字字符串'pong'作为回应。如果在 N秒内未收到，请发出错误或重新连接。
出现网络问题会自动断开连接
校验和机制
此功能可以帮助用户校验深度数据的准确性
每次推送depth频道的深度数据都有时间戳，且有checksum 校验（即checksum值）。 用户订阅depth 频道首次会接收到Example Response深度，后续推送的都是增量数据。checksum值为：每次增量更新合并后此Example Response深度的前25档bids和asks组成的字符串的crc32值， 用户可以拿自己的checksum的值和订阅的checksum值进行比较，如果不匹配可以重新订阅。
深度合并规则说明： 首次发送Example Response深度数据，后续每次发送增量的数据，拿增量去遍历Example Response中的asks和bids的price ,如果发现有相同价格 则看数量，数量为0删除此深度，数量有变化则替换此数据； 无相同价格则按照顺序排序。
计算说明: checksum的值为有符号整型(32位)
checksum的字符串都是以冒号连接的ask和bid中的price和数量，例如：
例子1：bid和ask成对档的情况下，要校验的字符串为：bid:ask:bid:ask:...
"data": [{
"instrument_id": "BTC-USDT",
"asks": [["3366.8", "9", 10],[ "3368","8",3]],
"bids": [
["3366.1", "7", 0],[ "3366","6",3 ]
],
"timestamp": "2018-12-04T09:38:36.300Z",
"checksum": -1881014294
}]
该例子对应的checksum字符串为：3366.1:7:3366.8:9:3366:6:3368:8
例子2：bid和ask不成对档的情况 ，要校验的字符串为：bid:ask:ask:ask:...
"data": [{
"instrument_id": "BTC-USDT",
"asks": [["3366.8", "9", 10],[ "3368","8",3],[ "3372","8",3 ]],
"bids": [
["3366.1", "7", 0]
],
"timestamp": "2018-12-04T09:38:36.300Z",
"checksum": 831078360
}]
此例子对应的checksum String 将会是 3366.1:7:3366.8:9:3368:8:3372:8
depth 频道用户收到推送数据为：
首次Example Response
{
"table": "spot/depth",
"action": "partial",
"data": [{
"instrument_id": "ETH-USDT",
"asks": [
["8.8", "96.99999966", 1],
["9", "39", 3],
["9.5", "100", 1],
["12", "12", 1],
["95", "0.42973686", 3],
["11111", "1003.99999795", 1]
],
"bids": [
["5", "7", 4],
["3", "5", 3],
["2.5", "100", 2],
["1.5", "100", 1],
["1.1", "100", 1],
["1", "1004.9998", 1]
],
"timestamp": "2018-12-18T07:27:13.655Z",
"checksum": 468410539
}]
}
增量：
{
"table": "spot/depth",
"action": "update",
"data": [{
"instrument_id": "BTC-USDT",
"asks": [],
"bids": [
["3983", "789", 0]
],
"timestamp": "2018-12-04T09:38:36.300Z",
"checksum": -1200119424
}]
}
频道说明
无需登录的频道包括：行情频道，K线频道，交易数据频道，资金费率频道，限价范围频道，深度数据频道，标记价格频道
需登录的频道包括：用户账户频道，用户交易频道，用户持仓频道
无需登录的频道名称如下：
spot/ticker // 行情数据频道
spot/candle60s // 1分钟K线数据频道
spot/candle180s // 3分钟K线数据频道
spot/candle300s // 5分钟K线数据频道
spot/candle900s // 15分钟K线数据频道
spot/candle1800s // 30分钟K线数据频道
spot/candle3600s // 1小时K线数据频道
spot/candle7200s // 2小时K线数据频道
spot/candle14400s // 4小时K线数据频道
spot/candle21600 // 6小时K线数据频道
spot/candle43200s // 12小时K线数据频道
spot/candle86400s // 1day K线数据频道
spot/candle604800s // 1week K线数据频道
spot/trade // 交易信息频道
spot/depth //深度数据频道，首次200档，后续增量
spot/depth5 //深度数据频道，每次返回前5档
需登录的频道如下
spot/account //用户币币账户信息频道
spot/order //用户交易数据频道
用户币币账户频道
获取币币账户信息，需用用户登录
send示例
{"op": "subscribe", "args": ["spot/account:BTC"]}
其中spot/account为频道名，BTC为currency
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| currency | String | 币种 |
| balance | String | 余额 |
| hold | String | 冻结（不可用） |
| available | String | 可用于交易或资金划转的数量 |
| timestamp | String | 账户数据更新时间 |
返回示例
{
"table":"spot/account",
"data":[
{
"balance":"2.215374581132125",
"available":"1.632774581132125",
"currency":"USDT",
"id":"",
"hold":"0.5826"
}
]
}
用户杠杆账户频道
获取用户杠杆账户信息：
send示例
{"op": "subscribe", "args": ["spot/margin_account:ETH-USDT"]}
其中spot/margin_account为频道名，ETH-USDT为instrument_id
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| instrument_id | String | 杠杆币对名称 |
| balance | String | 余额 |
| hold | String | 冻结（不可用） |
| available | String | 可用于交易或资金划转的数量 |
| borrowed | String | 已借币（已借未还的部分） |
| lending_fee | String | 利息（未还的利息） |
| maint_margin_ratio | String | 维持保证金率 |
| tiers | String | 当前借币数量档位 |
| liquidation_price | String | 强平价 |
| timestamp | String | 账户数据更新时间 |
返回示例
{
'table': 'spot/margin_account',
'data': [{
'currency:USDT': {
'available': '0.00000000930213',
'balance': '0.00000000930213',
'borrowed': '0',
'hold': '0',
'lending_fee': '0'
},
"liquidation_price":"4.6499",
'tiers': '1',
'maint_margin_ratio': '0.08',
'instrument_id': 'ETH-USDT',
'currency:ETH': {
'available': '0.0202516022462802',
'balance': '0.0202516022462802',
'borrowed': '0.01',
'hold': '0',
'lending_fee': '0.0000001666'
}
}]
}
用户交易频道
获取用户交易数据，需用用户登录
send示例
{"op": "subscribe", "args": ["spot/order:LTC-USDT"]}
其中spot/order为频道名，LTC-USDT为instrument_id
返回参数
| 参数名 | 类型 | 描述 |
|---|---|---|
| order_id | String | 订单ID |
| client_oid | String | 由用户设置的订单ID |
| price | String | 委托价格 |
| size | String | 委托数量（交易货币数量） |
| notional | String | 买入金额，市价买入时返回 |
| instrument_id | String | 币对名称 |
| side | String | buy 或 sell |
| type | String | limit或market（默认是limit） |
| timestamp | String | 订单创建时间 |
| filled_size | String | 已成交数量 |
| filled_notional | String | 已成交金额 |
| margin_trading | String | 1 币币交易订单. |
| order_type | String | 0：普通委托 1：只做Maker（Post only） 2：全部成交或立即取消（FOK） 3：立即成交并取消剩余（IOC） |
| last_fill_px | String | 最新成交价格（如果没有，推0） |
| last_fill_qty | String | 最新成交数量（如果没有，推0） |
| last_fill_time | String | 最新成交时间（如果没有，推1970-01-01T00:00:00.000Z） |
| state | String | -2:失败-1:撤单成功0:等待成交1:部分成交2:完全成交3:下单中4:撤单中 |
解释说明
status为state旧版参数，会短期兼容，建议尽早切换state。
返回示例
{
"table":"spot/order",
"data":[
{
"client_oid":"oktspot5",
"filled_notional":"0",
"filled_size":"0",
"instrument_id":"BTC-USDT",
"last_fill_px":"0",
"last_fill_qty":"0",
"last_fill_time":"1970-01-01T00:00:00.000Z",
"margin_trading":"2",
"notional":"",
"order_id":"2666285202473984",
"order_type":"3",
"price":"4535.8",
"side":"buy",
"size":"0.001",
"status":"cancelled",
"timestamp":"2019-04-16T13:11:23.000Z",
"type":"limit"
}
]
}
公共-Ticker频道
获取现货最新成交价、买一价、卖一价和24交易量，每100ms推送一次数据。
send示例
{"op": "subscribe", "args": ["spot/ticker:ETH-USDT"]}
其中spot/ticker为频道名，ETH-USDT为instrument_id
返回参数
| 参数名 | 参数类型 | 描述 |
| instrument_id | String | 币对名称 |
| last | String | 最新成交价 |
| last_qty | String | 最新成交的数量 |
| best_ask | String | 卖一价 |
| best_ask_size | String | 卖一价对应的量 |
| best_bid | String | 买一价 |
| best_bid_size | String | 买一价对应的数量 |
| open_24h | String | 24小时开盘价 |
| high_24h | String | 24小时最高价 |
| low_24h | String | 24小时最低价 |
| base_volume_24h | String | 24小时成交量，按交易货币统计 |
| quote_volume_24h | String | 24小时成交量，按计价货币统计 |
| timestamp | String | 系统时间戳 |
返回示例
{
"table":"spot/ticker",
"data":[
{
"instrument_id":"ETH-USDT",
"last":"146.24",
"last_qty":"0.082483",
"best_bid":"146.24",
"best_bid_size":"0.006822",
"best_ask":"146.25",
"best_ask_size":"80.541709",
"open_24h":"147.17",
"high_24h":"147.48",
"low_24h":"143.88",
"base_volume_24h":"117387.58",
"quote_volume_24h":"17159427.21",
"timestamp":"2019-12-11T02:31:40.436Z"
}
]
}
公共-K线频道
获取现货的K线数据，每500ms推送一次数据。
频道列表：
spot/candle60s // 1分钟K线数据频道
spot/candle60s // 1分钟K线数据频道
spot/candle180s // 3分钟K线数据频道
spot/candle300s // 5分钟K线数据频道
spot/candle900s // 15分钟K线数据频道
spot/candle1800s // 30分钟K线数据频道
spot/candle3600s // 1小时K线数据频道
spot/candle7200s // 2小时K线数据频道
spot/candle14400s // 4小时K线数据频道
spot/candle21600s // 6小时K线数据频道
spot/candle43200s // 12小时K线数据频道
spot/candle86400s // 1day K线数据频道
spot/candle604800s // 1week K线数据频道
send示例
{"op": "subscribe", "args": ["spot/candle60s:ETH-USDT"]}
其中spot/candle60s为频道名，ETH-USDT为instrument_id
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| timestamp | String | 开始时间 |
| open | String | 开盘价格 |
| high | String | 最高价格 |
| low | String | 最低价格 |
| close | String | 收盘价格 |
| volume | String | 交易量 |
| instrument_id | String | 币对 |
返回示例
{
"table":"spot/candle60s",
"data":[
{
"candle":[
"2019-04-16T10:49:00.000Z",
"162.03",
"162.04",
"161.96",
"161.98",
"336.452694"
],
"instrument_id":"ETH-USDT"
}
]
}
公共-交易频道
获取最近的成交数据，无需用户登录，有成交数据就推送。
send示例
{"op": "subscribe", "args": ["spot/trade:ETH-USDT"]}
其中spot/trade为频道名，ETH-USDT为instrument_id
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| trade_id | String | 成交id |
| price | String | 成交价格 |
| size | String | 成交数量 |
| side | String | 成交方向（buy 或 sell） |
| timestamp | String | 成交时间 |
| instrument_id | String | 币对 |
返回示例
{
"table": "spot/trade",
"data": [{
"instrument_id": "ETH-USDT",
"price": "162.12",
"side": "buy",
"size": "11.085",
"timestamp": "2019-05-06T06:51:24.389Z",
"trade_id": "1210447366"
}]
}
公共-5档深度频道
每次返回前五档的深度数据，此数据为每100毫秒的快照数据，即每隔100毫秒，快照当前时刻市场订单簿的5档深度数据并推送。
send示例
{"op": "subscribe", "args": ["spot/depth5:ETH-USDT"]}
其中spot/depth5为频道名，ETH-USDT为instrument_id
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| asks | List<String> | 卖方深度 |
| bids | List<String> | 买方深度 |
| timestamp | String | 时间戳 |
| instrument_id | String | 币对 |
asks和bids值数组举例说明： ["411.8","10","8"] 411.8为深度价格，10为此价格数量，8为此深度由几笔订单组成。
返回示例
{
"table":"spot/depth5",
"data":[
{
"asks":[
[
"161.96",
"7.37567",
3
],
[
"161.97",
"1.308",
1
],
[
"161.98",
"2.463509",
1
],
[
"161.99",
"5.185",
2
],
[
"162",
"29.184592",
5
]
],
"bids":[
[
"161.94",
"4.552355",
1
],
[
"161.91",
"7.949",
3
],
[
"161.9",
"2.213",
1
],
[
"161.89",
"11.999998",
1
],
[
"161.88",
"6.585142",
3
]
],
"instrument_id":"ETH-USDT",
"timestamp":"2019-04-16T11:03:03.712Z"
}
]
}
公共-深度频道
订阅后首次返回市场订单簿的400档深度数据并推送；然后每隔100毫秒，快照这个时间段内有更改的订单簿数据，并推送。
send示例
{"op": "subscribe", "args": ["spot/depth:ETH-USDT"]}
其中spot/depth为频道名，ETH-USDT为instrument_id
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| asks | List<String> | 卖方深度 |
| bids | List<String> | 买方深度 |
| timestamp | String | 时间戳 |
| instrument_id | String | 币对 |
| checksum | String | 检验和 |
asks和bids值数组举例说明： ["411.8","10",8"] 411.8为深度价格，10为此价格数量，8为此深度由几笔订单组成。
返回示例
首次Example Response
{
"table":"spot/depth",
"action":"partial",
"data":[
{
"instrument_id":"ETH-USDT",
"asks":[
[
"162.5",
"14.29884",
2
],
[
"162.51",
"2.084362",
1
],
...
[
"168.51",
"7.760755",
2
],
[
"168.57",
"0.02",
1
]
],
"bids":[
[
"162.49",
"1.556106",
3
],
[
"162.47",
"0.00913",
1
],
...
[
"155.15",
"70",
1
],
[
"155.13",
"3",
1
]
],
"timestamp":"2019-04-16T10:17:28.507Z",
"checksum":1141851215
}
]
}
增量：
{
"table":"spot/depth",
"action":"update",
"data":[
{
"instrument_id":"ETH-USDT",
"asks":[
[
"162.5",
"0",
0
],
[
"162.61",
"1.209",
2
],
[
"168.69",
"0.006",
1
],
[
"168.73",
"0.002082",
1
]
],
"bids":[
[
"162.49",
"1.512544",
2
],
[
"162.47",
"0.05333",
2
],
[
"162.46",
"14.608508",
3
],
[
"162.43",
"10.61874",
3
],
[
"162.41",
"27.303906",
2
],
[
"162.4",
"14.762929",
6
],
[
"162.39",
"11.045909",
1
],
[
"162.36",
"19.230907",
8
],
[
"162.31",
"3.927598",
4
],
[
"162.3",
"5.353085",
5
],
[
"162.29",
"6.569261",
12
],
[
"162.25",
"8.308575",
3
]
],
"timestamp":"2019-04-16T10:17:29.045Z",
"checksum":227291232
}
]
}
WS公共指数频道
WebSocket API 公共指数频道
指数行情
公共指数频道无需登录，现货可参考此频道 目前所提供的指数都是以USD计价的指数，币种列表为：BTC LTC ETH ETC XRP EOS BTG
获取公共指数行情
send示例
{"op": "subscribe", "args": ["index/ticker:BTC-USD"]}
其中index/ticker为频道名，BTC-USD为币种指数
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| instrument_id | String | BTC-USD |
| last | String | 最新成交价 |
| high_24h | String | 24小时最高价 |
| low_24h | String | 24小时最低价 |
| timestamp | String | 系统时间戳 |
| open_24h | String | 24h开盘价 |
返回示例
{"table":"index/ticker","data":[{"last":"3649.76","high_24h":"3955.4","low_24h":"10","instrument_id":"BTC-USD","open_24h":"3888.68","timestamp":"2018-11-27T10:01:23.341Z"}]}
指数K线
获取指数的K线数据
频道列表：
index/candle60s //1分钟K线数据频道
index/candle180s //3分钟K线数据频道
index/candle300s //5分钟K线数据频道
index/candle900s //15分钟K线数据频道
index/candle1800s //30分钟K线数据频道
index/candle3600s //1小时K线数据频道
index/candle7200s //2小时K线数据频道
index/candle14400s //4小时K线数据频道
index/candle21600s //6小时K线数据频道
index/candle43200s //12小时K线数据频道
index/candle86400s //1day小时K线数据频道
index/candle604800s //1 week K线数据频道
send示例
{"op": "subscribe", "args": ["index/candle60s:BTC-USD"]}
{"op": "subscribe", "args": ["index/candle60s:BTC-USDT"]}
其中index/candle60s为频道名，BTC-USD为币种指数
返回参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| timestamp | String | 开始时间 |
| open | String | 开盘价格 |
| high | String | 最高价格 |
| low | String | 最低价格 |
| close | String | 收盘价格 |
| volume | String | 交易量（张） |
| instrument_id | String | BTC-USD ,BTC-USDT |
返回示例
{"table":"index/candle60s","data":[{"instrument_id":"BTC-USD","candle":["2018-11-27T10:01:23.341Z","3811.31","3811.31","3811.31","3811.31","0"]}]}
这里是Websocket错误码
error message 格式：
{"event":"error","message":"
错误码示例
| 错误描述 | Code | |
|---|---|---|
| 长时间没有接收到数据 | no data received in 30s | 4001 |
| 缓冲区无法写入数据关闭 | Buffer full. cannot write data | 4002 |
| Url pass 无效 | Url path error | 30000 |
| "OK_ACCESS_KEY"不能为空 | OK_ACCESS_KEY cannot be blank | 30001 |
| "OK_ACCESS_SIGN"不能为空 | OK_ACCESS_SIGN cannot be blank | 30002 |
| "OK_ACCESS_PASSPHRASE"不能为空 | OK_ACCESS_PASSPHRASE cannot be blank | 30004 |
| 无效的OK_ACCESS_TIMESTAMP | Invalid OK_ACCESS_TIMESTAMP | 30005 |
| 无效的OK_ACCESS_KEY | Invalid OK_ACCESS_KEY | 30006 |
| 请求时间戳过期 | Timestamp request expired | 30008 |
| 无效的sign | Invalid sign | 30013 |
| 用户请求频率过快，超过该接口允许的限额 | Requested too frequent; endpoint limit exceeded | 30026 |
| 不合法的请求 | Login failure | 30027 |
| 不合法的请求 | Unrecognized request | 30039 |
| 频道不存在 | {0} Channel : {1} doesn't exist | 30040 |
| 用户需要登录 | User not logged in / User must be logged in | 30041 |
| 重复登录 | Already logged in | 30042 |
| 内部系统错误 | Internal system error | 30043 |
问题反馈
如果您有任何api相关问题，意见或者建议，请点此链接反馈：(请标明是API v3 ), 我们会及时处理您的问题。