入门指引


欢迎使用开发者文档。此文档目前为V3版,会继续更新,请大家及时关注。

此文档为用户提供了一整套简单而又强大的开发工具,旨在帮助用户快速、高效地将交易功能整合到自己的应用当中。
接口是提供服务的基础,API分为账户、交易和行情三类。开发者在网站创建账号后,可以根据自身需求建立不同权限的API,并利用API进行自动交易或者提现。
账户和交易API需要身份验证,提供下单、撤单,查询订单和帐户信息等功能。行情API提供市场的行情数据,所有行情接口都是公开的。 如果api返回值里出现文档上没有的字段,则意味着这些字段即将被弃用,请使用文档上的字段。

使用流程

步骤:开发者如需使用API ,请先申请v3API key等信息 点击申请API key,然后根据此文档详情进行开发交易,使用过程中如有问题或者建议请及时反馈。

接口调用方式说明

为用户提供两种调用接口的方式,开发者可根据自己的使用场景和偏好选择适合自己的方式来查询行情、进行交易或提现。 可参考SDK(点击跳转SDK详情页面)

REST API

REST,即Representational State Transfer的缩写,是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,正得到越来越多网站的采用。其优点如下:

  • 在RESTful架构中,每一个URL代表一种资源;
  • 客户端和服务器之间,传递这种资源的某种表现层;
  • 客户端通过四个HTTP指令,对服务器端资源进行操作,实现“表现层状态转化”。 建议开发者使用REST API进行币币交易或者资产提现等操作。
WebSocket API

WebSocket是HTML5一种新的协议(Protocol)。它实现了客户端与服务器全双工通信,使得数据可以快速地双向传播。通过一次简单的握手就可以建立客户端和服务器连接,服务器根据业务规则可以主动推送信息给客户端。其优点如下:

  • 客户端和服务器进行数据传输时,请求头信息比较小,大概2个字节;
  • 客户端和服务器皆可以主动地发送数据给对方;
  • 不需要多次创建TCP请求和销毁,节约宽带和服务器的资源。 强烈建议开发者使用WebSocket API获取市场行情和买卖深度等信息。

联系我们

如需帮助请添加微信号:ApiSupport 备注:API+姓名+ok账号,拉你进API问题交流群

API概述

市场概况和基础信息

撮合引擎

本章节主要为撮合引擎的细节分以下四个方面:

  • 成交价
  • 订单生命周期
  • 币币交易限价规则
  • 合约交易限价规则

    成交价

OKEx撮合系统撮合订单的优先级按照价格优于时间的优先级来撮合,优先撮合价格更有优势的订单。当价格一致时按照下单时间顺序撮合,先下单的先撮合。

比如深度列表中目前有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成交。

订单生命周期

订单进入撮合引擎后是"等待成交"状态;

如果一个订单被撮合而全部成交,那么它会变成"完全成交"状态;

一个订单被撮合可能出现部分成交,那么它的状态会变成"部分成交"状态,并且继续留在撮合队列中进行撮合;

一个未成交订单撤单成功,,那么它的状态会变成"已撤销"状态;

发起撤销到完成撤销的过程中有一个过程状态"撤单中";

被撤销或者全部成交的订单将被从撮合队列中剔除。

币币交易限价规则

为了防止用户下错大单造成市场异常波动和个人资金损失,OKEx币币交易设置了FOK限价规则:如果用户在币币交易所下的市价单/限价单可以与当前买卖盘内订单直接成交,那么系统会判断成交深度对应的价格与同方向盘口价的偏差是否超出5%。如果超过,则此订单将被系统立即全数撤销,否则此订单正常进行撮合。

例如:某用户在XRP/BTC交易区下了100BTC的市价买单(此时卖一价为0.00012),系统判断订单完成成交后最新成交价为0.0002。此时,(0.0002-0.00012)/0.00012=66.7%>5%,用户的这笔市价买单将被立即撤销,不会和买卖盘内订单进行撮合。

合约交易限价规则

限价是保护投资者,防止市场被操控的重要风控手段之一。如果没有限价规则,少数交易者可以使用少量资金和高杠杆倍数,使合约价格大幅波动,人为制造大额分摊。另一方面,如果限价规则过于简单,会导致市场缺乏活力,与币币没有溢价,失去了合约交易本身的意义。为了更好地起到风控效果,限价的具体规则是不完全公开的,OKEx会综合市场的交易量、成交量、持仓量、偏离指数的百分比等十几个参数,动态地计算风控规则。同时为了方便用户更好地了解限价和交易便利。

限价规则:该限价规则适合所有币种的合约。

新合约生成10分钟内:最高价=现货指数(1+5%),最低价=现货指数(1-5%)。

合约生成了10分钟后:最高价=近10分钟溢价平均值+现货指数(1+3%),最低价=近10分钟溢价均值+现货指数(1-3%),溢价=合约价格-现货价格。

若计算后的价格超过最高偏离度的现货指数25%或价格小于0,则最高价=现货指数(1+25%),最低价=现货指数(1-25%)。

以上规则,开平仓都受限制,若开多或平空,当委托价高于最高价,则将触发限价;若开空或平多,当委托价低于最新价,则将触发限价。

费用

本章节主要为费用的细节分以下两个方面:

  • 交易费用
  • 充/提币费用

交易费用

OKEx采用maker-taker收费规则,为鼓励挂单,maker挂单成交的手续费会比taker吃单成交的手续费低。

同时,为了鼓励成交,OKEx推出阶梯手续费政策,根据你前30天的累计交易量划分不同的手续费等级,成交量越高,手续费等级越高,手续费越低。
除了手续费优惠,OKEx还为提供流动性的专业用户提供了市商计划。参与市商计划后,只要您能够提供稳定的深度以及盘口点差,即可获得Maker手续费返还。
详情请查看(点击跳转至费率详情页面)

充/提币费用

OKEx不收取任何充币/提币费用,在OKCoin币行、OKCoin国际站和OKEx这3个站账户之间进行资金划转不需要支付矿工手续费,并且实时到账。但是提币到这3个站账户之外的数字货币地址的过程中产生的矿工手续费需要用户自己承担。

服务器

OKEx的数据库和服务器运行在香港。为了最大限度地减少API访问延迟,建议您使用与香港通讯通畅的服务器。

请求

本章节主要为请求的细节分以下三个方面:

  • 介绍
  • 错误
  • 成功

介绍

REST API提供账户管理、行情查询和交易功能。

REST API终端URL https://www.okex.com/

同时OKEx还提供了WebSocket流,订阅WebSocket可以获取行情数据的推送。

ws 地址:wss://real.okex.com:8443/ws/v3

所有请求基于Https协议,请求头信息中contentType需要统一设置为:’application/json’

请使用大陆以外的ip地址访问okex的API,强烈建议使用香港阿里云服务器。

不建议用户通过网络代理的方式请求okex的api。会造成较高延迟和网络稳定差。

错误

除非特殊说明,错误请求都通过HTTP 4xx或者状态码进行返回,返回内容还将包含错误原因、参数信息。您的HTTP库应配置为非2xx请求提供消息主体,以便您可以从主体读取消息字段。

常见错误码
400 Bad Request — Invalid request fotmat
401 Unauthorized — Invalid API Key
403 Forbidden — You do not have access to the requested resource
404 Not Found
500 Intermal Server Error — We had a problem with our server

成功

HTTP状态码200表示成功响应,并可能包含内容。如果响应含有内容,则将显示在相应的返回内容里面。

分页

OKEx对返回数组的有些REST请求使用游标分页。游标分页允许在当前结果页面之前和之后获取结果,并且非常适合实时数据。端点如/ trades,/ fills,/ orders,默认返回最新100项。要检索更多结果,后续请求应根据先前返回的数据指定要分页的方向。

beforeafter游标可以通过响应头OK-BEFOREOK-AFTER。在初始请求之后发出页面请求时,您的请求应使用这些游标值。

GET /api/spot/v3/orders?before=2&limit=30

参数名 参数类型 描述
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的order_idledger_idtrade_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的order_idledger_idtrade_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条

游标之前和之后 将before光标引用在结果页中的第一项和after光标引用了一组结果的最后一个数据。

headers将包含一个OK-BEFORE标头,该标头将返回光标id,以便在当前页面的下一个页面请求中使用。之前的页面是一个较新的页面,而不是在按时间顺序排列之前发生的页面。 响应还将包含一个OK-AFTER标头,该标头将返回光标id,以便在此页面之后的页面的下一个请求中使用。之后的页面是较旧的页面,而不是按时间顺序排在此页面之后的页面。

举例

1、GET /api/futures/v3/orders/BTC-USD-190628?state=2(返回合约BTC-USD-190628的最近100条全部成交订单)

2、GET /api/futures/v3/orders/BTC-USD-190628?state=2&limit=20(返回合约BTC-USD-190628的最近20条全部成交订单)

3、GET /api/futures/v3/orders/BTC-USD-190628?state=2&after=2512669605501952&limit=20(返回合约order_id=2512669605501952更旧的20条全部成交订单,不包括2512669605501952

4、GET /api/futures/v3/orders/BTC-USD-190628?state=2&=before2512669605501952&limit=20(返回合约order_id=2512669605501952更新的20条全部成交订单,不包括2512669605501952

标准规范

本章节主要为标准规范的细节分以下三个方面:

  • 时间戳
  • 数字
  • ID

时间戳

除非另外指定,API中的所有时间戳均以毫秒为单位返回,符合ISO 8601标准。请确保您可以解析ISO 8601格式。

例子

2014-11-06T10:34:47.123Z

数字

为了保持跨平台时精度的完整性,十进制数字作为字符串返回。建议您在发起请求时也将数字转换为字符串以避免截断和精度错误。

整数(如交易编号和顺序)不加引号。

ID

除非另有说明,大多数标识符是UUID。当提出一个需要UUID的请求时,以下两个形式(有和没有破折号)都被接受。

132fb6ae-456b-4654-b4e0-d681ac05cea1或者132fb6ae456b4654b4e0d681ac05cea1

接口类型

本章节主要为接口类型的细节分以下两个方面:

  • 公共接口
  • 私有接口

公共接口

公共接口可用于获取配置信息和行情数据。公共请求无需认证即可调用。

私有接口

私有接口可用于订单管理和账户管理。每个私有请求必须使用规范的验证形式进行签名。

私有接口需要使用您的API key进行验证。您可以在这里生成API key。

访问限制

本章节主要为访问限制的细节分以下两个方面:

  • REST API
  • WebSocket

当访问超过频率限制时,将返回429状态:请求太频繁。

REST API

如果传入有效的API key 用user id限速;如果没有则拿公网IP限速。

限速规则:各个接口上有单独的说明,如果没有一般接口限速为 6次/秒。

特殊说明:批量下单时,若下4个币对,每个币对10个订单时,计为一次请求。

WebSocket

WebSocket将每个命令类型限制为每秒50条命令。

验证

本章节主要为验证的细节分以下五个方面:

  • 生成API Key
  • 发起请求
  • 签名
  • 时间戳
  • 获取服务器时间

生成API Key

在对任何请求进行签名之前,您必须通过OKEx网站创建一个API Key。创建API Key后,您将获得3个必须记住的信息:

  • API Key
  • Secret
  • Passphrase

API Key和SecretKey将由OKEx随机生成和提供,Passphrase将由您提供以确保API访问的安全性。OKEx将存储Passphrase加密后的哈希值进行验证,但如果您忘记Passphrase,则无法恢复,请您通过OKEx网站重新生成新的API Key。

发起请求

所有REST请求头都必须包含以下内容:

OK-ACCESS-KEY字符串类型的API Key。

OK-ACCESS-SIGN使用base64编码签名(请参阅签名)。

OK-ACCESS-TIMESTAMP发起请求的时间戳。

OK-ACCESS-PASSPHRASE您在创建API密钥时指定的Passphrase。

所有请求都应该含有application/json类型内容,并且是有效的JSON。

签名

OK-ACCESS-SIGN的请求头是对timestamp + method + requestPath + body字符串(+表示字符串连接),以及secretKey,使用HMAC SHA256方法加密,通过BASE64编码输出而得到的。

例如:sign=CryptoJS.enc.Base64.Stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/users/self/verify', secretKey))

其中,timestamp的值与OK-ACCESS-TIMESTAMP请求头相同,必须是UTC时区Unix时间戳的十进制秒数格式或ISO8601标准的时间格式,精确到毫秒。。

method是请求方法,字母全部大写:GET/POST

requestPath是请求接口路径。例如:/orders?before=2&limit=30

body是指请求主体的字符串,如果请求没有主体(通常为GET请求)则body可省略。例如:{"product_id":"BTC-USD-0309","order_id":"377454671037440"}

secretKey为用户申请API Key时所生成。例如:22582BD0CFF14C41EDBF1AB98506286D’

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.okex.open.api.config.APIConfiguration;
import com.okcoin.commons.okex.open.api.constant.APIConstants;
import com.okcoin.commons.okex.open.api.enums.ContentTypeEnum;
import com.okcoin.commons.okex.open.api.enums.HttpHeadersEnum;
import com.okcoin.commons.okex.open.api.exception.APIException;
import com.okcoin.commons.okex.open.api.utils.DateUtils;
import com.okcoin.commons.okex.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/{instrument_id}/candles")
    Call<JSONArray> getProductCandles(@Path("instrument_id") String productId, @Query("start") String start, @Query("end") String end, @Query("granularity") String granularity);

}

import com.alibaba.fastjson.JSONArray;
import com.okcoin.commons.okex.open.api.bean.futures.result.*;
import com.okcoin.commons.okex.open.api.client.APIClient;
import com.okcoin.commons.okex.open.api.config.APIConfiguration;
import com.okcoin.commons.okex.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.okex.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.okex.open.api.bean.futures.result.*;
import com.okcoin.commons.okex.open.api.service.futures.FuturesMarketAPIService;
import com.okcoin.commons.okex.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 okex

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.okex.com/
    Endpoint String
    // The user's api key provided by OKEx.
    ApiKey String
    // The user's secret key provided by OKEx. 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 OKEX API's config
    var config Config
    config.Endpoint = "https://www.okex.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 OKEXAPI::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 OKEXAPI::Request(const String &method, const String &requestPath, const String &params) {
    /************************** 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() {
    OKEXAPI okexapi;
    /************************** set config **********************/
    struct Config config;
    config.Endpoint = "https://www.okex.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 okexapi.Request(method, request_path);
}

String AddSpotOrderExample() {
    OKEXAPI okexapi;
    /************************** set config **********************/
    struct Config config;
    config.Endpoint = "https://www.okex.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["instrument_id"] = value::String("BTC-USD");

    /************************** request and response **********************/
    String params = obj.serialize();
    return okexapi.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]


# request example
# set the request url
base_url = 'https://www.okex.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.okex.com'
request_path = '/api/spot/v3/orders'

# request params
params = {'type': 'market', 'side': 'buy', 'instrument_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.okex.com'
request_path = '/api/spot/v3/orders'

params = {'status':'all', 'instrument_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

限速规则:20次/2s
返回参数
参数名 描述
iso ISO8601标准的时间格式
epoch UTC时区Unix时间戳的十进制秒数格式
返回示例
{

"iso": "2015-01-07T23:47:25.201Z",

"epoch": 1420674445.201

}

资金账户API

资金账户主账户与交易账户/子账户之间的资金划转,获取充值地址,提现等功能。

资金账户信息

获取资金账户所有资产列表,查询各币种的余额、冻结和可用等信息。

限速规则:20次/2s
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":"EOS",
        "hold":"0"
    },
    {
        "available":"0",
        "balance":"0",
        "currency":"XMR",
        "hold":"0"
    }
]

单一币种账户信息

获取资金账户单个币种的余额、冻结和可用等信息。

限速规则:20次/2s
HTTP请求

GET /api/account/v3/wallet/<currency>

请求示例

GET /api/account/v3/wallet/XMR

请求参数
参数名 参数类型 是否必须 描述
currency String 币种
返回参数
参数名 参数类型 描述
balance String 余额
hold String 冻结(不可用)
available String 可用余额
currency String 币种,如BTC
返回示例
{
    "currency":"XMR",
    "available":"0.00049136",
    "balance":"0.00049136",
    "hold":"0"
}

资金划转

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:币币
3:合约
4:C2C
5:币币杠杆
6:资金账户
8:余币宝
9:永续合约
to String 转入账户
0:子账户
1:币币
3:合约
4:C2C
5:币币杠杆
6:资金账户
8:余币宝
9:永续合约
sub_account String 子账号登录名,fromto指定为0时,sub_account为必填项,
instrument_id String 杠杆转出币对,如:eos-usdt,仅限已开通杠杆的币对
to_instrument_id String 杠杆转入币对,如:eos-btc,仅限已开通杠杆的币对,仅币币杠杆内转账时用到此参数
返回参数
参数名 参数类型 描述
transfer_id String 划转ID
currency String 划转币种
from String 转出账户
amount String 划转量
to String 转入账户
result Boolean 划转结果。若是划转失败,将给出错误码提示
解释说明

fromto指定为0时,sub_account为必填项。

from0时,to只能填6,即子账户的资金账户只能转到母账户的资金账户。

from指定为6to指定为1-9,且sub_account填写子账户名时,可从母账户直接划转至子账户对应的币币、合约等账户。

fromto指定为5时,instrument_id为必填项。

返回示例
{
    "transfer_id": "754147",
    "currency”:"ETC”
    "from": "6",
    "amount": "0.1",
    "to”: "1",
    "result": true
}

提币

限速规则:20次/2s
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 提币到
2:OKCoin国际; 3:OKEx; 4:数字货币地址; 68:币全CoinAll; 69:OKGAEX;
70:2100BIT; 71:OCNex; 72:咖啡交易所; 73:OKTop; 75:BBang;
76:TokenClub; 79:VREX; 80:币窗; 81:PAICLUB; 82:淘币网;
83: GoTop; 84:ABull; 85:LETDAX; 86:爵爷; 87:币牛牛交易所;
88:YAOEOS; 89:TOKR; 90:4A交易平台; 91:币六六; 92:Vipexc;
93:imex; 95:DEX.HK; 96:BigEx; 97:StarEX; 98:比特上海;
99:LBL.market; 100:CoinGod; 101:WOOT; 102:币小龙Coinxiaolong; 103:VBEX;
104:MY1EX; 105:Bitfinance; 106:DBEX 迪交所; 107:LOVEUEX; 108:99EX-久币网;
109:Futures Crypto; 110:Exx BK; 111:MyCoin; 112:ROCKEX; 113:以太坊交易所;
114:COINZOZ; 115:ECGEX; 116:雷爵爾交易所; 117:EXVALUE; 118:TradeDee;
119:HHEX; 120:ERCSTO; 121:Tenspace; 122:APNEX; 123:HelloExc;
124:A9CPS; 125:PICKCOIN; 126:WeBit; 127:abv138; 128:币商所;
129:66交易所; 130:CBK; 131:Coinpop99; 132:Chain Bay; 133:Longwinex 长胜网;
134:BE.TOP; 135:CRYPTEX GLOBAL; 136:FT交易所; 137:牛币网; 138:ybitex;
139:大圣交易所; 140:EXFINEX; 141:aiEx; 142:EXIPFS; 143:盘行;
144:PeBank; 145:YES交易所; 146:币栈; 147:VitBlock; 148:CPC;
149:KGcoin; 150:京东交易所; 151:Korbot Exchange; 152:xFutures; 153:Float SV;
154:Y83; 155:雾交所; 156:KoKoEx; 157:MerXader; 158:理想国;
159:TEX IO; 160:贝壳国际交易所; 161:币爱交易所; 162:COEX; 163:BOOMEX;
164:艾普; 165:币火严选; 166:Token Coin; 167:实通所; 168:诺贝尔;
169:Oakiss; 170:魅幻城; 171:ETBBpro; 172:币可富; 173:VVCOIN)
to_address String 认证过的数字货币地址、邮箱或手机号。某些数字货币地址格式为:地址+标签,例:ARDOR-7JF3-8F2E-QUWZ-CAN7F:123456
trade_pwd String 交易密码
fee String 网络手续费≥0。提币到OKCoin国际或OKEx免手续费,请设置为0。提币到数字货币地址所需网络手续费可通过提币手续费接口查询

关于标签:某些币种如xrp充币时同时需要一个充值地址和标签(又名tag/memo/payment/标签等),标签是一种保证您的充币地址唯一性的数字串,与充币地址成对出现并一一对应。请您务必遵守正确的充值步骤,在提币时输入完整信息,否则将面临丢失币的风险!

返回参数
参数名 参数类型 描述
currency String 提币币种
amount String 提币数量
withdraw_id String 提币申请ID
result Boolean 提币申请结果。若是提现申请失败,将给出错误码提示
返回示例
{
    "amount":"0.1",
    "withdrawal_id":"67485",
    "currency":"btc",
    "result":true
}

账单流水查询

查询资金账户账单流水,可查询最近一个月的数据。

限速规则:20次/2s
HTTP请求

GET /api/account/v3/ledger

请求示例

GET /api/account/v3/ledger?type=2&currency=btc&after=9260348&limit=10

请求参数
参数名 参数类型 是否必须 描述
currency String 币种,如BTC ,不填时返回所有的账单流水
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的ledger_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的ledger_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条
type String 1: 充值
2: 提现
13: 撤销提现
18: 转入交割合约账户
19: 交割合约账户转出
20: 转入子账户
21: 子账户转出
28: 领取
29: 转入指数交易区
30: 指数交易区转出
31: 转入法币账户
32: 法币账户转出
33: 转入币币杠杆账户
34: 币币杠杆账户转出
37: 转入币币账户
38: 币币账户转出
41: 点卡抵扣手续费
42: 购买点卡
43: 点卡转让
44: 撤销点卡转让
47: 系统冲正
48: 活动得到
49: 活动送出
50: 预约得到
51: 预约扣除
52: 发红包; 53: 抢红包
54: 红包退还
55: 转入永续合约账户
56: 永续合约账户转出
57: 转入余币宝
58: 余币宝转出
59: 套保账户转出;
60: 转入套保账户
61: 兑换
返回参数
参数名 参数类型 描述
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"
    }
]

获取充值地址

获取各个币种的充值地址,包括曾使用过的老地址。

限速规则:20次/2s
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 转入账户
0:子账户
1:币币
3:合约
4:C2C
5:币币杠杆
6:资金账户
8:余币宝
9:永续合约
解释说明

IOTA充值地址不能重复使用!在向IOTA地址发起充值后,再次充值到此相同地址将不会被确认到账。

某些币充值到账,需要同时填写OKEx返回的充值地址和一个tag/payment_id/memo。如果未遵守正确的充值步骤,币会丢失!

返回示例
[
    {
        "address": "okbtothemoon",
        "memo": "971668",
        "currency": "eos",
        "to": 6
    }
]

查询所有币种的提币记录

查询最近所有币种的提币记录,为最近100条记录。

限速规则:20次/2s
HTTP请求

GET /api/account/v3/withdrawal/history

请求示例

GET /api/account/v3/withdrawal/history

返回参数
参数名 参数类型 描述
currency String 币种
amount String 数量
timestamp String 提币申请时间
from String 提币地址(如果收币地址是OKEx平台地址,则此处将显示用户账户)
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显示的是用户OKEx账户,并不等于区块链上实际的发币地址,如果提币到OKEx则to也显示为OKEx账户,此时将不OKEx账户,此时将不返回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"
    }
]

查询单个币种提币记录

查询单个币种的提币记录。

限速规则:20次/2s
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 提币地址(如果收币地址是OKEx平台地址,则此处将显示用户账户)
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显示的是用户OKEx账户,并不等于区块链上实际的发币地址,如果提币到OKEx则to也显示为OKEx账户,此时将不OKEx账户,此时将不返回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/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:充值成功
返回示例
[
    {
        "amount":"0.01044408",
        "txid":"1915737_3_0_0_WALLET",
        "currency":"BTC",
        "from": "13801825426",
        "to":"",
        "timestamp":"2018-09-30T02:45:50.000Z",
        "status":"2"
    },
    {
        "amount":"491.6784211",
        "txid":"1744594_3_184_0_WALLET",
        "currency":"OKB",
        "from": "",
        "to":"",
        "timestamp":"2018-08-21T08:03:10.000Z",
        "status":"2"
    },
    {
        "amount":"223.18782496",
        "txid":"6d892c669225b1092c780bf0da0c6f912fc7dc8f6b8cc53b003288624c",
        "currency":"USDT",
        "from": "",
        "to":"39kK4XvgEuM7rX9frgyHoZkWqx4iKu1spD",
        "timestamp":"2018-08-17T09:18:40.000Z",
        "status":"2"
    }
]

获取单个币种充值记录

获取单个币种的充值记录,为最近一百条数据

限速规则:20次/2s
HTTP

GET /api/account/v3/deposit/history/<currency>

请求示例

GET /api/account/v3/deposit/history/btc

请求参数
参数名 参数类型 是否必须 描述
currency String 币种
返回参数
参数名 参数类型 描述
amount String 充值数量
from String 充值地址,只显示内部账户转账地址,不显示区块链充值地址
to String 此笔充值到账地址
txid String 区块转账哈希记录
timestamp String 充值到账时间
currency String 币种名称,如btc
status String 充值状态
0:等待确认
1:确认到账
2:充值成功
返回示例
[
    {
        "amount":"0.0835",
        "txid":"6d892c669225b1092c780bf0da0c6f912fc3e8f997dc8f6b8cc53b003288624c",
        "currency":"BTC",
        "from":"13800138000"
        "to":"39kK4XvgEuM7rX9frgyHoZkWqx4iKu1spD",
        "timestamp":"2018-06-09T07:57:09.000Z",
        "status":"2"
    },
    {
        "amount":"0.01",
        "txid":"590426_1_0_WALLET",
        "currency":"BTC",
        "from":""
        "to":"",
        "timestamp":"2018-05-30T01:33:40.000Z",
        "status":"2"
    }
]

获取币种列表

获取平台所有币种列表。并非所有币种都可被用于交易。在ISO 4217标准中未被定义的币种代码可能使用的是自定义代码。

限速规则:20次/2s
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":""
    }
]

提币手续费

查询提现到数字货币地址时,建议网络手续费信息。手续费越高,网络确认越快。

限速规则:20次/2s
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"
    }
]

币币API

币币交易的行情信息,账户信息,订单操作,订单查询,账单明细查询。

说明:因为要和老版本做兼融,实际有些接口返回参数会有多余,请以文档中返回参数说明为准。

例如币币账户信息接口返回frozenholdholds参数值相同,以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":"9150707",
    "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&after=2500723297813504

请求参数
参数名 参数类型 是否必须 描述
currency String 币种
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的ledger_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的ledger_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条
type String 1 .充值
2 .提现
7 .买入
8 .卖出
9 .新手任务
10 .邀请好友完成新手任务
11 .扣除任务奖励
12 .邀请分成
13 .撤销提现
14 .活动送出
15 .活动得到
18 .交割合约转入
19 .转出至交割合约
20 .转入子账户
21 .转出至子账户
22 .返手续费
23 .接收红包
24 .发送红包
25 .otc买入
26 .otc卖出
27 .扣除
28 .兑换
29 .转出至资金账户
30 .资金账户转入
31 .转出至法币
32 .法币转入
33 .转出至杠杆
34 .杠杆转入
35 .借币
36 .还币
37 .市商计划送出
38 .市商计划返还
41 .点卡抵扣币币手续费
42 .购买点卡
43 .点卡转让
44 .市商计划额外送出
45 .市商计划返还
46 .币币账户转入
47 .转出至币币账户
48 .转出至组合
49 .组合转入
50 .挖矿扣除
51 .挖矿所得
52 .收益倍增
53 .鼓励金分配
55 .余币宝转入
56 .转出至余币宝
57 .永续合约转入
58 .转出至永续合约
59 .还糖果
60 .点卡抵扣杠杆手续费
返回参数
参数名 类型 描述
ledger_id String 账单ID
balance String 余额
currency String 币种
amount String 变动数量
type String 流水来源
timestamp String 账单创建时间
details String 如果typetrade或者fee,则会有该details字段将包含orderinstrument信息
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"
        }
    }
]

下单

OKEx币币交易提供限价单和市价单两种下单模式(更多下单模式将会在后期支持)。只有当您的账户有足够的资金才能下单。

一旦下单,您的账户资金将在订单生命周期内被冻结。被冻结的资金以及数量取决于订单指定的类型和参数。

限速规则:100次/2s
HTTP请求

POST /api/spot/v3/orders

签名请求示例

2018-10-12T07:30:49.664ZPOST /api/spot/v3/orders{'type': 'limit', 'side': 'buy', 'instrument_id': 'BTC-USDT', 'size': 0.001, 'client_oid': 'oktspot79', 'price': '4638.51', 'funds': '', 'margin_trading': '1', 'order_type': '3'}

请求参数
参数名 类型 是否必填 描述
client_oid String 由您设置的订单ID来识别您的订单,类型为字母(大小写)+数字或者纯字母(大小写) ,1-32位字符
type String limitmarket(默认是limit)。当以market(市价)下单,order_type只能选择0(普通委托)
side String buysell
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 错误码,下单成功时为空,下单失败时会显示相应错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
解释说明

client_oid

client_oid的类型为字母+数字或者纯字母(大小写),1-32位字符 ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单和查询订单时只能撤销或者查询出最新的一条数据。

instrument_id

instrument_id必须是有效的币对。币对列表可通过/ instrument接口获取。

type

下单时,您可以指定订单类型。您指定的订单类型将决定是否需要其他订单参数以及撮合引擎如何执行您的订单。如果type没有指定,订单类型将默认为limit。限价单既是默认订单类型,也是基本订单类型。限价单需要指定pricesizesize是买入或卖出交易货币的数量,price表示每个交易货币相对计价货币的价格。限价单会按指定价格或更好的价格成交。根据市场条件,卖单可以按照指定价格或者更高价格来成交,买单可以按照指定价格或更低价格成交。如果限价单不能立即成交,那么限价单将进入深度列表,直到被另一个新订单成交或被用户撤单。 市价单不同于限价单,因为它们不提供价格控制。市价单提供了一种不必指定价格,而以固定数量的货币进行买入或者卖出的方式。市价单下单后会立即撮合,而不会被挂入深度列表。市价单总是吃单方taker并按taker收取手续费用。(注:如果你计划买入卖出的数量巨大时,将会对价格产生巨大影响,此时不推荐使用市价单)

price

price表示买入或卖出的价格。价格必须是价格步长quote_increment的倍数。价格步长quote_increment是价格的最小增量,可通过instrument接口获取。

size

size表示买入或卖出交易货币的数量。数量必须大于min_sizesize_increment是交易货币数量的最小增量。上述参数都可通过instrument接口获取。 举例:假设 okb/usdt 的min_size10size_increment0.0001。那么不能交易9.9个okb,但是可以交易10.0001个okb

notional

notional表示被用于市价买入的计价货币的数量,市价买入时必填。例如,在BTC-USDT交易时,市价单指定5000 USDT表示将花费5000 USDT购买BTC。

hold

对于限价买单,系统将冻结计价货币的数量 = 限定价格 x 买入数量。对于限价卖单,系统将冻结你想卖出的交易货币的数量。对于市价买单,funds数量的计价货币将被冻结。对于市价卖单,size数量的交易货币将被冻结。如果您取消部分成交或未成交的订单,剩余资金将被解除冻结。

订单生命周期

HTTP请求将在订单被拒绝(资金不足,参数无效等)或下单成功(由匹配引擎接受)时作出响应。一个200响应表示该订单被接收并且进入撮合。进入撮合的订单可以部分或全部立即成交(取决于价格和市场条件)。部分成交的时候将把订单的剩余数量继续进行撮合。完全成交的订单将进入已成交状态。 监听行情数据的用户建议使用client_oid字段以便在接受到的信息中标识对应的数据。

响应

成功接受的订单将被分配一个订单ID。订单是否成功接受取决于撮合引擎是否接受。 未成交的订单不会过期,并将保持撮合状态,直到被成交或取消。

返回示例
{
    "client_oid":"oktspot79",
    "error_code":"",
    "error_message":"",
    "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 limitmarket(默认是limit),当以market(市价)下单,order_type只能选择0(普通委托)
side String buysell
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_idclient_oid必须且只能选一个填写,由您设置的订单ID来识别您的订单 , 类型为字母(大小写)+数字或者纯字母(大小写)1-32位字符
order_id String order_idclient_oid必须且只能选一个填写,订单ID
返回参数
参数名 类型 描述
order_id String 订单ID
client_oid String 由您设置的订单ID来识别您的订单
result Boolean 撤单申请结果。若是撤单失败,将给出错误码提示
error_code String 错误码,下单成功时为空,下单失败时会显示相应错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
解释说明

order_idclient_oid必须且只能选一个填写

使用client_oid撤单时,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单时只能撤销最新的一条数据

如果订单无法取消(已经成交或已取消),那么返回的报错内容里将显示相应的原因。

返回示例
{
    "btc-usdt":[
    {
       "result":true,
        "client_oid":"a123",
        "order_id": "2510832677225473"
     }
]
}

批量撤销订单

撤销指定的某一种或多种币对的未完成订单(每次只能下最多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":"ltc-usdt","client_oids":["a12345","a123456"]}]

请求参数
参数名 类型 是否必填 描述
order_ids List<String> order_idclient_oid必须且只能选一个填写,订单ID
client_oids List<String> order_idclient_oid必须且只能选一个填写,由您设置的订单ID来识别您的订单,类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符
instrument_id String 币种
返回参数
参数名 类型 描述
order_id String 订单ID
client_oid String 由您设置的订单ID来识别您的订单
instrument_id String 币种,如btc-usdt
result Boolean 撤单申请结果
解释说明

批量撤单时候,要么都是order_id要么都是client_oid,否则会提示错误

使用client_oid批量撤单时,目前只支持一个币对下撤一个client_oid ,一次4个币对,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单时只能撤销最新的一条数据

使用order_id撤单时,每次最多4个币对且每个币对最多10个订单,建议用户调用批量撤单接口后,再调用获取订单列表接口确认已撤销成功。

返回示例
{
    "btc-usdt":[
    {
       "result":true,
        "client_oid":"a123",
        "order_id": "2510832677225473"
     },
   {
       "result":true,
        "client_oid":"a1234",
        "order_id": "2510832677225474"
     }
],
"ltc-usdt":[
    {
       "result":true,
        "client_oid":"a12345",
        "order_id": "2510832677225475"
     },
   {
       "result":true,
        "client_oid":"a123456",
        "order_id": "2510832677225476"
     }
]
}

获取订单列表

列出您当前的订单信息(本接口能查询最近3个月订单信息)。这个请求支持分页,并且按委托时间倒序排序和存储,最新的排在最前面。

限速规则:20次/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 limitmarket(默认是limit
side String buysell
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 成交均价
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换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",
            "state":"-2",
            "timestamp":"2019-03-18T07:26:49.000Z",
            "type":"limit"
     },
     {
            "client_oid":"oktspot75",
            "created_at":"2019-03-18T07:26:49.000Z",
            "filled_notional":"3.9734",
            "filled_size":"0.001",
            "funds":"",
            "instrument_id":"BTC-USDT",
            "notional":"",
            "order_id":"2500723297223680",
            "order_type":"0",
            "price":"4013",
            "price_avg": "4013",
            "product_id":"BTC-USDT",
            "side":"buy",
            "size":"0.001",
            "status":"filled",
            "state": "-2",    
            "timestamp":"2019-03-18T07:26:49.000Z",
            "type":"limit"
     },
     {
            "client_oid":"oktspot74",
            "created_at":"2019-03-18T07:08:24.000Z",
            "filled_notional":"3.9768",
            "filled_size":"0.001",
            "funds":"",
            "instrument_id":"BTC-USDT",
            "notional":"",
            "order_id":"2500650881647616",
            "order_type":"0",
            "price":"4016.8",
            "price_avg": "4013",
            "product_id":"BTC-USDT",
            "side":"buy",
            "size":"0.001",
            "staus":"filled",
            "state": "-2",    
            "timestamp":"2019-03-18T07:08:24.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 buysell
type String limitmarket(默认是limit
timestamp String 订单创建时间
filled_size String 已成交数量
filled_notional String 已成交金额
state String 订单状态
0:等待成交
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换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",
            "state":"0",
            "timestamp":"2019-03-20T03:28:14.000Z",
            "type":"limit"
        },
        {
            "client_oid":"oktspot85",
            "created_at":"2019-03-20T03:28:10.000Z",
            "filled_notional":"0",
            "filled_size":"0",
            "funds":"",
            "instrument_id":"BTC-USDT",
            "notional":"",
            "order_id":"2511109459543040",
            "order_type":"0",
            "price":"3594.9",
            "price_avg":"",
            "product_id":"BTC-USDT",
            "side":"buy",
            "size":"0.001",
            "status":"open",
            "state":"0",
            "timestamp":"2019-03-20T03:28:10.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 buysell
type String limitmarket(默认是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 成交均价
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换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",
    "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&after=2&before=4

请求参数
参数名 参数类型 是否必须 描述
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 流动性方向(TM
fee String 手续费
side String 账单方向(buysell
解释说明

手续费

fee字段:负数的fee表示平台收取的手续费,正数的fee表示表示平台向达到指定lv交易等级的用户支付的挂单奖励(返佣)

流动性

exec_type字段表示该账单是maker还是taker产生的。M表示Maker,T表示Taker。

分页

返回账单列表的ledger_id按降序排列,从最大ledger_id到最小ledger_idOK-after都会有这样的第一笔ledger_id,以便将来的请求使用OK-after参数将获取一个更大的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"
        },
]

委托策略下单

委托策略下单

提供止盈止损、跟踪委托、冰山委托和时间加权委托策略

限速规则: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:时间加权
size String 委托总数,填写值1\<=X\<=1000000的整数
side String buysell
止盈止损参数 (最多同时存在10单)
参数名 参数类型 是否必须 描述
trigger_price String 触发价格,填写值0\<X\<=1000000
algo_price String 委托价格,填写值0\<X\<=1000000
跟踪委托参数 (最多同时存在10单)
参数名 参数类型 是否必须 描述
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 单笔均值,填写2-1000的整数(永续2-500的整数)
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 单笔上限,填写值10\<=X\<=2000(永续2-500的整数)
limit_price String 价格限制,填写值0\<X\<=1000000
time_interval String 委托间隔,填写值5\<=X\<=120

返回参数

参数名 参数类型 描述
result String 调用接口返回结果
algo_id String 订单ID,下单失败时,此字段值为-1
返回示例
{
    "algo_id": 329967,
    "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:时间加权
返回参数
参数名 参数类型 描述
instrument_id String 指定的币对
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
algo_ids String 撤销指定的委托单ID
result String 调用接口返回结果

返回参数

返回值是已发起撤销操作的委托单ID,不代表这些委托单已成功撤销,正在成交中的无法撤销,未成交的可成功撤销。

解释说明

无法保证一定会成功撤销,建议用户调用撤单接口后,再调用获取委托单列表接口确认。

返回示例
{
    "result": true,
    "algo_ids": [
        "329967"
    ],
    "instrument_id": "BTC-USDT",
    "order_type": "1"
}

获取委托单列表

获取委托单列表

列出您当前所有的订单信息。

限速规则: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:时间加权
status String 非必填 statusalgo_id必填且只能填其一】
订单状态
1:待生效
2:已生效
3:已撤销
4:部分生效
5:暂停生效
6:委托失败
【只有冰山和加权有45状态】
algo_id String 非必填 statusalgo_id必填且只能填其一】
查询指定的委托单ID
before string 请求此id之后(更新的数据)的分页内容
after string 请求此id之前(更旧的数据)的分页内容
limit string 分页返回的结果集数量,默认为100,最大为100
返回参数
参数名 参数类型 描述
instrument_id String 指定的币对
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
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 BuySell
trigger_price String 策略委托触发价格

止盈止损

参数名 参数类型 描述
trigger_price String 触发价格,填写值0\<X
algo_price String 委托价格,填写值0\<X\<=1000000
real_amount String 实际成交数量

跟踪委托

参数名 参数类型 描述
callback_rate String 回调幅度,填写值0.001(0.1%)\<=X\<=0.05(5%)
trigger_price String 激活价格 ,填写值0\<X\<=1000000
real_amount String 实际委托数量

冰山委托

参数名 参数类型 描述
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 已委托量
返回示例
{
    "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

请求示例

2018-09-12T07:56:45.645ZGET /api/spot/v3/instruments

返回参数
参数名 类型 描述
instrument_id String 币对名称
base_currency String 交易货币币种
quote_currency String 计价货币币种
min_size String 最小交易数量
size_increment String 交易货币数量精度
tick_size String 交易价格精度
解释说明

min_size指下单数量的最小值(交易货币)。size_increment(交易数量步长)是指下单数量的最小增量。例如,当size_increment0.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",
        "tick_size":"0.1"
    },
    {
        "base_currency":"OKB",
        "instrument_id":"OKB-USDT",
        "min_size":"1",
        "quote_currency":"USDT",
        "size_increment":"0.0001",
        "tick_size":"0.0001"
    }
]

公共-获取深度数据

获取币对的深度列表。这个请求不支持分页,一个请求返回整个深度列表。

限速规则:20次/2s
HTTP请求

GET /api/spot/v3/instruments/<instrument_id>/book

请求示例

2019-03-20T07:48:09.130ZGET /api/spot/v3/instruments/BTC-USDT/book?size=5&depth=0.2

请求参数
参数名 类型 描述
size String [ 非必填 ] 返回深度档位数量,最多返回200
depth String [ 非必填 ] 按价格合并深度,例如:0.10.001
instrument_id String [ 必填 ] 币对
返回参数
返回数据
参数名 类型 描述
asks List<String> 卖方深度
bids List<String> 买方深度
timestamp String 时间戳
解释说明

asks和bids值数组举例说明: ["411.8","10","8"] 411.8为深度价格,10为此价格数量,8为此深度由几笔订单组成。

size不传时,返回200条;size0时,返回0条;size最大200,传大于200的数时,返回200条。

按价格合并深度是指每个价格区间将仅返回一个数量,就像在该价格区间上只有一个订单。

asks: 卖方深度
bids: 买方深度

返回示例
{
    "asks":[
        [
            "3993.2",
            "0.41600068",
            "1"
        ],
        [
            "3993.4",
            "1.24807818",
            "3"
        ],
        [
            "3993.6",
            "0.03",
            "1"
        ],
        [
            "3993.8",
            "0.03",
            "1"
        ]
    ],
    "bids":[
        [
            "3993",
            "0.15149658",
            "2"
        ],
        [
            "3992.8",
            "1.19046818",
            "1"
        ],
        [
            "3992.6",
            "0.20831389",
            "1"
        ],
        [
            "3992.4",
            "0.01669446",
            "2"
        ]
    ],
    "timestamp":"2019-03-20T03:55:37.888Z"
}

公共-获取全部ticker信息

获取平台全部币对的最新成交价、买一价、卖一价和24小时交易量的快照信息。

限速规则:50次/2s
HTTP请求

GET /api/spot/v3/instruments/ticker

请求示例

2018-09-12T07:57:26.537ZGET /api/spot/v3/instruments/ticker

返回参数
参数名 类型 描述
instrument_id String 币对名称
last String 最新成交价
best_bid String 买一价
best_ask 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":"3995.4",
        "best_bid":"3995.3",
        "instrument_id":"BTC-USDT",
        "product_id":"BTC-USDT",
        "last":"3995.3",
        "ask":"3995.4",
        "bid":"3995.3",
        "open_24h":"3989.7",
        "high_24h":"4031.9",
        "low_24h":"3968.9",
        "base_volume_24h":"31254.359231295",
        "timestamp":"2019-03-20T04:07:07.912Z",
        "quote_volume_24h":"124925963.3459723295"
    },
    {
        "best_ask":"1.3205",
        "best_bid":"1.3204",
        "instrument_id":"OKB-USDT",
        "product_id":"OKB-USDT",
        "last":"1.3205",
        "ask":"1.3205",
        "bid":"1.3204",
        "open_24h":"1.0764",
        "high_24h":"1.44",
        "low_24h":"1.0601",
        "base_volume_24h":"183010468.2062",
        "timestamp":"2019-03-20T04:07:05.878Z",
        "quote_volume_24h":"233516598.011530085"
    }
]

公共-获取某个ticker信息

获取币对的最新成交价、买一价、卖一价和24小时交易量的快照信息。

限速规则:20次/2s
HTTP请求

GET /api/spot/v3/instruments/<instrument-id>/ticker

请求示例

2019-03-13T11:42:09.849ZGET /api/spot/v3/instruments/BTC-USDT/ticker

请求参数
参数名 类型 描述
instrument_id String [ 必填 ] 币对
返回参数
参数名 类型 描述
instrument_id String 币对名称
last String 最新成交价
best_bid String 买一价
best_ask 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": "8120.6",
    "best_bid": "8120",
    "instrument_id": "BTC-USDT",
    "product_id": "BTC-USDT",
    "last": "8120",
    "ask": "8120.6",
    "bid": "8120",
    "open_24h": "8232.6",
    "high_24h": "8395.9",
    "low_24h": "8068.2",
    "base_volume_24h": "13508.4",
    "timestamp": "2019-10-03T15:49:38.506Z",
    "quote_volume_24h": "111036129.6"
}

公共-获取成交数据

本接口能查询最近60条数据。这个请求支持分页,并且按时间倒序排序和存储,最新的排在最前面。请参阅分页部分以获取第一页之后的其他纪录。

限速规则:20次/2s
HTTP请求

GET /api/spot/v3/instruments/<instrument_id>/trades

签名请求示例

2018-09-12T07:58:34.414ZGET /api/spot/v3/instruments/LTC-USDT/trades?limit=20&after=2&before=4

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 币对名称
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的trade_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的trade_id
limit String 分页返回的结果集数量,最大为60,不填默认返回60条
返回参数
参数名 类型 描述
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线数据最多可获取最近2000条。

限速规则:20次/2s
HTTP请求

GET /api/spot/v3/instruments/<instrument_id>/candles

签名请求示例

GET /api/spot/v3/instruments/BTC-USDT/candles?granularity=86400&start=2019-03-18T08%3A28%3A48.899Z&end=2019-03-19T09%3A28%3A48.899Z

请求参数
参数名 参数类型 是否必须 描述
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]中的任一值,否则请求将被拒绝。这些值分别对应的是[1min 3min 5min 15min 30min 1hour 2hour 4hour 6hour 12hour 1day 1week]的时间段。

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

币币杠杆交易的行情信息,账户信息,订单操作,订单查询,账单明细查询。

说明:因为要和老版本做兼融,实际有些接口返回参数会有多余,请以文档中返回参数说明为准。

例如币币账户信息接口返回frozenholdholds参数值相同,以hold为准;获取借币记录接口返回参数 repay_amountreturned_amountrepay_interestpaid_interest 参数的值相同,product_idinstrument_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 保证金率
解释说明

当你下市价单或限价单时,订单所需的资金将被冻结。这部分数量将不能被用于其他订单或者资金划转。资金将一直被冻结直至订单被成交或者取消。

返回示例
[
    {
        "currency:BTC": {
            "available": "0.03044298",
            "balance": "0.03044298",
            "borrowed": "0",
            "can_withdraw": "0.02952103",
            "frozen": "0",
            "hold": "0",
            "holds": "0",
            "lending_fee": "0"
        },
        "currency:USDT": {
            "available": "6.24820656",
            "balance": "6.24820656",
            "borrowed": "11",
            "can_withdraw": "6.24820656",
            "frozen": "0",
            "hold": "0",
            "holds": "0",
            "lending_fee": "0.01941356"
        },
        "instrument_id": "BTC-USDT",
        "liquidation_price": "192.8",
        "margin_ratio": "22.1438",
        "product_id": "BTC-USDT",
        "risk_rate": "23.1438"
    },
    {
        "currency:LTC": {
            "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"
        },
        "instrument_id": "LTC-USDT",
        "liquidation_price": "0",
        "margin_ratio": "",
        "product_id": "LTC-USDT",
        "risk_rate": ""
    },
]

单一币对账户信息

获取币币杠杆某币对账户的余额、冻结和可用等信息。

限速规则: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 保证金率
返回示例
{
    "currency:BTC": {
        "available": "0.03044298",
        "balance": "0.03044298",
        "borrowed": "0",
        "can_withdraw": "0.02952383",
        "frozen": "0",
        "hold": "0",
        "holds": "0",
        "lending_fee": "0"
    },
    "currency:USDT": {
        "available": "6.24820656",
        "balance": "6.24820656",
        "borrowed": "11",
        "can_withdraw": "6.24820656",
        "frozen": "0",
        "hold": "0",
        "holds": "0",
        "lending_fee": "0.01983016"
    },
    "liquidation_price": "192.8",
    "margin_ratio": "22.2138",
    "risk_rate": "23.2138"
}

账单流水查询

列出杠杆帐户资产流水。帐户资产流水是指导致帐户余额增加或减少的行为。流水会分页,并且按时间倒序排序和存储,最新的排在最前面。请参阅分页部分以获取第一页之后的其他纪录。 本接口能查询最近3个月的数据。

限速规则:20次/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

请求参数
参数名 参数类型 是否必须 描述
currency String 币种
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的ledger_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的ledger_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条
type String 1 .充值
2 .提现
3 .借入
4 .还款
7 .买入
8 .卖出
9 .新手任务
10 .邀请好友完成新手任务
11 .扣除任务奖励
12 .邀请分成
13 .撤销提现
14 .活动送出
15 .活动得到
18 .交割合约转入
19 .转出至交割合约
20 .转入子账户
21 .转出至子账户
22 .返手续费
23 .接收红包
24 .发送红包
25 .otc买入
26 .otc卖出
27 .扣除
28 .兑换
29 .转出至资金账户
30 .资金账户转入
31 .转出至法币
32 .法币转入
33 .转出至杠杆
34 .杠杆转入
35 .借币
36 .还币
37 .市商计划送出
38 .市商计划返还
41 .点卡抵扣币币手续费
42 .购买点卡
43 .点卡转让
44 .市商计划额外送出
45 .市商计划返还
46 .币币账户转入
47 .转出至币币账户
48 .转出至组合
49 .组合转入
50 .挖矿扣除
51 .挖矿所得
52 .收益倍增
53 .鼓励金分配
55 .余币宝转入
56 .转出至余币宝
57 .永续合约转入
58 .转出至永续合约
59 .还糖果
60 .点卡抵扣杠杆手续费
返回参数
参数名 类型 描述
ledger_id String 账单ID
instrument_id String 杠杆币对名称
currency String 币种
balance String 余额
amount String 变动数量
type String 流水来源
timestamp String 账单创建时间
details String 如果typetrade或者fee,则会有该details字段将包含orderinstrument信息
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 41,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 杠杆币对名称
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,不填时还整个币对的币
instrument_id String 杠杆币对名称
currency String 币种
amount String 还币数量
返回参数
参数名 类型 描述
repayment_id String 还币记录ID
client_oid String 由您设置的订单ID来识别您的订单
result Boolean 结果
返回示例
{
    "client_oid":"",
    "repayment_id":"791434",
    "result":true
}

下单

OKEx API提供limitmarket两种下单模式。只有当您的账户有足够的资金才能下单。一旦下单,您的账户资金将在订单生命周期内被冻结。被冻结的资金以及数量取决于订单指定的类型和参数。

限速规则: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 limitmarket(默认是limit)。当以market(市价)下单,order_type只能选择0(普通委托)
side String buysell
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 错误码,下单成功时为空,下单失败时会显示相应错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
result Boolean 下单结果。若是下单失败,将给出错误码提示。
解释说明

client_oid的类型为字母+数字或者纯字母(大小写),1-32位字符 ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单和查询订单时只能撤销或者查询出最新的一条数据。

instrument_id

instrument_id必须是有效的币对。币对列表可通过/ instrument接口获取。

type

下单时,您可以指定订单类型。您指定的订单类型将决定是否需要其他订单参数以及撮合引擎如何执行您的订单。如果type没有指定,订单类型将默认为limit。限价单既是默认订单类型,也是基本订单类型。限价单需要指定pricesizesize是买入或卖出交易货币的数量,price表示每个交易货币相对计价货币的价格。限价单会按指定价格或更好的价格成交。根据市场条件,卖单可以按照指定价格或者更高价格来成交,买单可以按照指定价格或更低价格成交。如果限价单不能立即成交,那么限价单将进入深度列表,直到被另一个新订单成交或被用户撤单。 市价单不同于限价单,因为它们不提供价格控制。市价单提供了一种不必指定价格,而以固定数量的货币进行买入或者卖出的方式。市价单下单后会立即撮合,而不会被挂入深度列表。市价单总是吃单方(taker)并承担taker费用。

price

price表示买入或卖出的价格。价格必须是价格步长quote_increment的倍数。价格步长quote_increment是价格的最小增量,可通过instrument接口获取。

size

size表示买入或卖出交易货币的数量。数量必须大于base_min_size。交易数量步长base_increment是数量的最小增量。上述参数都可通过instrument接口获取。

notional

notional表示被用于市价买入的计价货币的数量,市价买入时必填。例如,在BTC-USDT交易时,市价单指定5000 USDT表示将花费5000 USDT购买BTC。

hold

对于限价买单,系统将冻结计价货币的数量 = 限定价格 x 买入数量。对于限价卖单,系统将冻结你想卖出的交易货币的数量。对于市价买单,funds数量的计价货币将被冻结。对于市价卖单,size数量的交易货币将被冻结。如果您取消部分成交或未成交的订单,剩余资金将被解除冻结。

订单生命周期

HTTP请求将在订单被拒绝(资金不足,参数无效等)或下单成功(由匹配引擎接受)时作出响应。一个200响应表示该订单被接收并且进入撮合。进入撮合的订单可以部分或全部立即成交(取决于价格和市场条件)。部分成交的时候将把订单的剩余数量继续进行撮合。完全成交的订单将进入已成交状态。 监听行情数据的用户建议使用client_oid字段以便在接受到的信息中标识对应的数据。

响应

成功接受的订单将被分配一个订单ID。成功接受的订单表示撮合引擎已经接受的订单。 未成交的订单不会过期,并将保持撮合状态,直到被成交或取消。

返回示例
{
    "client_oid":"oktlever50",
    "error_code":"",
    "error_message":"",
    "order_id":"2512084870235136",
    "result":true
}

批量下单

下指定币对的多个订单(每次只能下最多4个币对且每个币对可批量下10个单)。

限速规则:50次/2s
HTTP请求

POST /api/margin/v3/batch_orders

签名请求示例

市价单:POST /api/spot/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/spot/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 limitmarket(默认是limit)。当以market(市价)下单,order_type只能选择0(普通委托)
side String buysell
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 错误码
error_message String 错误信息
result Boolean 下单结果。若是下单失败,将给出错误码提示。
解释说明

client_oid的类型为字母(大小写)+数字或者纯字母(大小写)1-32位字符 ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单和查询订单时只能撤销或者查询最新的一条数据。

每次最多4个币对且每个币对最多10个订单,建议用户调用批量撤单接口后,再调用获取订单列表接口确认已撤销成功。

返回示例
{
    "BTC-USDT":[
        {
            "client_oid":"oktlever51",
            "error_code":0,
            "error_message":"",
            "order_id":"2512113685627904",
            "result":true
        },
        {
            "client_oid":"oktlever52",
            "error_code":0,
            "error_message":"",
            "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_idclient_oid必须且只能选一个填写,由您设置的订单ID来识别您的订单 , 类型为字母(大小写)+数字或者纯字母(大小写)1-32位字符
order_id String 非必填 order_idclient_oid必须且只能选一个填写,订单ID
返回参数
参数名 类型 描述
order_id String 订单ID
client_oid String 由您设置的订单ID来识别您的订单
error_code String 错误码
error_message String 错误信息
result Boolean 撤单申请结果。若是撤单失败,将给出错误码提示
解释说明

order_idclient_oid必须且只能选一个填写

使用client_oid撤单时,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单时只能撤销最新的一条数据

如果订单无法取消(已经成交或已取消),那么返回的报错内容里将显示相应的原因。

返回示例
{
    "result":true,
    "client_oid":"a123",
    "order_id": "2510832677225473"
    "error_code": "",
    "error_message": "",
}

批量撤销订单

撤销指定的某一种或多种币对的所有未完成订单,每个币对可批量撤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_idclient_oid必须且只能选一个填写,订单ID
client_oids List<String> order_idclient_oid必须且只能选一个填写,由您设置的订单ID来识别您的订单,类型为字母(大小写)+数字或者纯字母(大小写)1-32位字符
返回参数
参数名 类型 描述
order_id String 订单ID
client_oid String 由您设置的订单ID来识别您的订单
instrument_id String 币种,如btc-usdt
result Boolean 撤单申请结果。若是撤单失败,将给出错误码提示
解释说明

批量撤单一次性时候,要么都是order_id要么都是client_oid,否则会提示错误

使用client_oid批量撤单时,目前只支持一个币对下撤一个client_oid ,一次四个币对,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单时只能撤销最新的一条数据

使用order_id撤单时,每次最多4个币对且每个币对最多10个订单,建议用户调用批量撤单接口后,再调用获取订单列表接口确认已撤销成功。

返回示例
{
    "btc-usdt":[
    {
       "result":true,
        "client_oid":"a123",
        "order_id": "2510832677225473"
     },
   {
       "result":true,
        "client_oid":"a1234",
        "order_id": "2510832677225474"
     }
],
"ltc-usdt":[
    {
       "result":true,
        "client_oid":"a12345",
        "order_id": "2510832677225475"
     },
   {
       "result":true,
        "client_oid":"a123456",
        "order_id": "2510832677225476"
     }
]
}

获取订单列表

列出您当前所有的订单信息(本接口能查询最近100条订单信息)。这个请求支持分页,并且按委托时间倒序排序和存储,最新的排在最前面。

限速规则:20次/2s
HTTP请求

GET /api/margin/v3/orders

签名请求示例

2018-09-12T07:49:43.306ZGET /api/spot/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 buysell
type String limitmarket(默认是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_idclient_oid必须且只能选一个填写
client_oid String [非必填 ] order_idclient_oid必须且只能选一个填写 由您设置的订单ID来识别您的订单 , 类型为字母(大小写)+数字或者纯字母(大小写)1-32位字符
返回参数
参数名 类型 描述
order_id String 订单ID
client_oid String 由您设置的订单ID来识别您的订单
price String 委托价格
size String 委托数量(交易货币数量)
notional String 买入金额,市价买入时返回
instrument_id String 币对名称
side String buysell
type String limitmarket(默认是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 成交均价
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换state

order_idclient_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 buysell
type String limitmarket(默认是limit
timestamp String 订单创建时间
filled_size String 已成交数量
filled_notional String 已成交金额
state String 订单状态
0:等待成交
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换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月的数据。

限速规则:20次/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
to 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 流动性方向(TM
fee String 手续费
side String 订单方向(buysell
解释说明

手续费

fee字段表示这条账单记录所收取的手续费。

流动性

exec_type字段表示该账单是maker还是taker产生的。M表示Maker,T表示Taker。

分页

返回账单列表的ledger_id按降序排列,从最大ledger_id到最小ledger_idOK-AFTER都会有这样的第一笔ledger_id,以便将来的请求使用OK-after参数将获取一个更大的ledger_id(新的账单)。

返回示例
[
        {
            "created_at":"2019-03-18T03:45:57.000Z",
            "exec_type":"M",
            "fee":"0.0004",
            "instrument_id":"EOS-USDT",
            "ledger_id":"77622945",
            "liquidity":"M",
            "order_id":"2499854635054080",
            "price":"3.76",
            "product_id":"EOS-USDT",
            "side":"buy",
            "size":"0.4",
            "timestamp":"2019-03-18T03:45:57.000Z"
        },
        {
            "created_at":"2019-03-18T03:45:57.000Z",
            "exec_type":"M",
            "fee":"0",
            "instrument_id":"EOS-USDT",
            "ledger_id":"77622944",
            "liquidity":"M",
            "order_id":"2499854635054080",
            "price":"3.76",
            "product_id":"EOS-USDT",
            "side":"sell",
            "size":"1.504",
            "timestamp":"2019-03-18T03:45:57.000Z"
        }
]

公共-币币杠杆行情

要实时更新市场数据,请参阅WebSocket文档,以便获取并创建更完整的深度和交易数据。

币币杠杆交易和币币交易共享行情和深度数据,请移步币币行情查看接口。

交割合约API

交割合约交易的行情信息,账户信息,订单操作,订单查询,账单明细查询。

所有合约持仓信息

获取账户所有合约的持仓信息。请求此接口,会在数据库遍历所有币对下的持仓数据,有大量的性能消耗,请求频率较低。建议用户传合约ID获取持仓信息。

限速规则:5次/2s
HTTP请求

GET /api/futures/v3/position

请求示例

GET /api/futures/v3/position

返回参数
全仓
全仓参数名 参数类型 描述
margin_mode String 账户类型
全仓:crossed
liquidation_price String 预估强平价
long_qty String 多仓数量
long_avail_qty String 多仓可平仓数量
long_avg_cost String 开仓平均价
long_settlement_price String 多仓结算基准价
realised_pnl String 已实现盈余
short_qty String 空仓数量
short_avail_qty String 空仓可平仓数量
short_avg_cost String 开仓平均价
short_settlement_price String 空仓结算基准价
instrument_id String 合约ID,如BTC-USD-180213
leverage String 杠杆倍数
created_at String 创建时间
updated_at String 最近一次加减仓的更新时间
short_margin String 空仓保证金
short_pnl String 空仓收益
short_pnl_ratio String 空仓收益率
short_unrealised_pnl String 空仓未实现盈亏
short_settled_pnl String 空仓已结算收益
long_margin String 多仓保证金
long_pnl String 多仓收益
long_pnl_ratio String 多仓收益率
long_unrealised_pnl String 多仓未实现盈亏
long_settled_pnl String 多仓已结算收益
last String 最新成交价
逐仓
逐仓参数名 参数类型 描述
margin_mode String 账户类型
逐仓:fixed
long_qty String 多仓数量
long_avail_qty String 多仓可平仓数量
long_margin String 多仓保证金
long_liqui_price String 多仓强平价格
long_pnl_ratio String 多仓收益率
long_avg_cost String 开仓平均价
long_settlement_price String 多仓结算基准价
realised_pnl String 已实现盈余
long_leverage String 多仓杠杆倍数
short_qty String 空仓数量
short_avail_qty String 空仓可平仓数量
short_margin String 空仓保证金
short_liqui_price String 空仓强平价格
short_pnl_ratio String 空仓收益率
short_avg_cost String 开仓平均价
short_settlement_price String 空仓结算基准价
short_leverage String 空仓杠杆倍数
instrument_id String 合约ID,如BTC-USD-180213
created_at String 创建时间
updated_at String 最近一次加减仓的更新时间
short_margin_ratio String 空仓保证金率
short_maint_margin_ratio String 空仓维持保证金率
short_pnl String 空仓收益
short_unrealised_pnl String 空仓未实现盈亏
long_margin_ratio String 多仓保证金率
long_maint_margin_ratio String 多仓维持保证金率
long_pnl String 多仓收益
long_unrealised_pnl String 多仓未实现盈亏
long_settled_pnl String 多仓已结算收益
short_settled_pnl String 空仓已结算收益
last String 最新成交价
返回示例
全仓
{
    "result": true,
    "holding": [
        [
            {
                "long_qty": "0",
                "long_avail_qty": "0",
                "long_avg_cost": "0",
                "long_settlement_price": "0",
                "realised_pnl": "-0.0001318",
                "short_qty": "0",
                "short_avail_qty": "0",
                "short_avg_cost": "8181.88",
                "short_settlement_price": "8181.88",
                "liquidation_price": "113.81",
                "instrument_id": "BTC-USD-191018",
                "leverage": "10",
                "created_at": "2019-10-08T11:56:07.922Z",
                "updated_at": "2019-10-08T14:02:06.861Z",
                "margin_mode": "crossed",
                "short_margin": "0.0",
                "short_pnl": "0.0",
                "short_pnl_ratio": "-0.027818392",
                "short_unrealised_pnl": "0.0",
                "long_margin": "0.0",
                "long_pnl": "0.0",
                "long_pnl_ratio": "0.0",
                "long_unrealised_pnl": "0.0",
                "long_settled_pnl": "0",
                "short_settled_pnl": "0",
                "last": "8202.92"
            },
            {
                "long_qty": "2",
                "long_avail_qty": "2",
                "long_avg_cost": "8260",
                "long_settlement_price": "8260",
                "realised_pnl": "0.00020928",
                "short_qty": "2",
                "short_avail_qty": "2",
                "short_avg_cost": "8259.99",
                "short_settlement_price": "8259.99",
                "liquidation_price": "113.81",
                "instrument_id": "BTC-USD-191227",
                "leverage": "10",
                "created_at": "2019-09-25T07:58:42.129Z",
                "updated_at": "2019-10-08T14:02:51.029Z",
                "margin_mode": "crossed",
                "short_margin": "0.002422",
                "short_pnl": "6.9E-6",
                "short_pnl_ratio": "0.002477997",
                "short_unrealised_pnl": "6.9E-6",
                "long_margin": "0.002422",
                "long_pnl": "-6.92E-6",
                "long_pnl_ratio": "-0.002478",
                "long_unrealised_pnl": "-6.92E-6",
                "long_settled_pnl": "0",
                "short_settled_pnl": "0",
                "last": "8257.65"
            }
        ]
    ]
}
逐仓
{
    "result": true,
    "holding": [
        [
            {
                "long_qty": "0",
                "long_avail_qty": "0",
                "long_margin": "0",
                "long_liqui_price": "0",
                "long_pnl_ratio": "0",
                "long_avg_cost": "0",
                "long_settlement_price": "0",
                "realised_pnl": "-0.00001222",
                "short_qty": "2",
                "short_avail_qty": "2",
                "short_margin": "0.00244443",
                "short_liqui_price": "9040.9",
                "short_pnl_ratio": "-0.06463685",
                "short_avg_cost": "8181.88",
                "short_settlement_price": "8181.88",
                "instrument_id": "BTC-USD-191018",
                "long_leverage": "0",
                "short_leverage": "10",
                "created_at": "2019-10-08T11:56:07.922Z",
                "updated_at": "2019-10-08T11:56:08.002Z",
                "margin_mode": "fixed",
                "short_margin_ratio": "0.09410211",
                "short_maint_margin_ratio": "0.005",
                "short_pnl": "-1.5915E-4",
                "short_unrealised_pnl": "-1.5915E-4",
                "long_margin_ratio": "10000.0",
                "long_maint_margin_ratio": "0.005",
                "long_pnl": "0.0",
                "long_unrealised_pnl": "0.0",
                "long_settled_pnl": "0",
                "short_settled_pnl": "0",
                "last": "8237.72"
            },
            {
                "long_qty": "4",
                "long_avail_qty": "4",
                "long_margin": "0.00323844",
                "long_liqui_price": "7762.09",
                "long_pnl_ratio": "0.10622415",
                "long_avg_cost": "8234.43",
                "long_settlement_price": "8234.43",
                "realised_pnl": "-0.00000296",
                "short_qty": "2",
                "short_avail_qty": "2",
                "short_margin": "0.00241105",
                "short_liqui_price": "9166.74",
                "short_pnl_ratio": "0.00248854",
                "short_avg_cost": "8295.13",
                "short_settlement_price": "8295.13",
                "instrument_id": "BTC-USD-191227",
                "long_leverage": "15",
                "short_leverage": "10",
                "created_at": "2019-09-25T07:58:42.129Z",
                "updated_at": "2019-10-08T13:12:09.438Z",
                "margin_mode": "fixed",
                "short_margin_ratio": "0.1002126",
                "short_maint_margin_ratio": "0.005",
                "short_pnl": "5.7E-6",
                "short_unrealised_pnl": "5.7E-6",
                "long_margin_ratio": "0.07427591",
                "long_maint_margin_ratio": "0.005",
                "long_pnl": "3.4407E-4",
                "long_unrealised_pnl": "3.4407E-4",
                "long_settled_pnl": "0",
                "short_settled_pnl": "0",
                "last": "8294.07"
            }
        ]
    ]
}

单个合约持仓信息

获取某个合约的持仓信息。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/<instrument_id>/position

请求示例

GET /api/futures/v3/BTC-USD-180309/position

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
返回参数
全仓
全仓参数名 参数类型 描述
margin_mode String 账户类型
全仓:crossed
liquidation_price String 预估强平价
long_qty String 多仓数量
long_avail_qty String 多仓可平仓数量
long_avg_cost String 开仓平均价
long_settlement_price String 结算基准价
realised_pnl String 已实现盈余
leverage String 杠杆倍数
short_qty String 空仓数量
short_avail_qty String 空仓可平仓数量
short_avg_cost String 开仓平均价
short_settlement_price String 结算基准价
instrument_id String 合约ID,如BTC-USD-180213
created_at String 创建时间
updated_at String 最近一次加减仓的更新时间
short_margin String 空仓保证金
short_pnl String 空仓收益
short_pnl_ratio String 空仓收益率
short_unrealised_pnl String 空仓未实现盈亏
short_settled_pnl String 空仓已结算收益
long_margin String 多仓保证金
long_pnl String 多仓收益
long_pnl_ratio String 多仓收益率
long_unrealised_pnl String 多仓未实现盈亏
long_settled_pnl String 多仓已结算收益
last String 最新成交价
逐仓
逐仓参数名 参数类型 描述
margin_mode String 账户类型
逐仓:fixed
long_qty String 多仓数量
long_avail_qty String 多仓可平仓数量
long_margin String 多仓保证金
long_liqui_price String 多仓强平价格
long_pnl_ratio String 多仓盈亏比
long_avg_cost String 开仓平均价
long_settlement_price String 结算基准价
realised_pnl String 已实现盈余
long_leverage String 多仓杠杆倍数
short_qty String 空仓数量
short_avail_qty String 空仓可平仓数量
short_margin String 空仓保证金
short_liqui_price String 空仓强平价格
short_pnl_ratio String 空仓盈亏比
short_avg_cost String 开仓平均价
short_settlement_price String 结算基准价
short_leverage String 空仓杠杆倍数
instrument_id String 合约ID,如BTC-USD-180213
created_at String 创建时间
updated_at String 最近一次加减仓的更新时间
short_margin_ratio String 空仓保证金率
short_maint_margin_ratio String 空仓维持保证金率
short_pnl String 空仓收益
short_unrealised_pnl String 空仓未实现盈亏
short_settled_pnl String 空仓已结算收益
long_margin_ratio String 多仓保证金率
long_maint_margin_ratio String 多仓维持保证金率
long_pnl String 多仓收益
long_unrealised_pnl String 多仓未实现盈亏
long_settled_pnl String 多仓已结算收益
last String 最新成交价
返回示例
全仓
{
    "result": true,
    "holding": [
        {
            "long_qty": "2",
            "long_avail_qty": "2",
            "long_avg_cost": "8260",
            "long_settlement_price": "8260",
            "realised_pnl": "0.00020928",
            "short_qty": "2",
            "short_avail_qty": "2",
            "short_avg_cost": "8259.99",
            "short_settlement_price": "8259.99",
            "liquidation_price": "113.81",
            "instrument_id": "BTC-USD-191227",
            "leverage": "10",
            "created_at": "2019-09-25T07:58:42.129Z",
            "updated_at": "2019-10-08T14:02:51.029Z",
            "margin_mode": "crossed",
            "short_margin": "0.00242197",
            "short_pnl": "6.63E-6",
            "short_pnl_ratio": "0.002477997",
            "short_unrealised_pnl": "6.63E-6",
            "long_margin": "0.00242197",
            "long_pnl": "-6.65E-6",
            "long_pnl_ratio": "-0.002478",
            "long_unrealised_pnl": "-6.65E-6",
            "long_settled_pnl": "0",
            "short_settled_pnl": "0",
            "last": "8257.57"
        }
    ],
    "margin_mode": "crossed"
}
逐仓
{
    "result": true,
    "holding": [
        {
            "long_qty": "4",
            "long_avail_qty": "4",
            "long_margin": "0.00323844",
            "long_liqui_price": "7762.09",
            "long_pnl_ratio": "0.06052306",
            "long_avg_cost": "8234.43",
            "long_settlement_price": "8234.43",
            "realised_pnl": "-0.00000296",
            "short_qty": "2",
            "short_avail_qty": "2",
            "short_margin": "0.00241105",
            "short_liqui_price": "9166.74",
            "short_pnl_ratio": "0.03318052",
            "short_avg_cost": "8295.13",
            "short_settlement_price": "8295.13",
            "instrument_id": "BTC-USD-191227",
            "long_leverage": "15",
            "short_leverage": "10",
            "created_at": "2019-09-25T07:58:42.129Z",
            "updated_at": "2019-10-08T13:12:09.438Z",
            "margin_mode": "fixed",
            "short_margin_ratio": "0.10292507",
            "short_maint_margin_ratio": "0.005",
            "short_pnl": "7.853E-5",
            "short_unrealised_pnl": "7.853E-5",
            "long_margin_ratio": "0.07103743",
            "long_maint_margin_ratio": "0.005",
            "long_pnl": "1.9841E-4",
            "long_unrealised_pnl": "1.9841E-4",
            "long_settled_pnl": "0",
            "short_settled_pnl": "0",
            "last": "8266.99"
        }
    ],
    "margin_mode": "fixed"
}

所有币种合约账户信息

获取合约账户所有币种的账户信息。请求此接口,会在数据库遍历所有币对下的账户数据,有大量的性能消耗,请求频率较低。建议用户传币种获取账户信息信息。

限速规则:1次/10s
HTTP请求

GET /api/futures/v3/accounts

请求示例

GET /api/futures/v3/accounts

返回参数
全仓
全仓参数名 参数类型 描述
currency String 币种,如:btc
margin_mode String 账户类型
全仓:crossed
equity String 账户权益
total_avail_balance String 账户余额
margin String 保证金(挂单冻结+持仓已用)
margin_frozen String 持仓已用保证金
margin_for_unfilled String 挂单冻结保证金
realized_pnl String 已实现盈亏
unrealized_pnl String 未实现盈亏
margin_ratio String 保证金率
maint_margin_ratio String 维持保证金率
liqui_mode string 强平模式:tier(梯度强平)
can_withdraw string 可划转数量
liqui_fee_rate string 强平手续费
逐仓
逐仓参数名 参数类型 描述
currency String 币种,如:btc
margin_mode String 账户类型
逐仓:fixed
fixed_balance String 逐仓账户余额
available_qty String 逐仓可用余额
margin_frozen String 持仓已用保证金
margin_for_unfilled String 挂单冻结保证金
instrument_id String 合约ID,如BTC-USD-180213
realized_pnl String 已实现盈亏
unrealized_pnl String 未实现盈亏
equity String 账户权益(账户动态权益)
total_avail_balance String 账户余额(账户静态权益)
auto_margin String 是否自动追加保证金
1: 自动追加已开启
0: 自动追加未开启
liqui_mode string 强平模式:tier(梯度强平)
can_withdraw string 可划转数量
解释说明

所有持仓/所有账户信息,没有持仓/持币时返回空数组;单个持仓/单个账户信息没有持仓/持币时返回各字段均为默认值;

逐仓:

1.账户权益:账户权益=账户余额+逐仓仓位账户余额+所有合约的已实现盈亏+所有合约的未实现盈亏

2.可用:可用余额=账户余额+逐仓仓位账户余额+本合约已实现盈亏- 当前仓位的持仓所需保证金 - 挂单冻结保证金

全仓:

1.账户权益=账户余额+所有合约的已实现盈亏+所有合约的未实现盈亏

2.可用余额=账户余额+所有合约已实现盈亏+所有合约的未实现- 所有仓位持仓所需保证金 - 挂单冻结保证金

返回示例
全仓
{
    "info": {
        "btc": {
            "can_withdraw": "0.00812559",
            "equity": "0.01125076",
            "liqui_fee_rate": "0.0005",
            "liqui_mode": "tier",
            "maint_margin_ratio": "0.005",
            "margin": "0.00312517",
            "margin_for_unfilled": "0",
            "margin_frozen": "0.00312517",
            "margin_mode": "crossed",
            "margin_ratio": "0.23077227",
            "realized_pnl": "-0.00007907",
            "total_avail_balance": "0.01132985",
            "unrealized_pnl": "-0.00000002"
        },
        "eos": {
            "can_withdraw": "18.7120227",
            "equity": "19.96280444",
            "liqui_fee_rate": "0.0005",
            "liqui_mode": "tier",
            "maint_margin_ratio": "0.01",
            "margin": "1.25078174",
            "margin_for_unfilled": "0",
            "margin_frozen": "1.25078174",
            "margin_mode": "crossed",
            "margin_ratio": "1.59602621",
            "realized_pnl": "-0.005272",
            "total_avail_balance": "19.97",
            "unrealized_pnl": "-0.00192356"
        }
    }
}
逐仓
{
    "info": {
        "btc": {
            "auto_margin": "0",
            "can_withdraw": "0.00473265",
            "contracts": [
                {
                    "available_qty": "0.00473265",
                    "fixed_balance": "0.00004645",
                    "instrument_id": "BTC-USD-191018",
                    "margin_for_unfilled": "0",
                    "margin_frozen": "0",
                    "realized_pnl": "-0.00004645",
                    "unrealized_pnl": "0"
                },
                {
                    "available_qty": "0.00473265",
                    "fixed_balance": "0.00655075",
                    "instrument_id": "BTC-USD-191227",
                    "margin_for_unfilled": "0",
                    "margin_frozen": "0.00646337",
                    "realized_pnl": "-0.00008738",
                    "unrealized_pnl": "-0.0001"
                }
            ],
            "equity": "0.01118081",
            "liqui_mode": "tier",
            "margin_mode": "fixed",
            "total_avail_balance": "0.00473265"
        },
        "eos": {
            "auto_margin": "0",
            "can_withdraw": "18.69775421",
            "contracts": [
                {
                    "available_qty": "18.69775421",
                    "fixed_balance": "1.27224579",
                    "instrument_id": "EOS-USD-191227",
                    "margin_for_unfilled": "0",
                    "margin_frozen": "1.25058623",
                    "realized_pnl": "-0.02165956",
                    "unrealized_pnl": "-0.002"
                }
            ],
            "equity": "19.94638549",
            "liqui_mode": "tier",
            "margin_mode": "fixed",
            "total_avail_balance": "18.69775421"
        }
    }
}

单个币种合约账户信息

获取单个币种的合约账户信息。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/accounts/{currency}

请求示例

GET /api/futures/v3/accounts/btc

请求参数
参数名 参数类型 是否必须 描述
currency String 币种,如:btc
返回参数
全仓
全仓参数名 参数类型 描述
margin_mode String 账户类型
全仓:crossed
equity String 账户权益
total_avail_balance String 账户余额
margin String 保证金(挂单冻结+持仓已用)
margin_frozen String 持仓已用保证金
margin_for_unfilled String 挂单冻结保证金
realized_pnl String 已实现盈亏
unrealized_pnl String 未实现盈亏
margin_ratio String 保证金率
maint_margin_ratio String 维持保证金率
liqui_mode string 强平模式:tier(梯度强平)
can_withdraw string 可划转数量
liqui_fee_rate string 强平手续费
逐仓
逐仓参数名 参数类型 描述
margin_mode String 账户类型
逐仓:fixed
fixed_balance String 逐仓账户余额
available_qty String 逐仓可用余额
margin_frozen String 持仓已用保证金
margin_for_unfilled String 挂单冻结保证金
instrument_id String 合约ID,如BTC-USD-180213
realized_pnl String 已实现盈亏
unrealized_pnl String 未实现盈亏
equity String 账户权益(账户动态权益)
total_avail_balance String 账户余额(账户静态权益)
auto_margin String 是否自动追加保证金
1: 自动追加已开启
0: 自动追加未开启
liqui_mode string 强平模式:tier(梯度强平)
can_withdraw string 可划转数量
解释说明

所有持仓/所有账户信息,没有持仓/持币时返回空数组;单个持仓/单个账户信息没有持仓/持币时返回各字段均为默认值

逐仓:

1.账户权益:账户权益=账户余额+逐仓仓位账户余额+所有合约的已实现盈亏+所有合约的未实现盈亏

2.可用:可用余额=账户余额+逐仓仓位账户余额+本合约已实现盈亏- 当前仓位的持仓所需保证金 - 挂单冻结保证金

全仓:

1.账户权益=账户余额+所有合约的已实现盈亏+所有合约的未实现盈亏

2.可用余额=账户余额+所有合约已实现盈亏+所有合约的未实现- 所有仓位持仓所需保证金 - 挂单冻结保证金

返回示例
全仓
{
    "equity": "0.01125076",
    "margin": "0.00312227",
    "realized_pnl": "-0.00007907",
    "unrealized_pnl": "-0.00000002",
    "margin_ratio": "0.23098661",
    "margin_mode": "crossed",
    "total_avail_balance": "0.01132985",
    "margin_frozen": "0.00312227",
    "margin_for_unfilled": "0",
    "liqui_mode": "tier",
    "maint_margin_ratio": "0.005",
    "liqui_fee_rate": "0.0005",
    "can_withdraw": "0.00812849"
}
逐仓
{
    "total_avail_balance": "0.00473265",
    "contracts": [
        {
            "available_qty": "0.00473265",
            "fixed_balance": "0.00004645",
            "instrument_id": "BTC-USD-191018",
            "margin_for_unfilled": "0",
            "margin_frozen": "0",
            "realized_pnl": "-0.00004645",
            "unrealized_pnl": "0"
        },
        {
            "available_qty": "0.00473265",
            "fixed_balance": "0.00655075",
            "instrument_id": "BTC-USD-191227",
            "margin_for_unfilled": "0",
            "margin_frozen": "0.00646337",
            "realized_pnl": "-0.00008738",
            "unrealized_pnl": "-0.0002"
        }
    ],
    "equity": "0.01113638",
    "margin_mode": "fixed",
    "auto_margin": "0",
    "liqui_mode": "tier",
    "can_withdraw": "0.00473265"
}

获取合约币种杠杆倍数

获取合约账户币种杠杆倍数

限速规则:5次/2s
HTTP请求

GET /api/futures/v3/accounts/<currency>/leverage

请求示例

GET /api/futures/v3/accounts/btc/leverage

请求参数
参数名 参数类型 是否必须 描述
currency String 币种,如:btc
返回参数
全仓
全仓参数名 参数类型 描述
margin_mode String 账户类型
全仓:crossed
currency String 币种,如:btc
leverage String 杠杆倍数
逐仓
逐仓参数名 参数类型 描述
margin_mode String 账户类型
逐仓:fixed
instrument_id String 合约ID,如BTC-USD-180213
long_leverage String 多头杠杆倍数
short_leverage String 空头杠杆倍数
解释说明

全仓同一个币种只允许有一种杠杆倍数,逐仓同一个合约同一个方向只能用一种杠杆倍数。

返回示例
1.全仓模式:
{
    "leverage":"10",
    "margin_mode":"crossed",
    "currency":"BTC"
}

2.逐仓模式:
{
    "BTC-USD-191018":{
        "long_leverage":"10",
        "short_leverage":"10"
    },
    "BTC-USD-191227":{
        "long_leverage":"10",
        "short_leverage":"10"
    },
    "margin_mode":"fixed",
    "BTC-USD-191011":{
        "long_leverage":"10",
        "short_leverage":"10"
    }
}

设定合约币种杠杆倍数

设置合约账户币种杠杆倍数。当下单时,系统会按照您设置的杠杆倍数进行下单。

限速规则:5次/2s
HTTP请求

POST /api/futures/v3/accounts/<currency>/leverage

请求示例

POST /api/futures/v3/accounts/btc/leverage{"leverage":"10"}(全仓示例)

POST /api/futures/v3/accounts/btc/leverage{"instrument_id":"BTC-USD-180213","direction":"long","leverage":"10"}(逐仓示例)

请求参数
全仓
全仓参数名 参数类型 是否必须 描述
leverage String 要设定的杠杆倍数,填写1-100的数值
currency String 币种,如:btc
逐仓
逐仓参数名 参数类型 是否必须 描述
currency String 币种,如:btc
instrument_id String 合约ID,如BTC-USD-180213
direction String 开仓方向
long(做多)或short(做空)
leverage String 要设定的杠杆倍数,填写1-100的数值
返回参数
全仓
全仓参数名 参数类型 描述
margin_mode String 账户类型
全仓:crossed
currency String 币种,如:btc
leverage String 已设定的杠杆倍数,1-100的数值
result String 返回设定结果,成功或错误码
逐仓
逐仓参数名 参数类型 描述
margin_mode String 账户类型
逐仓:fixed
instrument_id String 合约ID,如BTC-USD-180213
direction String 开仓方向
long(做多)或short(做空)
leverage String 已设定的杠杆倍数,1-100的数值
result String 返回设定结果,成功或错误码
解释说明

仓位设定:全仓,逐仓

全仓的话:传currency ,传杠杆倍数

逐仓的话:传instrument_id,传方向,传杠杆倍数

全仓同一个币种只允许有一种杠杆倍数,逐仓同一个合约同一个方向只能用一种杠杆倍数。

返回示例
1.全仓模式:
{
    "result": true,
    "leverage": "10",
    "margin_mode": "crossed",
    "currency": "BTC"
}

2.逐仓模式:
{
    "result":"true",
    "margin_mode":"fixed",
    "EOS-USD-190628":{
        "short":"10",
        "long":"10"
    }
}

账单流水查询

列出帐户资产流水。帐户资产流水是指导致帐户余额增加或减少的行为。本接口能查询最近2天的数据。

限速规则:5次/2s
HTTP请求

GET /api/futures/v3/accounts/<currency>/ledger

请求示例

GET /api/futures/v3/accounts/eos/ledger?after=2510946217009854&limit=3

请求参数
参数名 参数类型 是否必须 描述
currency String 币种,如:btc
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的ledger_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的ledger_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条
type String 1.开多
2.开空
3.平多
4.平空
5.手续费
6.转入,
7.转出
8.清算已实现盈亏
13.强平平多
14.强平平空
15.交割平多
16.交割平空
17.清算未实现收益-多头
18.清算未实现收益-空头
20.强减空
21.强减多
返回参数
参数名 参数类型 描述
ledger_id String 账单ID
currency String 币种,如:btc
amount String 变动数量
type String 流水来源
timestamp String 账单创建时间
details String 如果类型是交易产生的,则该details字段将包含order_idinstrument_id
order_id String 订单ID
instrument_id String 合约ID,如BTC-USD-180213
balance String 开仓平仓的张数(开仓为正数,平仓为负数,当typefee时,balance0
流水来源类型 参数类型 描述
transfer String 资金转入/转出
match String 开多/开空/平多/平空
fee String 手续费
settlement String 清算/分摊/多结算/空结算
liquidation String 强平多/强平空/交割平多/交割平空
返回示例
[
    {
        "ledger_id":"2510946217197569",
        "timestamp":"2019-03-20T02:46:38.000Z",
        "amount":"-0.0080819",
        "balance":"0",
        "currency":"EOS",
        "type":"fee",
        "details":{
            "order_id":"2510946213248000",
            "instrument_id":"EOS-USD-190628"
        }
    },
    {
        "ledger_id":"2510946217197568",
        "timestamp":"2019-03-20T02:46:38.000Z",
        "amount":"0",
        "balance":"10",
        "currency":"EOS",
        "type":"match",
        "details":{
            "order_id":"2510946213248000",
            "instrument_id":"EOS-USD-190628"
        }
    },
    {
        "ledger_id":"2508090544914461",
        "timestamp":"2019-03-19T14:40:24.000Z",
        "amount":"-0.00529521",
        "balance":"0",
        "currency":"EOS",
        "type":"fee",
        "details":{
            "order_id":"2506982456445952",
            "instrument_id":"EOS-USD-190628"
        }
    }
]

下单

OKEx合约交易提供了限价单下单模式。只有当您的账户有足够的资金才能下单。一旦下单,您的账户资金将在订单生命周期内被冻结。被冻结的资金以及数量取决于订单指定的类型和参数。

限速规则:40次/2s
HTTP请求

POST /api/futures/v3/order

请求示例

POST /api/futures/v3/order{"client_oid": “12233456”,"order_type”:”1”,"instrument_id":"BTC-USD-180213","type":"1","price":"432.11","size":"2","match_price":"0"}

请求参数
参数名 参数类型 是否必须 描述
client_oid String 由您设置的订单ID来识别您的订单 ,类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符
instrument_id String 合约ID,如BTC-USD-180213
type String 1:开多
2:开空
3:平多
4:平空
order_type String 参数填数字
0:普通委托(order type不填或填0都是普通委托)
1:只做Maker(Post only)
2:全部成交或立即取消(FOK)
3:立即成交并取消剩余(IOC)
price String 委托价格
size String 买入或卖出合约的数量(以张计数)
match_price String 是否以对手价下单(0:不是; 1:是),默认为0,当取值为1时,price字段无效。当以对手价下单,order_type只能选择0(普通委托)
返回参数
参数名 参数类型 描述
order_id String 订单ID,下单失败时,此字段值为-1
client_oid String 由您设置的订单ID来识别您的订单
error_code String 错误码
error_message String 错误信息
result Boolean 调用接口返回结果
解释说明

instrument_id

instrument_id必须是有效的合约ID。合约列表可通过/ instrument接口获取。

client_oid

client_oid的类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符(此功能 2019.2.28 号正式上线) ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单和查询订单时只能撤销或者查询最新的一条数据。

type

下单时,您可以指定订单类型。在您没有持仓时,只能选择开多和开空。您只能对持仓合约进行平仓。

price

price表示买入或卖出每张合约的价格。价格必须是价格步长tick_size的倍数。价格步长tick_size是价格的最小增量,可通过instrument接口获取。

size

size表示买入或卖出合约的张数。数量必须是整数。

match_price

对手价表示你希望以目前对手方的最优价格成交。如果你下的是买单,选择以对手价下单表示你用当前卖一价进行下单。如果你下的是卖单,选择以对手价下单表示你用当前买一价进行下单。

订单生命周期

HTTP请求将在订单被拒绝(资金不足,参数无效等)或下单成功(由匹配引擎接受)时作出响应。一个200响应表示该订单被接收并且进入撮合。进入撮合的订单可以部分或全部立即成交(取决于价格和市场条件)。部分成交的时候将把订单的剩余数量继续进行撮合。完全成交的订单将进入已成交状态。

监听行情数据的用户建议使用client_oid字段以便在接受到的信息中标识对应的数据。

响应

成功接受的订单将被分配一个订单ID。成功接受的订单表示撮合引擎已经接受的订单。

未成交的订单不会过期,并将保持撮合状态,直到被成交或取消。

返回示例
{
    "result":true,
    "error_message":"",
    "error_code":"0",
    "client_oid":"oktfuture8",
    "order_id":"2517062038154240"
}

批量下单

批量进行合约下单操作。每个合约可批量下10个单。

限速规则:20次/2s
HTTP请求

POST /api/futures/v3/orders

请求示例

POST /api/futures/v3/orders{"instrument_id":"ETH-USD-181228","orders_data":[{"order_type”:”1”,"client_oid":"f379a96206fa4b778e1554c6dc969687","type":"1","price":"180.0","size":"1","match_price":"0"}]}

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
orders_data List<String> JSON类型的字符串 例:[{order_type:"0",price:"5",size:"2",type:"1",match_price:"1"},{order_type:"0",price:"2",size:"3",type:"1",match_price:"1"}]
最大下单量为10,当以对手价下单,order_type只能选择0(普通委托) 。
price, size, type, match_price 参数参考future_trade接口中的说明
client_oid String 由您设置的订单ID来识别您的订单 ,类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符
order_type String 参数填数字
0:普通委托(order_type不填或填0都是普通委托)
1:只做Maker(Post only)
2:全部成交或立即取消(FOK)
3:立即成交并取消剩余(IOC)
返回参数
参数名 参数类型 描述
order_info String 订单信息
order_id String 订单ID,下单失败时,此字段值为-1
client_oid String 由您设置的订单ID来识别您的订单
error_code String 错误码,下单成功时为0,下单失败时会显示相应错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
result String 调用接口返回结果
解释说明

client_oid的类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符 ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单和查询订单时只能撤销或者查询最新的一条数据。

只要其中任何一单下单成功,result就会返回true。返回的结果数据和orders_data提交订单数据顺序一致。如果下单失败,则order_id-1error_code是错误码提示,error_message是错误信息。

返回示例
{
    "result":true,
    "order_info":[
        {
            "error_message":"",
            "error_code":"0",
            "client_oid":"oktfuture18",
            "order_id":"2517748155771904"
        },
        {
            "error_message":"",
            "error_code":"0",
            "client_oid":"oktfuture19",
            "order_id":"2517748157541376"
        }
    ]
}

撤销指定订单

撤销之前下的未完成订单。

限速规则:40次/2s
HTTP请求

POST /api/futures/v3/cancel_order/<instrument_id>/<order_id> or <client_oid>

请求示例

POST /api/futures/v3/cancel_order/BTC-USD-180309/1407616797780992

POST /api/futures/v3/cancel_order/BTC-USD-180309/1407616797780992ee

请求参数
参数名 参数类型 是否必须 描述
order_id String 非必填 order_idclient_oid必须且只能选一个填写,订单ID
instrument_id String 合约ID,如BTC-USD-180213
client_oid String 非必填 order_idclient_oid必须且只能选一个填写,由您设置的订单ID来识别您的订单 , 类型为字母(大小写)+数字或者纯字母(大小写)1-32位字符
返回参数
参数名 参数类型 描述
order_id String 订单ID
result String 撤单申请结果
instrument_id String 合约ID
client_oid String 由您设置的订单ID来识别您的订单
解释说明

使用client_oid撤单时,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单时只能撤销最新的一条数据

使用client_oids撤单时返回参数包含order_idsclient_oids, 使用order_ids撤单时返回参数不包含client_oids

order_id是服务器分配的订单ID,而不是用户传的的client_oid

如果订单无法取消(已经成交或已取消),那么返回的报错内容里将显示相应的原因。

返回值是已发起撤销操作的订单ID,不代表这些订单已成功撤销,正在成交中的无法撤销,未成交的可成功撤销。

返回示例
1.用client_oid撤单的返回值:
{
    "result":true,
    "client_oid":"oktfuture10",
    "order_id":"2517514559122432",
    "instrument_id":"EOS-USD-190628"
}

2.用order_id撤单的返回值:
{
    "result":true,
    "order_id":"2517535534836736",
    "instrument_id":"EOS-USD-190628"
}

批量撤销订单

根据指定的order_id撤销某个合约的未完成订单,每次最多可撤10个单。

限速规则:20 次/2s
HTTP请求

POST /api/futures/v3/cancel_batch_orders/<instrument_id>

请求示例

POST /api/futures/v3/cancel_batch_orders/BTC-USD-180309{"order_ids":[ "2517748157541376", "2517748155771904"]}

POST /api/futures/v3/cancel_batch_orders/BTC-USD-180309{"client_oids":[ "oktfuture19","oktfuture18"]}

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 撤销指定合约品种的订单
order_ids List<String> 非必填 order_idclient_oid必须且只能选一个填写,撤销指定的订单ID
client_oids List<String> 非必填 order_idclient_oid必须且只能选一个填写,由您设置的订单ID来识别您的订单, 类型为字母(大小写)+数字或者纯字母(大小写)1-32位字符
返回参数
参数名 参数类型 描述
instrument_id String 撤销指定合约品种的订单
order_ids String 撤销指定的订单ID
client_oids String 由您设置的订单ID来识别您的订单
result String 调用接口返回结果
返回参数

批量撤单时候,要么都是order_id要么都是client_oids,否则会提示错误

使用client_oids批量撤单时,目前只支持一个币对下撤10个client_oids,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单时只能撤销最新的一条数据

order_idsclient_oids 必须且只能选一个填写,使用client_oids撤单时返回参数包含order_idsclient_oids,使用order_ids撤单时返回参数不包含client_oids

返回值是已发起撤销操作的订单ID列表,不代表这些订单已成功撤销,正在成交中的无法撤销,未成交的可成功撤销。

解释说明

无法保证一定会成功撤销,建议用户调用批量撤单接口后,再调用获取订单列表接口确认。

返回示例
1.用client_oids批量撤单的返回值:
{
    "result":true,
    "order_ids":[
        "2517748157541376",
        "2517748155771904"
    ],
    "instrument_id":"EOS-USD-190628",
    "client_oids":[
        "oktfuture19",
        "oktfuture18"
    ]
}

2.用order_ids批量撤单的返回值:
{
    "result":true,
    "order_ids":[
        "2517748157541376",
        "2517748155771904"
    ],
    "instrument_id":"EOS-USD-190628"
}

获取订单列表

列出您当前所有的订单信息。本接口能查询最近7天的数据。这个请求支持分页,并且按委托时间倒序排序和存储,最新的排在最前面。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/orders/<instrument_id>

请求示例

GET /api/futures/v3/orders/BTC-USD-190628?state=2&after=2517062044057601&limit=2

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
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条
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
client_oid String 用户设置的订单ID
size String 委托数量
timestamp Date 委托时间
filled_qty String 成交数量
fee String 手续费
order_id String 订单ID
price String 委托价格
price_avg String 成交均价
type String 订单类型
1:开多
2:开空
3:平多
4:平空
contract_val String 合约面值
leverage String 杠杆倍数,1-100的数值
order_type String 0:普通委托
1:只做Maker(Post only)
2:全部成交或立即取消(FOK)
3:立即成交并取消剩余(IOC)
pnl String 收益
state String 订单状态
-2:失败
-1:撤单成功
0:等待成交
1:部分成交
2:完全成交
3:下单中
4:撤单中
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换state

client_oid的类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符 ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单和查询订单时只能撤销或者查询最新的一条数据。

如果订单在其生命周期内没有任何成交,其记录可能被清除。这表示订单详细信息将不可用本接口来获取。

未成交的订单可能会根据市场情况在你发起请求和服务器响应之间改变状态。

返回示例
{
    "result": true,
    "order_info": [
        {
            "instrument_id": "BTC-USD-191227",
            "size": "2",
            "timestamp": "2019-09-25T08:42:34.000Z",
            "filled_qty": "2",
            "fee": "-0.0000119",
            "order_id": "3582522429644800",
            "price": "8160.55",
            "price_avg": "8402.36",
            "status": "2",
            "state": "2",
            "type": "3",
            "contract_val": "100",
            "leverage": "10",
            "client_oid": "",
            "pnl": "-0.00011292",
            "order_type": "0"
        },
        {
            "instrument_id": "BTC-USD-191227",
            "size": "2",
            "timestamp": "2019-09-25T07:58:42.000Z",
            "filled_qty": "2",
            "fee": "-0.00001183",
            "order_id": "3582349944101888",
            "price": "8454.42",
            "price_avg": "8454.42",
            "status": "2",
            "state": "2",
            "type": "1",
            "contract_val": "100",
            "leverage": "10",
            "client_oid": "",
            "pnl": "0",
            "order_type": "0"
        }
    ]
}

获取订单信息

通过订单ID获取单个订单信息。已撤销的未成交单只保留2个小时。

限速规则:40次/2s
HTTP请求

GET /api/futures/v3/orders/<instrument_id>/<order_id>

GET /api/futures/v3/orders/<instrument_id>/<client_oid>

请求示例

GET /api/futures/v3/orders/BTC-USD-180213/888845120785408

GET /api/futures/v3/orders/BTC-USD-180213/888845120785408ee

请求参数
参数名 参数类型 是否必须 描述
order_id String 订单ID order_idclient_oid必须且只能选一个填写
instrument_id String 合约ID,如BTC-USD-180213
client_oid String order_idclient_oid必须且只能选一个填写 .由您设置的订单ID来识别您的订单 , 类型为字母(大小写)+数字或者纯字母(大小写) 1-32位字符
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
client_oid String 由您设置的订单ID来识别您的订单
size String 委托数量
timestamp String 委托时间
filled_qty String 成交数量
fee String 手续费
order_id String 订单ID
price String 委托价格
price_avg String 成交均价
type String 订单类型
1:开多
2:开空
3:平多
4:平空
contract_val String 合约面值
leverage String 杠杆倍数,1-100的数值
order_type String 0:普通委托
1:只做Maker(Post only)
2:全部成交或立即取消(FOK)
3:立即成交并取消剩余(IOC)
pnl String 收益
state String 订单状态
-2:失败
-1:撤单成功
0:等待成交
1:部分成交
2:完全成交
3:下单中
4:撤单中
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换state

client_oid的类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符 ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单和查询订单时只能撤销或者查询最新的一条数据。

本接口只能查询最近三个月的已成交和已撤销订单信息。

如果订单在其生命周期内没有任何成交,其记录可能被清除,则响应可能因为没有相应的匹配而返回状态码404。

未成交的订单可能会根据市场情况在你发起请求和服务器响应之间改变状态。

返回示例
{
    "instrument_id": "BTC-USD-191227",
    "size": "2",
    "timestamp": "2019-09-25T08:42:34.000Z",
    "filled_qty": "2",
    "fee": "-0.0000119",
    "order_id": "3582522429644800",
    "price": "8160.55",
    "price_avg": "8402.36",
    "status": "2",
    "state": "2",
    "type": "3",
    "contract_val": "100",
    "leverage": "10",
    "client_oid": "",
    "pnl": "-0.00011292",
    "order_type": "0"
}

获取成交明细

获取最近的成交明细列表,本接口能查询最近7天的数据。

限速规则:20 次/2s
HTTP请求

GET /api/futures/v3/fills

请求示例

GET /api/futures/v3/fills?order_id=123123&instrument_id=BTC-USD-180309&after=2517062044057601&limit=50

请求参数
参数名 参数类型 是否必须 描述
order_id String 订单ID,不填写order_id,返回当前instrument_id下的所有订单成交明细
instrument_id String 合约ID,如BTC-USD-180213
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的trade_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的trade_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条
返回参数
参数名 参数类型 描述
trade_id String 账单ID
instrument_id String 合约ID,如BTC-USD-180213
price String 价格
order_qty String 数量
order_id String 订单ID
created_at String 订单成交时间
exec_type String 流动性方向(TM
fee String 手续费
side String 订单方向(buysell
解释说明

手续费

fee字段:负数的fee表示平台收取的手续费,正数的fee表示表示平台向达到指定lv交易等级的用户支付的挂单奖励(返佣)

流动性

exec_type字段表示该账单是maker还是taker产生的。M表示Maker,T表示Taker。

分页

返回账单列表的trade_id按降序排列,从最大trade_id到最小trade_id。OK-after都会有这样的第一笔trade_id,以便将来的请求使用OK-after参数将获取一个更大的trade_id(新的账单)。

返回示例
[
    {
        "trade_id":"2517062044057601",
        "instrument_id":"EOS-USD-190628",
        "price":"3.692",
        "order_qty":"1",
        "order_id":"251706627555816789240",
        "created_at":"2019-03-21T04:41:58.0Z",
        "exec_type":"T",
        "fee":"-0.00081257",
        "side":"buy"
    }
]

设置合约币种账户模式

设置合约币种账户模式,注意当前仓位有挂单时禁止切换账户模式。

限速规则:5次/2s
HTTP请求

POST /api/futures/v3/accounts/margin_mode

请求示例

POST /api/futures/v3/accounts/margin_mode{"currency":"btc","margin_mode":"crossed"}

请求参数
参数名 参数类型 是否必须 描述
currency String 币种,如:btc
margin_mode String 账户模式
crossed:全仓
fixed:逐仓
返回参数
参数名 参数类型 描述
currency String 币种,如:btc
margin_mode String 账户模式
crossed:全仓
fixed:逐仓
result String 返回设定结果
返回示例
{
    "result":true,
    "currency":"btc",
    "margin_mode":"crossed"
}

市价全平

市价全平接口,其中BTC单次最多可以平999张,其他币种单次最多可以平9999张。

限速规则:5次/2s
HTTP请求

POST /api/futures/v3/close_position

请求示例

POST /api/futures/v3/close_position{"instrument_id":"BTC-USD-180213","direction":"long"}

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
direction String 平仓方向
long:平多
short:平空
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
direction String 平仓方向
long:平多
short:平空
error_code String 错误码,下单成功时为0,下单失败时会显示相应错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
result String 调用接口返回结果
返回示例
{
    "result":true,
    "error_message":"",
    "error_code":0,
    "instrument_id":"BTC-USD-180213",
    "direction":"long"
}

撤销所有平仓挂单

此接口,仅支持撤销平仓的所有挂单。不包括开仓的挂单。

限速规则:5次/2s
HTTP请求

POST /api/futures/v3/cancel_all

请求示例

POST /api/futures/v3/cancel_all{"instrument_id":"BTC-USD-180213","direction":"long"}

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
direction String 平仓方向
long:平多
short:平空
返回参数
参数名 参数类型 描述
instrument_id String 是 合约ID,如BTC-USD-180213
direction String 是 平仓方向
long:平多
short:平空
error_code String 错误码,下单成功时为0,下单失败时会显示相应错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
result String 调用接口返回结果
返回示例
{
    "result":true,
    "error_message":"",
    "error_code":0,
    "instrument_id":"BTC-USD-180213",
    "direction":"long"
}

获取合约挂单冻结数量

获取合约挂单冻结的数量.

限速规则:5次/2s
HTTP请求

GET /api/futures/v3/accounts/<instrument_id>/holds

请求示例

GET /api/futures/v3/accounts/BTC-USD-181228/holds

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
amount String 冻结数量
timestamp String 查询时间
返回示例
{
    "amount":"0.3073",
    "instrument_id":"EOS-USD-190328",
    "timestamp":"2019-03-26T03:19:48.035Z"
}

委托策略下单

委托策略下单

提供止盈止损、跟踪委托、冰山委托和时间加权委托策略

限速规则:40次/2s
HTTP请求

POST /api/futures/v3/order_algo

请求示例

POST /api/futures/v3/order_algo{"instrument_id":"BTC-USD-190328","type":"1","trigger_price":"432.11","order_type":"1",“algo_price“:"341.99","size":"2"}(止盈止损)

请求参数(通用)
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-190328
type String 1:开多
2:开空
3:平多
4:平空
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
size String 委托总数(以张计数),填写值1\<=X\<=1000000的整数
止盈止损参数 (最多同时存在10单)
参数名 参数类型 是否必须 描述
trigger_price String 触发价格,填写值0\<X\<=1000000
algo_price String 委托价格,填写值0\<X\<=1000000
跟踪委托参数 (最多同时存在10单)
参数名 参数类型 是否必须 描述
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 单笔均值,填写2-1000的整数(永续2-500的整数)
price_limit 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 单笔上限,填写值10\<=X\<=2000(永续2-500的整数)
price_limit String 价格限制,填写值0\<X\<=1000000
time_interval String 委托间隔,填写值5\<=X\<=120

返回参数

参数名 参数类型 描述
result String 调用接口返回结果
instrument_id String 合约ID,如BTC-USD-190328
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
algo_id String 订单ID,下单失败时,此字段值为-1
error_code String 错误码,下单成功时为0,下单失败时会显示相应错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
返回示例
{
    "result": true,
    "algo_id": "3003646",
    "error_message": "",
    "error_code": "0",
    "instrument_id": "EOS-USD-191227",
    "order_type": "1"
}

委托策略撤单

委托策略撤单

根据指定的algo_id撤销某个合约的未完成订单,每次最多可撤6(冰山/时间)/10(计划/跟踪)个。

限速规则:20 次/2s
HTTP请求

POST /api/futures/v3/cancel_algos

请求示例

单个撤单:POST /api/futures/v3/cancel_algos{“instrument_id":"BTC-USD-190328","order_type":“1”,"algo_ids":[“198273485”]}

批量撤单:POST /api/futures/v3/cancel_algos{“instrument_id":"BTC-USD-190328","order_type":“1”,"algo_ids":["198273485","198273486"]}

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 撤销指定的合约品种
algo_ids List<String> 撤销指定的委托单ID
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
返回参数
参数名 参数类型 描述
instrument_id String 撤销指定的合约品种
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
algo_ids String 撤销指定的委托单ID
result String 调用接口返回结果

返回参数

返回值是已发起撤销操作的委托单ID,不代表这些委托单已成功撤销,正在成交中的无法撤销,未成交的可成功撤销。

解释说明

无法保证一定会成功撤销,建议用户调用撤单接口后,再调用获取委托单列表接口确认。

返回示例
{
    "result": true,
    "error_message": "",
    "algo_id": "3003646",
    "instrument_id": "EOS-USD-191227",
    "order_type": "1"
}

获取委托单列表

获取委托单列表

列出您当前所有的订单信息。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/order_algo/<instrument_id>

请求示例

GET /api/futures/v3/order_algo/BTC-USD-190328?order_type=1&status=2

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-190328
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
status String 见描述 statusalgo_id必填且只能填其一】
订单状态
1:待生效
2:已生效
3:已撤销
4:部分生效
5:暂停生效
6:委托失败
【只有冰山和加权有45状态】
algo_id String 见描述 statusalgo_id必填且只能填其一】
查询指定的委托单ID
before string 请求此id之后(更新的数据)的分页内容
after string 请求此id之前(更旧的数据)的分页内容
limit string 分页返回的结果集数量,默认为100,最大为100
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-190328
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
timestamp String 委托时间
algo_ids String 委托单ID
status String 订单状态
1: 待生效
2: 已生效
3: 已撤销
4: 部分生效
5: 暂停生效
type String 订单类型
1:开多
2:开空
3:平多
4:平空
leverage String 杠杆倍数
size String 委托数量(以张计数),填写值1\<=X\<=1000000的整数

止盈止损

参数名 参数类型 描述
trigger_price String 触发价格,填写值0\<X
algo_price String 委托价格,填写值0\<X\<=1000000
real_amount String 实际成交数量

跟踪委托

参数名 参数类型 描述
callback_rate String 回调幅度,填写值0.001(0.1%)\<=X\<=0.05(5%)
trigger_price String 激活价格 ,填写值0\<X\<=1000000
real_amount String 实际委托数量

冰山委托

参数名 参数类型 描述
algo_variance String 委托深度,填写值0\<=X\<=0.01(1%)
avg_amount String 单笔均值,填写2-500的整数(永续2-500的整数)
price_limit 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的整数)
price_limit String 价格限制,填写值0\<X\<=1000000
time_interval String 委托间隔,填写值5\<=X\<=120
deal_value String 已委托量
返回示例
[
    {
        "algo_ids": "3003719",
        "algo_price": "2",
        "instrument_id": "EOS-USD-191227",
        "leverage": "10",
        "order_type": "1",
        "real_amount": "0",
        "size": "1",
        "status": "1",
        "timestamp": "2019-10-11T07:43:41.000Z",
        "trigger_price": "2",
        "type": "1"
    },
    {
        "algo_ids": "3003718",
        "algo_price": "2",
        "instrument_id": "EOS-USD-191227",
        "leverage": "10",
        "order_type": "1",
        "real_amount": "0",
        "size": "1",
        "status": "1",
        "timestamp": "2019-10-11T07:43:39.000Z",
        "trigger_price": "2",
        "type": "1"
    }
]

公共-获取合约信息

获取可用合约的列表,查询各合约的交易限制和价格步长等信息。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments

请求示例

GET /api/futures/v3/instruments

返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
underlying_index String 交易货币币种,如:BTC-USD中的BTC
quote_currency String 计价货币币种,如:BTC-USD中的USD
contract_val String 合约面值(美元)
listing String 上线日期
delivery String 交割日期
tick_size String 下单价格精度
trade_increment String 下单数量精度
alias String 本周 this_week
次周 next_week
季度 quarter
解释说明

tick_size(价格精度)是指下单价格的最小增量,委托价格必须是tick_size的倍数。例如,当tick_size0.01,委托价格传入0.022将被系统按截尾法修正为0.02

返回示例
[
    {
        "instrument_id":"BTC-USD-190322",
        "underlying_index":"BTC",
        "quote_currency":"USD",
        "tick_size":"0.01",
        "contract_val":"100",
        "listing":"2019-03-08",
        "delivery":"2019-03-22",
        "trade_increment":"1",
        "alias":"this_week"
    },
    {
        "instrument_id":"BTC-USD-190329",
        "underlying_index":"BTC",
        "quote_currency":"USD",
        "tick_size":"0.01",
        "contract_val":"100",
        "listing":"2018-12-14",
        "delivery":"2019-03-29",
        "trade_increment":"1",
        "alias":"next_week"
    },
    {
        "instrument_id":"BTC-USD-190628",
        "underlying_index":"BTC",
        "quote_currency":"USD",
        "tick_size":"0.01",
        "contract_val":"100",
        "listing":"2019-03-15",
        "delivery":"2019-06-28",
        "trade_increment":"1",
        "alias":"quarter"
    }

   ...

]

公共-获取深度数据

获取合约的深度列表。这个请求不支持分页,一个请求返回整个深度列表。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/book

请求示例

GET /api/futures/v3/instruments/BTC-USD-180309/book?size=50

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
size String 返回深度数量,最大值可传200,即买卖深度共400条
depth String 按价格合并深度,例如:0.10.001
返回参数
参数名 参数类型 描述
asks List<String> 卖方深度
bids List<String> 买方深度
timestamp String 系统时间戳

返回值数组说明

["411.8", "10", "1", "4"] 411.8为深度价格,10为此价格的合约张数,1为此价格的强平单个数,4为此价格的订单个数,timestamp为深度生成时间戳。

解释说明

size不传时,返回1条;size0时,返回0条;size最大200,传大于200的数时,返回200条。

按价格合并深度是指每个价格区间将仅返回一个数量,就像在该价格区间上只有一个订单。

返回示例
{
    "bids":[
        [
            "3.596",
            "5125",
            "0",
            "15"
        ],
        [
            "3.595",
            "553",
            "0",
            "14"
        ]
    ],
    "asks":[
        [
            "3.597",
            "3181",
            "0",
            "18"
        ],
        [
            "3.598",
            "13912",
            "0",
            "31"
        ]
    ],
    "timestamp":"2019-03-22T01:59:34.707Z"
}

公共-获取全部ticker信息

获取平台全部合约的最新成交价、买一价、卖一价和24小时交易量的快照信息。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/ticker

请求示例

GET /api/futures/v3/instruments/ticker

返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
last String 最新成交价
best_ask String 卖一价
best_bid String 买一价
high_24h String 24小时最高价
low_24h String 24小时最低价
volume_24h String 24小时成交量,按张数统计
timestamp String 系统时间戳
解释说明

最高价、最低价和成交量都是按最近24小时为维度统计的。

返回示例
[
    {
        "instrument_id":"BSV-USD-190329",
        "last":"65",
        "best_bid":"65",
        "best_ask":"65.03",
        "high_24h":"68.59",
        "low_24h":"63.72",
        "volume_24h":"62944",
        "timestamp":"2019-03-22T02:14:55.716Z"
    },
    {
        "instrument_id":"BSV-USD-190628",
        "last":"67.05",
        "best_bid":"67.03",
        "best_ask":"67.05",
        "high_24h":"69.84",
        "low_24h":"65.28",
        "volume_24h":"221458",
        "timestamp":"2019-03-22T02:14:55.716Z"
    },
    {
        "instrument_id":"EOS-USD-190628",
        "last":"3.601",
        "best_bid":"3.6",
        "best_ask":"3.601",
        "high_24h":"3.73",
        "low_24h":"3.511",
        "volume_24h":"29673717",
        "timestamp":"2019-03-22T02:14:55.716Z"
    }

]

公共-获取某个ticker信息

获取合约的最新成交价、买一价、卖一价和24小时交易量的快照信息。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/ticker

请求示例

GET /api/futures/v3/instruments/BTC-USD-180309/ticker

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
last String 最新成交价
best_ask String 卖一价
best_bid String 买一价
high_24h String 24小时最高价
low_24h String 24小时最低价
volume_24h String 24小时成交量,按张数统计
timestamp String 系统时间戳
解释说明

最高价、最低价和成交量都是按最近24小时为维度统计的。

返回示例
{
    "instrument_id":"EOS-USD-190628",
    "last":"3.708",
    "best_bid":"3.707",
    "best_ask":"3.708",
    "high_24h":"3.799",
    "low_24h":"3.494",
    "volume_24h":"24884595",
    "timestamp":"2019-03-21T03:15:50.144Z"
}

公共-获取成交数据

获取合约最新的300条成交列表。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/trades

请求示例

GET /api/futures/v3/instruments/BTC-USD-180309/trades?after=2517062044057601&limit=2

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的trade_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的trade_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条
返回参数
参数名 参数类型 描述
timestamp String 成交时间
trade_id String 成交ID
price String 成交价格
qty String 成交数量
side String 成交方向
解释说明

成交方向side是指Taker订单的下单方向,Taker表示主动与深度列表中挂单进行成交。buy表示价格上涨,因为Taker是买单吃掉深度,所以价格将上行。相反,sell表示价格下跌。

trade_id是记录成交信息的递增ID,可能不完整。

返回示例
[
    [
        {
            "trade_id":"2522253054345222",
            "side":"sell",
            "price":"3.625",
            "qty":"24",
            "timestamp":"2019-03-22T02:42:07.323Z"
        },
        {
            "trade_id":"2522252973080580",
            "side":"buy",
            "price":"3.626",
            "qty":"6",
            "timestamp":"2019-03-22T02:42:06.081Z"
        },
        {
            "trade_id":"2522252969410561",
            "side":"buy",
            "price":"3.626",
            "qty":"6",
            "timestamp":"2019-03-22T02:42:06.026Z"
        }
    ],
    {

    }
]

公共-获取K线数据

获取合约的K线数据。K线数据按请求的粒度分组返回,k线数据最多可获取最近1440条。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/candles

请求示例

GET /api/futures/v3/instruments/EOS-USD-190628/candles?start=2019-03-18T02:31:00Z&end=2019-03-20T02:55:00Z&granularity=60

(查询EOS-USD-180309的2019年3月18日02点31分到2019年3月20日02点55分的1分钟K线数据)

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
start String 开始时间(ISO UTC标准,例如:2018-06-20T02:31:00Z
end String 结束时间(ISO UTC标准,例如:2018-06-20T02:31:00Z
granularity String 时间粒度,以秒为单位,默认值60。如[60/180/300/900/1800/3600/7200/14400/21600/43200/86400/604800],详见下解释说明
返回参数
参数名 参数类型 描述
timestamp String 开始时间
open String 开盘价格
high String 最高价格
low String 最低价格
close String 收盘价格
volume String 交易量(张)
currency_volume String 按币种折算的交易量
解释说明

如果用户没有提供开始时间或结束时间中的任一字段,则两个字段都将被忽略。未提供开始时间和结束时间的请求,则系统按时间粒度返回最近的300条数据。

时间粒度granularity必须是[60 180 300 900 1800 3600 7200 14400 21600 43200 86400 604800]中的任一值,否则请求将被拒绝。这些值分别对应的是[1min 3min 5min 15min 30min 1hour 2hour 4hour 6hour 12hour 1day 1week]的时间段。

K线数据可能不完整。

单次请求的最大数据量是300。如果您选择的开始/结束时间和时间粒度导致超过单次请求的最大数据量,您的请求将只会返回300个数据。如果您希望在更大的时间范围内获取足够精细的数据,则需要使用多个开始/结束范围进行多次请求。

返回值分别为[timestamp,open,high,low,close,volume,currency_volume]

返回示例
[
    [
        "2019-03-20T16:00:00.000Z",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "22698348.04828491"
    ],
    [
        "2019-03-19T16:00:00.000Z",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "67632347.24399722"
    ],
    [
        "2019-03-18T16:00:00.000Z",
        "3.729",
        "3.78",
        "3.698",
        "3.731",
        "17545741",
        "46945274.21772249"
    ]
]

公共-获取指数信息

获取币种指数。此接口为公共接口,不需要身份验证。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/index

请求示例

GET /api/futures/v3/instruments/EOS-USD-190628/index

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 指数币对,如BTC-USD-190628
返回参数
参数名 参数类型 描述
instrument_id String 指数币对,如BTC-USD-190628
index String 指数价格
timestamp String 系统时间戳
解释说明

指数币对"-"后面的币种表示指数价格的计价单位。

返回示例
{
    "instrument_id":"EOS-USD-190628",
    "index":"3.59125725275",
    "timestamp":"2019-03-22T05:18:05.756Z"
}

公共-获取法币汇率

获取法币汇率。此接口为公共接口,不需要身份验证。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/rate

请求示例

GET /api/futures/v3/rate

返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如USD_CNY
rate String 汇率
timestamp String 系统时间戳
返回示例
{
    "instrument_id":"USD_CNY",
    "rate":"6.701",
    "timestamp":"2019-03-22T05:08:44.323Z"
}

公共-获取预估交割价

获取合约预估交割价。交割预估价只有交割前一小时才有返回值。此接口为公共接口,不需要身份验证。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/estimated_price

请求示例

GET /api/futures/v3/instruments/BTC-USD-180309/estimated_price

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
settlement_price String 预估交割价
timestamp String 系统时间戳
返回示例
{
    "instrument_id":"EOS-USD-181026",
    "settlement_price":"0",
    "timestamp":"2018-10-23T10:07:44.095Z"
}

公共-获取平台总持仓量

获取合约整个平台的总持仓量。此接口为公共接口,不需要身份验证。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/open_interest

请求示例

GET /api/futures/v3/instruments/BTC-USD-180309/open_interest

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
返回参数
参数名 描述
instrument_id String 合约ID,如BTC-USD-180213
amount String 总持仓量
timestamp String 系统时间戳
返回示例
{
    "instrument_id":"EOS-USD-190628",
    "amount":"5311831",
    "timestamp":"2019-03-22T05:56:06.726Z"
}

公共-获取当前限价

获取合约当前交易的最高买价和最低卖价。此接口为公共接口,不需要身份验证。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/price_limit

请求示例

GET /api/futures/v3/instruments/BTC-USD-180309/price_limit

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
highest String 最高买价
lowest String 最低卖价
timestamp String 系统时间戳
返回示例
{
    "instrument_id":"EOS-USD-190628",
    "highest":"3.707",
    "lowest":"3.491",
    "timestamp":"2019-03-22T06:05:08.502Z"
}

公共-获取标记价格

获取合约标记价格。此接口为公共接口,不需要身份验证。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/mark_price

请求示例

GET /api/futures/v3/instruments/BTC-USD-180309/mark_price

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
mark_price String 指定合约品种的标记价格
timestamp String 返回请求时间
解释说明

为了防止个别用户恶意操控市场导致合约价格波动剧烈,我们根据现货指数和合理基差设定标记价格。

返回示例
{
    "mark_price":"3.591",
    "instrument_id":"EOS-USD-190628",
    "timestamp":"2019-03-22T06:28:53.208Z"
}

公共-获取强平单

获取合约强平单,此接口为公共接口,不需要身份验证。

限速规则:20次/2s
HTTP请求

GET /api/futures/v3/instruments/<instrument_id>/liquidation

请求示例

GET /api/futures/v3/instruments/BTC-USD-180309/liquidation?status=0&limit=50

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-180213
status String 状态
0:最近7天未成交
1:最近7天已成交
limit String 分页返回的结果集数量,默认为100,最大为100,按时间倒序排列,越晚的在前面
from String 请求此id之前(更旧的数据)的分页内容,例如 2
to String 请求此id之后(更新的数据)的分页内容 例如 3
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-180213
size String 数量
created_at Date 强平单的委托时间
loss String 穿仓用户亏损
price String 订单价格
type String 订单类型
3:平多
4:平空
返回示例
[
    {
        "loss":"0.0",
        "size":"945",
        "price":"5.623",
        "created_at":"2018-10-21T01:20:18.0Z",
        "instrument_id":"EOS-USD-181026",
        "type":"1"
    },
    {
        "loss":"0",
        "size":"37",
        "price":"5.623",
        "created_at":"2018-10-21T01:20:18.0Z",
        "instrument_id":"EOS-USD-181026",
        "type":"1"
    }
]

永续合约API

永续合约交易的行情信息,账户信息,订单操作,订单查询,账单明细查询。

所有合约持仓信息

获取账户所有合约的持仓信息。请求此接口,会在数据库遍历所有币对下的持仓数据,有大量的性能消耗,请求频率较低。建议用户传合约ID获取持仓信息。

限速规则:1次/10s
HTTP请求

GET /api/swap/v3/position

请求示例

GET /api/swap/v3/position

返回参数

全仓

全仓参数名 参数类型 描述
margin_mode String 仓位模式:全仓crossed
liquidation_price String 预估强平价
position String 持仓数量
avail_position String 可平数量
margin String 保证金
avg_cost String 开仓平均价
settlement_price String 结算基准价
instrument_id String 合约名称
leverage String 杠杆
realized_pnl String 已实现盈亏
side String 方向
timestamp String 创建时间
maint_margin_ratio String 维持保证金率
settled_pnl String 已结算收益
last String 最新成交价

逐仓

逐仓参数名 参数类型 描述
margin_mode String 仓位模式:逐仓fixed
liquidation_price String 预估强平价
position String 持仓数量
avail_position String 可平数量
margin String 保证金
avg_cost String 开仓平均价
settlement_price String 结算基准价
instrument_id String 合约名称
leverage String 杠杆
realized_pnl String 已实现盈亏
side String 方向
timestamp String 创建时间
maint_margin_ratio String 维持保证金率
settled_pnl String 已结算收益
last String 最新成交价
返回示例
[
    {
        "margin_mode": "fixed",
        "timestamp": "2019-09-27T03:47:37.230Z",
        "holding": [
            {
                "avail_position": "20",
                "avg_cost": "8025.0",
                "instrument_id": "BTC-USD-SWAP",
                "last": "8099.8",
                "leverage": "15.00",
                "liquidation_price": "7002.6",
                "maint_margin_ratio": "0.0050",
                "margin": "0.0454",
                "position": "20",
                "realized_pnl": "-0.0001",
                "settled_pnl": "0.0076",
                "settlement_price": "8279.2",
                "side": "long",
                "timestamp": "2019-09-27T03:47:37.230Z"
            }
        ]
    },
    {
        "margin_mode": "crossed",
        "timestamp": "2019-09-27T03:49:02.018Z",
        "holding": [
            {
                "avail_position": "3",
                "avg_cost": "59.49",
                "instrument_id": "LTC-USD-SWAP",
                "last": "55.79",
                "leverage": "10.00",
                "liquidation_price": "4.37",
                "maint_margin_ratio": "0.0100",
                "margin": "0.0537",
                "position": "3",
                "realized_pnl": "0.0000",
                "settled_pnl": "-0.0330",
                "settlement_price": "55.84",
                "side": "long",
                "timestamp": "2019-09-27T03:49:02.018Z"
            },
        ] 
    }
]

单个合约持仓信息

获取某个合约的持仓信息

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/<instrument_id>/position

请求示例

GET /api/swap/v3/BTC-USD-SWAP/position

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
返回参数

全仓

全仓参数名 参数类型 描述
margin_mode String 仓位模式:全仓crossed
liquidation_price String 预估强平价
position String 持仓数量
avail_position String 可平数量
margin String 保证金
avg_cost String 开仓平均价
settlement_price String 结算基准价
instrument_id String 合约名称
leverage String 杠杆
realized_pnl String 已实现盈亏
side String 方向
timestamp String 最近一次加减仓的更新时间
maint_margin_ratio String 维持保证金率
settled_pnl String 已结算收益
last String 最新成交价

逐仓

逐仓参数名 参数类型 描述
margin_mode String 仓位模式:逐仓fixed
liquidation_price String 预估强平价
position String 持仓数量
avail_position String 可平数量
margin String 保证金
avg_cost String 开仓平均价
settlement_price String 结算基准价
instrument_id String 合约名称
leverage String 杠杆
realized_pnl String 已实现盈亏
side String 方向
timestamp String 最近一次加减仓的更新时间
maint_margin_ratio String 维持保证金率
settled_pnl String 已结算收益
last String 最新成交价
返回示例
{
    "margin_mode": "fixed",
    "timestamp": "2019-09-27T03:47:37.230Z",
    "holding": [
        {
            "avail_position": "20",
            "avg_cost": "8025.0",
            "instrument_id": "BTC-USD-SWAP",
            "last": "8113.1",
            "leverage": "15.00",
            "liquidation_price": "7002.6",
            "maint_margin_ratio": "0.0050",
            "margin": "0.0454",
            "position": "20",
            "realized_pnl": "-0.0001",
            "settled_pnl": "0.0076",
            "settlement_price": "8279.2",
            "side": "long",
            "timestamp": "2019-09-27T03:47:37.230Z"
        }
    ]
}

{
    "margin_mode": "crossed",
    "timestamp": "2019-09-27T03:49:02.018Z",
    "holding": [
        {
            "avail_position": "3",
            "avg_cost": "59.49",
            "instrument_id": "LTC-USD-SWAP",
            "last": "55.98",
            "leverage": "10.00",
            "liquidation_price": "4.37",
            "maint_margin_ratio": "0.0100",
            "margin": "0.0536",
            "position": "3",
            "realized_pnl": "0.0000",
            "settled_pnl": "-0.0330",
            "settlement_price": "55.84",
            "side": "long",
            "timestamp": "2019-09-27T03:49:02.018Z"
        },
    ]
}

所有币种合约账户信息

获取所有币种合约的账户信息,当用户没有持仓时,保证金率为10000

限速规则:1次/10s
HTTP请求

GET /api/swap/v3/accounts

请求示例

GET /api/swap/v3/accounts

返回参数
参数名 参数类型 描述
equity String 账户权益(账户动态权益)
total_avail_balance String 账户余额(账户静态权益)
fixed_balance String 逐仓账户余额
margin String 已用保证金
realized_pnl String 已实现盈亏
unrealized_pnl String 未实现盈亏
margin_ratio String 保证金率
instrument_id String 合约名称
margin_frozen String 开仓冻结保证金
timestamp String 创建时间
margin_mode String 仓位模式
全仓:crossed
逐仓:fixed
maint_margin_ratio String 维持保证金率
解释说明

所有持仓/所有账户信息,没有持仓/持币时返回空数组;单个持仓/单个账户信息没有持仓/持币时返回各字段均为默认值;

逐仓:

账户权益:账户权益=账户余额+逐仓仓位账户余额+所有合约的已实现盈亏+所有合约的未实现盈亏

全仓:

账户权益=账户余额+所有合约的已实现盈亏+所有合约的未实现盈亏

返回示例
{
    "info": [
        {
            "equity": "0.0446",
            "fixed_balance": "0.0461",
            "instrument_id": "BTC-USD-SWAP",
            "maint_margin_ratio": "0.0000",
            "margin": "0.0454",
            "margin_frozen": "0.0000",
            "margin_mode": "fixed",
            "margin_ratio": "0.0000",
            "realized_pnl": "-0.0001",
            "timestamp": "2019-09-27T03:47:37.230Z",
            "total_avail_balance": "0.0033",
            "unrealized_pnl": "-0.0049"
        },
        {
            "equity": "0.1371",
            "fixed_balance": "0.0000",
            "instrument_id": "LTC-USD-SWAP",
            "maint_margin_ratio": "0.0100",
            "margin": "0.1071",
            "margin_frozen": "0.0000",
            "margin_mode": "crossed",
            "margin_ratio": "0.1280",
            "realized_pnl": "0.0000",
            "timestamp": "2019-09-27T03:49:02.018Z",
            "total_avail_balance": "0.1371",
            "unrealized_pnl": "0.0000"
        },
        {
            "equity": "0.1124",
            "fixed_balance": "0.0000",
            "instrument_id": "EOS-USD-SWAP",
            "maint_margin_ratio": "0.0100",
            "margin": "0.1367",
            "margin_frozen": "0.0000",
            "margin_mode": "crossed",
            "margin_ratio": "0.0164",
            "realized_pnl": "0.0000",
            "timestamp": "2019-08-27T02:05:29.651Z",
            "total_avail_balance": "0.1124",
            "unrealized_pnl": "0.0000"
        }
    ]
}

单个币种合约账户信息

获取单个币种合约的账户信息,当用户没有持仓时,保证金率为10000

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/<instrument_id>/accounts

请求示例

GET /api/swap/v3/BTC-USD-SWAP/accounts

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
返回参数
参数名 参数类型 描述
equity String 账户权益(账户动态权益)
fixed_balance String 逐仓账户余额
total_avail_balance String 账户余额(账户静态权益)
margin String 已用保证金
realized_pnl String 已实现盈亏
unrealized_pnl String 未实现盈亏
margin_ratio String 保证金率
instrument_id String 合约名称
margin_frozen String 开仓冻结保证金
timestamp String 创建时间
margin_mode String 仓位模式
全仓:crossed
逐仓:fixed
maint_margin_ratio String 维持保证金率
解释说明

所有持仓/所有账户信息,没有持仓/持币时返回空数组;单个持仓/单个账户信息没有持仓/持币时返回各字段均为默认值

逐仓:

账户权益:账户权益=账户余额+逐仓仓位账户余额+所有合约的已实现盈亏+所有合约的未实现盈亏

全仓:

账户权益=账户余额+所有合约的已实现盈亏+所有合约的未实现盈亏

返回示例
{
    "info": {
        "equity": "0.0444",
        "fixed_balance": "0.0461",
        "instrument_id": "BTC-USD-SWAP",
        "maint_margin_ratio": "0.0000",
        "margin": "0.0454",
        "margin_frozen": "0.0000",
        "margin_mode": "fixed",
        "margin_ratio": "0.0000",
        "realized_pnl": "-0.0001",
        "timestamp": "2019-09-27T03:47:37.230Z",
        "total_avail_balance": "0.0033",
        "unrealized_pnl": "-0.0051"
    }
}

获取某个合约的用户配置

获取某个合约的杠杆倍数,持仓模式

限速规则:5次/2s
HTTP请求

GET /api/swap/v3/accounts/<instrument_id>/settings

请求示例

GET /api/swap/v3/accounts/BTC-USD-SWAP/settings

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
返回参数
参数名 参数类型 描述
long_leverage String 多仓杠杆
margin_mode String 持仓模式
short_leverage String 空仓杠杆
instrument_id String 合约名称
解释说明

全仓同一个合约只允许有一种杠杆倍数,逐仓同一个合约同一个方向只能用一种杠杆倍数。

返回示例
{
    "long_leverage":"5.0000",
    "short_leverage":"5.0000",
    "margin_mode":"crossed",
    "instrument_id":"BTC-USD-SWAP"
}

设定某个合约的杠杆

设定某个合约的杠杆倍数

限速规则:5次/2s
HTTP请求

POST /api/swap/v3/accounts/<instrument_id>/leverage

请求示例

POST /api/swap/v3/accounts/BTC-USD-SWAP/leverage{"leverage": "10","side": "1"}

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
leverage String 杠杆倍数,填写1-100的数值
side String 方向
1:逐仓-多仓
2:逐仓-空仓
3:全仓
返回参数
参数名 参数类型 描述
long_leverage String 多仓杠杆
margin_mode String 持仓模式
short_leverage String 空仓杠杆
instrument_id String 合约名称
返回示例
{
    "long_leverage":"10.0000",
    "short_leverage":"10.0000",
    "margin_mode":"crossed",
    "instrument_id":"BTC-USD-SWAP"
}

账单流水查询

列出账户资产流水,账户资产流水是指导致账户余额增加或减少的行为。流水会分页,每页100条数据,并且按照时间倒序排序和存储,最新的排在最前面。 本接口能查询最近7天的数据。

限速规则:5次/2s
HTTP请求

GET /api/swap/v3/accounts/<instrument_id>/ledger

请求示例

GET /api/swap/v3/accounts/BTC-USD-SWAP/ledger?after=2&limit=30

注:after=2&limit=30代表在第2页请求30条数据,返回结果为第2页的30条最近的数据

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的ledger_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的ledger_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条
type String 1. 开多
2. 开空
3. 平多
4. 平空
5.转入
6.转出
7.清算未实现
8.分摊
9.剩余拨付
10.强平多
11.强平空
14.资金费
15.手动追加
16.手动减少
17.自动追加
18.修改持仓模式
19.强减多
20.强减空
21.用户调低杠杆追加保证金
22.清算已实现
返回参数
参数名 参数类型 描述
ledger_id String 账单id
amount String 变动金额
type String 账单类型
fee String 手续费
timestamp String 账单创建时间
instrument_id String 合约名称
currency String 币种,如:btc
details String 如果类型是交易产生的,则该details字段将包含order_idinstrument_id
order_id String 订单ID
balance String 开仓平仓的张数(开仓为正数,平仓为负数,当typefee时,balance0
流水来源类型 参数类型 描述
transfer String 转入/转出
match String 交易产生的资金变动
settlement String 清算/分摊
liquidation String 强平/减仓
funding String 资金费
margin String 修改保证金的资金变动
返回示例
[
     {
         "amount": "0.000011",
         "balance": "0",
         "fee": "0.000000",
         "currency": "BTC",
         "details": {
             "instrument_id": "BTC-USD-SWAP",
             "order_id": ""
         },
         "type": "funding",
         "instrument_id": "BTC-USD-SWAP",
         "ledger_id": "336890402630811792",
         "timestamp": "2019-10-03T16:00:00.000Z"
     },
     {
         "amount": "0.001812",
         "balance": "0",
         "fee": "0.000000",
         "currency": "BTC",
         "details": {
             "instrument_id": "BTC-USD-SWAP",
             "order_id": ""
         },
         "type": "settlement",
         "instrument_id": "BTC-USD-SWAP",
         "ledger_id": "336648803103555621",
         "timestamp": "2019-10-03T08:00:00.000Z"
     },
]

下单

API交易提供限价单下单模式,只有当您的账户有足够的资金才能下单。一旦下单,您的账户资金将在订单生命周期内被冻结,被冻结的资金以及数量取决于订单指定的类型和参数。目前api下单只支持以美元为计价单位

限速规则:40次/2s
HTTP请求

POST /api/swap/v3/order

请求示例

POST /api/swap/v3/order{"client_oid":"e12233456","size":"2","order_type”:”1”,"type":"1","match_price":"0","price":"432.11","instrument_id":"BTC-USD-SWAP"}

请求参数
参数名 参数类型 是否必须 描述
client_oid String 由您设置的订单id来唯一标识您的订单,数字+字母(大小写)或者纯字母(大小写)类型,1-32位
size String 下单数量
type String 可填参数:
1:开多
2:开空
3:平多
4:平空
order_type String 参数填数字
0:普通委托(order_type不填或填0都是普通委托)
1:只做Maker(Post only)
2:全部成交或立即取消(FOK)
3:立即成交并取消剩余(IOC)
match_price String 是否以对手价下单。
0:不是; 1:是。当以对手价下单,order_type只能选择0(普通委托)
price String 委托价格
instrument_id String 合约名称,如BTC-USD-SWAP

请求参数校验:合约名称必须是已存在合约名称;委托价格必须符合下单成交价格(不能达到溢价和强平价);下单类型除了1:开多; 2:开空; 3:平多; 4:平空都会报错;数量不能小于等于零,不能大于可开张数。

返回参数
参数名 参数类型 描述
order_id String 订单id,下单失败时,此字段值为-1
client_oid String 由您设置的订单id来标识您的订单
error_code String 错误码,下单成功时为0,下单失败时会显示相应错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
result String 调用接口返回结果
解释说明

instrument_id

instrument_id必须是有效的合约ID。合约列表可通过/ instruments接口获取。

client_oid

client_oid的类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符 ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单和查询订单时只能撤销或者查询最新的一条数据。

type

下单时,您可以指定订单类型。在您没有持仓时,只能选择开多和开空。您只能对持仓合约进行平仓。

price

price表示买入或卖出每张合约的价格。价格必须是价格步长tick_size的倍数。价格步长tick_size是价格的最小增量,可通过/instruments接口获取。

size

size表示买入或卖出合约的张数。数量必须是整数。

match_price

对手价表示你希望以目前对手方的最优价格成交。如果你下的是买单,选择以对手价下单表示你用当前卖一价进行下单。如果你下的是卖单,选择以对手价下单表示你用当前买一价进行下单。

订单生命周期

HTTP请求将在订单被拒绝(资金不足,参数无效等)或下单成功(由匹配引擎接受)时作出响应。一个200响应表示该订单被接收并且进入撮合。进入撮合的订单可以部分或全部立即成交(取决于价格和市场条件)。部分成交的时候将把订单的剩余数量继续进行撮合。完全成交的订单将进入已成交状态。

监听行情数据的用户建议使用client_oid字段以便在接受到的信息中标识对应的数据。

响应

成功接受的订单将被分配一个订单ID。成功接受的订单表示撮合引擎已经接受的订单。

未成交的订单不会过期,并将保持撮合状态,直到被成交或取消。

返回示例
{
    "error_message":"",
    "result":"true",
    "error_code":"0",
    "client_oid":"oktswap6",
    "order_id":"6a-d-54dcc6543-0"
}

批量下单

批量进行下单请求,每个合约可批量下10个单。

限速规则:20次/2s
HTTP请求

POST /api/swap/v3/orders

请求示例

POST /api/swap/v3/orders{"instrument_id": "EOS-USD-SWAP","order_data":[{"client_oid": "oktswap14", "type": "1", "price": "3.2571000000000003", "size": "1", "match_price": "0"}, {"client_oid": "oktswap15", "type": "1", "price": "3.2571000000000003", "size": "1", "match_price": "0"}]}

请求参数
参数名 参数类型 是否必须 描述
order_data List JSON类型的字符串
例:[{"order_type":"0","client_oid": "E213","price": "5","size": "2","type": "1","match_price": "0"},{"order_type":"0","client_oid": "243","price": "2","size": "3","type": "2","match_price": "1"}]
最大下单量为20,当以对手价下单,order_type只能选择0(普通委托)
client_oid String 由您设置的订单id来唯一标识您的订单,数字+字母(大小写)或者纯字母(大小写)类型,1-32位
size String 下单数量
price String 委托价格
type String 可填参数:
1:开多
2:开空
3:平多
4:平空
match_price String 是否以对手价下单
0:不是; 1:是。当以对手价下单,order_type只能选择0(普通委托)
order_type String 参数填数字
0:普通委托(order_type不填或填0都是普通委托)
1:只做Maker(Post only)
2:全部成交或立即取消(FOK)
3:立即成交并取消剩余(IOC)
instrument_id String 合约名称,如BTC-USD-SWAP

请求参数的校验和单个订单一致。

返回参数
参数名 参数类型 描述
order_id String 订单id,下单失败时,此字段值为-1
client_oid String 由您设置的订单id来标识您的订单
error_code String 错误码,下单成功时返回0,下单失败时会显示相应的错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
result String 调用接口返回结果
解释说明

client_oid是数字+字母(大小写)或者纯字母(大小写)类型 1-32位

result是代表服务器处理了请求,不代表下单、撤单是否成功。

返回的结果数据和order_data提交订单数据顺序一致。如果下单失败,则order_id-1error_code是错误码提示,error_message是错误信息。

返回示例
{
    "order_info":[
        {
            "client_oid":"oktswap14",
            "error_code":"0",
            "error_message":"",
            "order_id":"6a-d-54df9a2ac-0"
            "result": "true"
        },
        {
            "client_oid":"oktswap15",
            "error_code":"0",
            "error_message":"",
            "order_id":"6a-d-54df9a2ad-0"
            "result": "true"
        }
    ],
    "result":"true"
}

撤单

撤销之前下的未完成订单。

限速规则:40次/2s
HTTP请求

POST /api/swap/v3/cancel_order/<instrument_id>/<order_id> or <client_oid>

请求示例

POST /api/swap/v3/cancel_order/BTC-USD-SWAP/64-2b-17122f911-3

POST /api/swap/v3/cancel_order/BTC-USD-SWAP/64er

请求参数
参数名 参数类型 是否必须 描述
order_id String 非必填 order_idclient_oid必须且只能选一个填写,订单id
instrument_id String 合约名称,如BTC-USD-SWAP
client_oid String 非必填 order_idclient_oid必须且只能选一个填写,由您设置的订单ID来识别您的订单 , 类型为字母(大小写)+数字或者纯字母(大小写)1-32位字符

请求参数校验:合约名称必须是已存在合约的名称;order_id必须是已存在的order_id

返回参数
参数名 参数类型 描述
order_id String 订单id
result String 撤单申请结果
client_oid String 由您设置的订单ID来识别您的订单
解释说明

使用client_oid撤单时,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单时只能撤销最新的一条数据

order_idclient_oid必须且只能选一个填写

order_id是服务器分配的订单ID,而不是用户传的的client_oid

返回值是已发起撤销操作的订单ID,不代表这些订单已成功撤销,正在成交中的无法撤销,未成交的可成功撤销。

result是代表服务器处理了请求,不代表下单、撤单是否成功。

如果订单无法取消(已经成交或已取消),那么返回的报错内容里将显示相应的原因。

返回示例

{
    "result":"true",
    "client_oid":"oktswap6",
    "order_id":"6a-d-54dcc6543-0"
}

批量撤单

撤销之前下的未完成订单,每个币对可批量撤10个单。

限速规则:20次/2s
HTTP请求

POST /api/swap/v3/cancel_batch_orders/<instrument_id>

请求示例

POST /api/swap/v3/cancel_batch_orders/BTC-USD-SWAP{"ids":["64-2a-17122d911-0","64-2b-17124f911-0","64-2c-17126f911-0"]}

POST /api/swap/v3/cancel_batch_orders/BTC-USD-SWAP{"client_oids":["6EEE33","643RE","64REE"]}

请求参数
参数名 参数类型 是否必须 描述
ids List<String> 非必填 order_idclient_oid必须且只能选一个填写,订单id列表
instrument_id String 合约名称,如BTC-USD-SWAP
client_oids List<String> 非必填 order_idclient_oid必须且只能选一个填写,由您设置的订单ID来识别您的订单,类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符

请求参数校验和单个订单撤销一致。

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
ids String 订单id列表
result String 撤单申请结果
返回参数

返回值是已发起撤销操作的订单ID列表,不代表这些订单已成功撤销,正在成交中的无法撤销,未成交的可成功撤销。

解释说明

批量撤单时候,要么都是order_id要么都是client_oid,否则会提示错误

使用client_oid批量撤单时,目前只支持一个币对下撤一个client_oid ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,撤单时只能撤销最新的一条数据

result是代表服务器处理了请求,不代表下单、撤单是否成功。如果全部都撤单失败,result就为false

无法保证一定会成功撤销,建议用户调用批量撤单接口后,再调用获取订单列表接口确认。

返回示例
1. 用order_ids批量撤单:

{
    "client_oids":[

    ],
    "ids":[
        "6a-d-54df9a2ac-0",
        "6a-d-54df9a2ad-0"
    ],
    "instrument_id":"EOS-USD-SWAP",
    "result":"true"
}


2. 用client_oids撤单:

{
    "client_oids":[
        "oktswap16",
        "oktswap17"
    ],
    "ids":[

    ],
    "instrument_id":"EOS-USD-SWAP",
    "result":"true"
}

获取所有订单列表

列出您当前所有的订单信息。本接口能查询最近7天20000条数据。这个请求支持分页,并且按委托时间倒序排序和存储,最新的排在最前面。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/orders/<instrument_id>

请求示例

GET /api/swap/v3/orders/EOS-USD-SWAP?state=2&after=1&limit=2

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的order_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的order_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条
state String 订单状态
-2:失败
-1:撤单成功
0:等待成交
1:部分成交
2:完全成交
3:下单中
4:撤单中
6: 未完成(等待成交+部分成交)
7:已完成(撤单成功+完全成交)
返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
client_oid String 用户设置的订单ID
size String 委托数量
timestamp String 创建时间
filled_qty String 成交数量
fee String 手续费
order_id String 订单id
price String 委托价格
price_avg String 成交均价
type String 1:开多
2:开空
3:平多
4:平空
contract_val String 合约面值
order_type String 0:普通委托
1:只做Maker(Post only)
2:全部成交或立即取消(FOK)
3:立即成交并取消剩余(IOC)
state String -2:失败
-1:撤单成功
0:等待成交
1:部分成交
2:完全成交
3:下单中
4:撤单中
trigger_price String 强平的真实触发价格,仅强平单会返回此字段
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换state

client_oid的类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符 ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,查询订单时只能查询出最新的一条数据。

最新的定义为 先从未成交表查,如果未成交表没有,再查已成交表的最新数据。

返回示例
{
    "order_info":[
        {
            "client_oid":"",
            "contract_val":"10",
            "fee":"-0.000551",
            "filled_qty":"1",
            "instrument_id":"EOS-USD-SWAP",
            "order_id":"6a-7-54d663a28-0",
            "order_type":"0",
            "price":"3.633",
            "price_avg":"3.633",
            "size":"1",
            "state":"2",
            "status":"2",
            "timestamp":"2019-03-25T05:56:21.674Z",
            "trigger_price": "0.0",
            "type":"4"
        },
        {
            "client_oid":"",
            "contract_val":"10",
            "fee":"-0.000550",
            "filled_qty":"1",
            "instrument_id":"EOS-USD-SWAP",
            "order_id":"6a-8-54cee3a3f-0",
            "order_type":"0",
            "price":"3.640",
            "price_avg":"3.640",
            "size":"1",
            "state":"2",
            "status":"2",
            "timestamp":"2019-03-25T03:45:17.376Z",
            "trigger_price": "0.0",
            "type":"2"
        }
    ]
}

获取订单信息

通过订单id获取单个订单信息。本接口只能查询最近3个月的已成交和已撤销订单信息。已撤销的未成交单只保留2个小时。

限速规则:40次/2s
HTTP请求

GET /api/swap/v3/orders/<instrument_id>/<order_id>

GET /api/swap/v3/orders/<instrument_id>/<client_oid>

请求示例

GET /api/swap/v3/orders/BTC-USD-SWAP/64-2a-26132f931-3

GET /api/swap/v3/orders/BTC-USD-SWAP/64rt

请求参数
参数名 参数类型 是否必须 描述
order_id String 订单id , order_idclient_oid必须且只能选一个填写
instrument_id String 合约名称,如BTC-USD-SWAP
client_oid String order_idclient_oid必须且只能选一个填写 . 由您设置的订单ID来识别您的订单 , 类型为字母(大小写)+数字或者纯字母(大小写)1-32位字符
返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
client_oid String 由您设置的订单ID来识别您的订单
size String 委托数量
timestamp String 创建时间
filled_qty String 成交数量
fee String 手续费
order_id String 订单id
price String 委托价格
price_avg String 成交均价
type String 1:开多
2:开空
3:平多
4:平空
contract_val String 合约面值
order_type String 0:普通委托
1:只做Maker(Post only)
2:全部成交或立即取消(FOK)
3:立即成交并取消剩余(IOC)
state String -2:失败
-1:撤单成功
0:等待成交
1:部分成交
2:完全成交
3:下单中
4:撤单中
trigger_price String 强平的真实触发价格,仅强平单会返回此字段
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换state

client_oid的类型为字母(大小写)+数字或者纯字母(大小写),1-32位字符 ,用户需要自己保证此ID不重复,我方不会进行排重提示,如有重复,查询订单时只能查询出最新的一条数据。

最新的定义为 先从未成交表查,如果未成交表没有,再查已成交表的最新数据。

返回示例
{
    "filled_qty":"1",
    "fee":"-0.000550",
    "client_oid":"",
    "price_avg":"3.640",
    "trigger_price": "0.0",
    "type":"2",
    "instrument_id":"EOS-USD-SWAP",
    "size":"1",
    "price":"3.640",
    "contract_val":"10",
    "order_id":"6a-8-54cee3a3f-0",
    "order_type":"0",
    "status":"2",
    "state":"2",
    "timestamp":"2019-03-25T03:45:17.376Z"
}

获取成交明细

获取最近的成交明细列表,本接口能查询最近7天的数据。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/fills

请求示例

GET /api/swap/v3/fills?order_id=64-2b-16122f931-3&instrument_id=BTC-USD-SWAP&after=1&limit=50

(返回BTC-USD-SWAPorder_id64-2b-16122f931-3的订单中第1页前50笔成交信息)

请求参数
参数名 参数类型 是否必须 描述
order_id String 订单ID,不填写order_id,返回当前instrument_id下的所有订单成交明细
instrument_id String 合约名称,如BTC-USD-SWAP
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的trade_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的trade_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条
返回参数
参数名 参数类型 描述
trade_id String 成交id
instrument_id String 合约名称,如BTC-USD-SWAP
order_id String 订单id
price String 成交价格
order_qty String 成交数量
fee String 手续费
timestamp String 成交时间
exec_type String 流动性方向
T:taker; M:maker
side String 订单方向
解释说明

手续费

fee字段:负数的fee表示平台收取的手续费,正数的fee表示表示平台向达到指定lv交易等级的用户支付的挂单奖励(返佣)

返回示例
 [
     {
         "trade_id":"197429674631450625",
         "instrument_id":"EOS-USD-SWAP",
         "order_id":"6a-7-54d663a28-0",
         "price":"3.633",
         "order_qty":"1.0000",
         "fee":"-0.000551",
         "timestamp":"2019-03-25T05:56:31.287Z",
         "exec_type":"M",
         "side":"short"
     }
 ]

获取合约挂单冻结数量

获取合约挂单冻结数量。

限速规则:5次/2s
HTTP请求

GET /api/swap/v3/accounts/<instrument_id>/holds

请求示例

GET /api/swap/v3/accounts/BTC-USD-SWAP/holds

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
amount String 开仓冻结保证金
timestamp String 查询时间

校验合约名称,只要和数据库中的合约名称不同,就会报错

返回示例
{
    "instrument_id":"BTC-USD-SWAP",
    "amount":"303613",
    "timestamp":"2019-03-26T02:36:22.703Z"
}

委托策略下单

委托策略下单

提供止盈止损、跟踪委托、冰山委托和时间加权委托策略

限速规则:40次/2s
HTTP请求

POST /api/swap/v3/order_algo

请求示例

POST /api/swap/v3/order_algo{"instrument_id":"BTC-USD-SWAP","type":"1","trigger_price":"432.11","order_type":"1",“algo_price“:"341.99","size":"2"}(止盈止损)

请求参数(通用)
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-SWAP
type String 1:开多
2:开空
3:平多
4:平空
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
size String 委托总数(以张计数),填写值1\<=X\<=1000000的整数
止盈止损参数 (最多同时存在10单)
参数名 参数类型 是否必须 描述
trigger_price String 触发价格,填写值0\<X\<=1000000
algo_price String 委托价格,填写值0\<X\<=1000000
跟踪委托参数 (最多同时存在10单)
参数名 参数类型 是否必须 描述
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 单笔均值,填写2-1000的整数(永续2-500的整数)
price_limit 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 单笔上限,填写值10\<=X\<=2000(永续2-500的整数)
price_limit String 价格限制,填写值0\<X\<=1000000
time_interval String 委托间隔,填写值5\<=X\<=120

返回参数

参数名 参数类型 描述
result String 调用接口返回结果
instrument_id String 合约ID,如BTC-USD-SWAP
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
algo_id String 订单ID,下单失败时,此字段值为-1
error_code String 错误码,下单成功时为0,下单失败时会显示相应错误码
error_message String 错误信息,下单成功时为空,下单失败时会显示错误信息
返回示例
{
    "code": 0,
    "data": {
        "result": "success",
        "algo_id": "340286404443709440",
        "error_message": "",
        "error_code": "0",
        "instrument_id": "BTC-USD-SWAP",
        "order_type": 1
    },
    "detailMsg": "",
    "msg": ""
}

委托策略撤单

委托策略撤单

根据指定的algo_id撤销某个合约的未完成订单,每次最多可撤6(冰山/时间)/10(计划/跟踪)个。

限速规则:20 次/2s
HTTP请求

POST /api/swap/v3/cancel_algos

请求示例

单个撤单:POST /api/swap/v3/cancel_algos{“instrument_id":"BTC-USD-SWAP","order_type":“1”,"algo_ids":[“198273485”]}

批量撤单:POST /api/swap/v3/cancel_algos{“instrument_id":"BTC-USD-SWAP","order_type":“1”,"algo_ids":["198273485","198273486"]}

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 撤销指定的合约品种
algo_ids List<String> 撤销指定的委托单ID
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
返回参数
参数名 参数类型 描述
instrument_id String 撤销指定的合约品种
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
algo_ids String 撤销指定的委托单ID
result String 调用接口返回结果

返回参数

返回值是已发起撤销操作的委托单ID,不代表这些委托单已成功撤销,正在成交中的无法撤销,未成交的可成功撤销。

解释说明

无法保证一定会成功撤销,建议用户调用撤单接口后,再调用获取委托单列表接口确认。

返回示例
{
    "code": 0,
    "data": {
        "result": "success",
        "algo_ids": "[340286404443709440]",
        "instrument_id": "BTC-USD-SWAP",
        "order_type": "1"
    },
    "detailMsg": "",
    "msg": ""
}

获取委托单列表

获取委托单列表

列出您当前所有的订单信息。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/order_algo/<instrument_id>

请求示例

GET /api/swap/v3/order_algo/BTC-USD-SWAP?order_type=1&status=3

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约ID,如BTC-USD-SWAP
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
status String 见描述 statusalgo_id必填且只能填其一】
订单状态
1:待生效
2:已生效
3:已撤销
4:部分生效
5:暂停生效
6:委托失败
【只有冰山和加权有45状态】
algo_id String 见描述 statusalgo_id必填且只能填其一】
查询指定的委托单ID
before string 请求此id之后(更新的数据)的分页内容
after string 请求此id之前(更旧的数据)的分页内容
limit string 分页返回的结果集数量,默认为100,最大为100
返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-SWAP
order_type String 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权
timestamp String 委托时间
real_price String 实际委托价格
algo_id String 委托单ID
status String 订单状态
1: 待生效
2: 已生效
3: 已撤销
4: 部分生效
5: 暂停生效
type String 订单类型
1:开多
2:开空
3:平多
4:平空
leverage String 杠杆倍数
size String 委托数量(以张计数),填写值1\<=X\<=1000000的整数
algo_price String 策略委托价格
real_amount String 实际委托数量
trigger_price String 策略委托触发价格

止盈止损

参数名 参数类型 描述
trigger_price String 触发价格,填写值0\<X
algo_price String 委托价格,填写值0\<X\<=1000000
real_amount String 实际成交数量

跟踪委托

参数名 参数类型 描述
callback_rate String 回调幅度,填写值0.001(0.1%)\<=X\<=0.05(5%)
trigger_price String 激活价格 ,填写值0\<X\<=1000000
real_amount String 实际委托数量

冰山委托

参数名 参数类型 描述
algo_variance String 委托深度,填写值0\<=X\<=0.01(1%)
avg_amount String 单笔均值,填写2-500的整数(永续2-500的整数)
price_limit 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的整数)
price_limit String 价格限制,填写值0\<X\<=1000000
time_interval String 委托间隔,填写值5\<=X\<=120
deal_value String 已委托量
返回示例
{
    "orderStrategyVOS": [
        {
            "algo_id": "340286404443709440",
            "algo_price": "8300.0",
            "instrument_id": "BTC-USD-SWAP",
            "leverage": "15.00",
            "order_type": "1",
            "real_amount": "0.0000",
            "real_price": "0.0",
            "size": "1.0000",
            "status": "3",
            "timestamp": "2019-10-08T08:27:20.517Z",
            "trigger_price": "8200.0",
            "type": "1"
        },
        {
            "algo_id": "337464291111936000",
            "algo_price": "9000.0",
            "instrument_id": "BTC-USD-SWAP",
            "leverage": "15.00",
            "order_type": "1",
            "real_amount": "0.0000",
            "real_price": "0.0",
            "size": "1.0000",
            "status": "3",
            "timestamp": "2019-10-04T11:00:18.392Z",
            "trigger_price": "8500.0",
            "type": "1"
        },
    ]
}

公共-获取合约信息

获取可用合约的列表,这组公开接口提供了行情数据的快照,无需认证即可调用。 获取可用合约的列表,查询各合约的交易限制和价格步长等信息。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments

请求示例

GET /api/swap/v3/instruments

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
underlying_index String 合约币种,如BTC-USD-SWAP中前面的BTC
quote_currency String 计价货币,如BTC-USD-SWAP中的USD
coin String 保证金币种,如BTC-USD-SWAP中BTC
contract_val String 合约面值
Listing String 创建时间
delivery String 结算时间
size_increment String 数量精度
tick_size String 价格精度
返回示例
[
    {
        "instrument_id":"TESTD-USD-SWAP",
        "underlying_index":"TESTD",
        "quote_currency":"USD",
        "coin":"TESTD",
        "contract_val":"100",
        "listing":"2019-03-05T07:43:23.000Z",
        "delivery":"2019-03-25T14:00:00.000Z",
        "size_increment":"1",
        "tick_size":"0.1"
    },
    {
        "instrument_id":"BTC-USD-SWAP",
        "underlying_index":"BTC",
        "quote_currency":"USD",
        "coin":"BTC",
        "contract_val":"100",
        "listing":"2018-08-28T02:43:23.000Z",
        "delivery":"2019-03-25T14:00:00.000Z",
        "size_increment":"1",
        "tick_size":"0.1"
    },
    ...
]

公共-获取深度数据

获取合约的深度列表。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/depth

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/depth?size=50

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
size String 返回深度数量,最大值可传200,即买卖深度共400条

校验合约名称,只要和数据库中的合约名称不同,就会报错

size不传时,返回1条;size0时,返回0条;size最大200,传大于200的数时,返回200条。

返回参数
参数名 参数类型 描述
asks List<String> 卖方深度
bids List<String> 买方深度
timestamp String 系统时间戳

返回值数组说明

["411.8", "10", "1", "4"] 411.8为深度价格,10为此价格的合约张数,1为此价格的强平单个数,4为此价格的订单个数。

返回示例
{
    "asks":[
        [
            "3968.5",
            "121",
            0,
            2
        ],
        [
            "3968.6",
            "160",
            0,
            4
        ]
    ],
    "bids":[
        [
            "3968.4",
            "179",
            0,
            4
        ],
        [
            "3968",
            "914",
            0,
            3
        ]
    ],
    "time":"2019-03-25T11:12:10.601Z"
}

公共-获取全部ticker信息

获取平台全部合约的最新成交价、买一价、卖一价和24交易量。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/ticker

请求示例

GET /api/swap/v3/instruments/ticker

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
best_ask String 卖一价
best_bid String 买一 价
last String 最新成交价
high_24h String 24小时最高价
low_24h String 24小时最低价
volume_24h String 24小时成交量,按张数统计
timestamp String 系统时间戳
解释说明

最高价、最低价和成交量都是按最近24小时为维度统计的。

返回示例
[
    {
        "instrument_id":"BTC-USD-SWAP",
        "last":"3968.1",
        "high_24h":"3980",
        "low_24h":"3942.6",
        "volume_24h":"264017",
        "best_ask":"3968.1",
        "best_bid":"3968",
        "timestamp":"2019-03-25T11:34:02.241Z"
    },
    {
        "instrument_id":"EOS-USD-SWAP",
        "last":"3.609",
        "high_24h":"3.665",
        "low_24h":"3.57",
        "volume_24h":"1537961",
        "best_ask":"3.609",
        "best_bid":"3.608",
        "timestamp":"2019-03-25T11:34:05.557Z"
    }
]

公共-获取某个ticker信息

获取合约的最新成交价、买一价、卖一价和24交易量。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/ticker

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/ticker

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP

校验合约名称,只要和数据库中的合约名称不同,就会报错

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
last String 最新成交价
best_bid String 买一价
best_ask String 卖一价
high_24h String 24小时最高价
low_24h String 24小时最低价
volume_24h String 24小时成交量,按张数统计
timestamp String 系统时间戳
解释说明

最高价、最低价和成交量都是按最近24小时为维度统计的。

返回示例
{
    "instrument_id":"EOS-USD-SWAP",
    "last":"3.611",
    "high_24h":"3.665",
    "low_24h":"3.57",
    "volume_24h":"1733788",
    "best_ask":"3.611",
    "best_bid":"3.61",
    "timestamp":"2019-03-25T09:16:07.501Z"
}

公共-获取成交数据

获取合约的成交记录,本接口能查询最近300条数据。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/trades

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/trades?after=1&limit=50

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
after String 请求此id之前(更旧的数据)的分页内容,传的值为对应接口的trade_id
before String 请求此id之后(更新的数据)的分页内容,传的值为对应接口的trade_id
limit String 分页返回的结果集数量,最大为100,不填默认返回100条

校验合约名称,只要和数据库中的合约名称不同,就会报错。afterbefore同时传,以after为准

返回参数
参数名 参数类型 描述
trade_id String 成交id
price String 成交价格
size String 成交数量
side String 成交方向:sellbuy
timestamp String 成交时间
解释说明

成交方向side是指 buysell,返回 buysell

获取永续合约最新的300条成交列表

返回示例
[
    {
        "trade_id":"197610300823248897",
        "price":"3969.2",
        "size":"5",
        "side":"buy",
        "timestamp":"2019-03-25T11:55:23.569Z"
    },
    {
        "trade_id":"197608511860318209",
        "price":"3969.3",
        "size":"56",
        "side":"sell",
        "timestamp":"2019-03-25T11:51:50.308Z"
    }
]

公共-获取K线数据

获取合约的K线数据。k线数据最多可获取最近1440条。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/candles

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/candles?start=2019-03-24T02:31:00.000Z&end=2019-03-25T02:55:00.000Z&granularity=86400

(查询BTC-USD-SWAP的2019年3月24日到25日的日线K线数据)

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
start String 开始时间,必须是ISO8601格式的时间
end String 结束时间,必须是ISO8601格式的时间
granularity String 时间粒度,以秒为单位,默认值60。如[60/180/300/900/1800/3600/7200/14400/21600/43200/86400/604800],详见下解释说明
返回参数
参数名 参数类型 描述
timestamp String 系统时间
open String 开盘价格
high String 最高价格
low String 最低价格
close String 收盘价格
volume String 交易量(按张折算)
currency_volume String 交易量(按币折算)
解释说明

如果用户没有提供开始时间或结束时间中的任一字段,则两个字段都将被忽略。未提供开始时间和结束时间的请求,则系统按时间粒度返回最近的200条数据。

时间粒度granularity必须是[60 180 300 900 1800 3600 7200 14400 21600 43200 86400 604800]中的任一值,否则请求将被拒绝。这些值分别对应的是[1min 3min 5min 15min 30min 1hour 2hour 4hour 6hour 12hour 1day 1week]的时间段。

K线数据可能不完整。

单次请求的最大数据量是200。如果您选择的开始/结束时间和时间粒度导致超过单次请求的最大数据量,您的请求将只会返回200个数据。如果您希望在更大的时间范围内获取足够精细的数据,则需要使用多个开始/结束范围进行多次请求。

数组中的数据顺序分别是:时间戳,开盘价格,最高价格,最低价格,收盘价格,交易量(张),交易量(币)

即分别为[timestamp,open,high,low,close,volume,currency_volume]

返回示例
[
    [
        "2019-03-25T16:00:00.000Z",
        "3946.6",
        "3960",
        "3860",
        "3917.7",
        "329627",
        "8434.421"
    ],
    [
        "2019-03-24T16:00:00.000Z",
        "3971.4",
        "3977.7",
        "3942.6",
        "3946.4",
        "333780",
        "8416.0873"
    ]
]

//["系统时间","开盘价格","最高价格","最低价格","收盘价格","交易量(按张折算)","交易量(按币折算)"]

公共-获取指数信息

获取币种指数。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/index

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/index

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP

校验合约名称,只要和数据库中的合约名称不同,就会报错

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
index String 现货指数价格
timestamp String 系统时间戳
解释说明

指数币对"-"后面的币种表示指数价格的计价单位。

返回示例
{
    "instrument_id":"BTC-USD-SWAP",
    "index":"3913.64749999",
    "timestamp":"2019-03-26T02:30:20.560Z"
}

公共-获取法币汇率

获取法币汇率。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/rate

请求示例

GET /api/swap/v3/rate

返回参数
参数名 参数类型 描述
instrument_id String USD_CNY
rate String 汇率
timestamp String 系统时间戳
返回示例
{
    "instrument_id":"USD_CNY",
    "rate":"6.701",
    "timestamp":"2019-03-26T02:32:52.703Z"
}

公共-获取平台总持仓量

获取合约整个平台的总持仓量。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/open_interest

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/open_interest

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
amount String 总持仓量
timestamp String 系统时间戳

校验合约名称,只要和数据库中的合约名称不同,就会报错

返回示例
{
    "instrument_id":"BTC-USD-SWAP",
    "amount":"303613",
    "timestamp":"2019-03-26T02:36:22.703Z"
}

公共-获取当前限价

获取合约当前交易的最高买价和最低卖价。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/price_limit

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/price_limit

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP

校验合约名称,只要和数据库中的合约名称不同,就会报错

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
highest String 最高买价
lowest String 最低卖价
timestamp String 系统时间戳
返回示例
{
    "instrument_id":"BTC-USD-SWAP",
    "highest":"3953.4",
    "lowest":"3875.0",
    "timestamp":"2019-03-26T02:42:38.143Z"
}

公共-获取强平单

获取合约强平单。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/liquidation

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/liquidation?status=1&limit=50

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
status String 状态
0:最近7天的未成交
1:最近7天的已成交
limit String 分页返回的结果集数量,默认为100,最大为100,按时间倒序排列,越晚的在前面
from String 请求此id之前(更旧的数据)的分页内容,例如 2
to String 请求此id之后(更新的数据)的分页内容 例如 3

校验合约名称,只要和数据库中的合约名称不同,就会报错

status不是01,报非法参数

afterbefore同时传,以after为准

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
size String 数量
created_at String 委托时间
loss String 穿仓用户亏损
price String 委托价格
type String 3:平多
4:平空
返回示例
[
    {
        "instrument_id":"BTC-USD-SWAP",
        "size":"4",
        "created_at":"2019-03-26T02:00:40.490Z",
        "loss":"0",
        "price":"3935.1",
        "type":"4"
    },
    {
        "instrument_id":"BTC-USD-SWAP",
        "size":"193",
        "created_at":"2019-03-25T23:28:15.922Z",
        "loss":"0",
        "price":"3932.5",
        "type":"4"
    }
]

公共-获取合约资金费率

获取合约下一次的结算时间。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/funding_time

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/funding_time

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP

校验合约名称,只要和数据库中的合约名称不同,就会报错

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
funding_time String 当期资金费率时间
funding_rate String 当期资金费率
estimated_rate String 下一期预测资金费率
settlement_time String 结算时间
返回示例
{
  "instrument_id": "EOS-USD-SWAP",
  "funding_time": "2019-09-02T16:00:00.000Z",
  "funding_rate": "-0.00066983",
  "estimated_rate": "-0.00043662",
  "settlement_time": "2019-09-02T16:00:00.000Z"
}

公共-获取合约标记价格

获取合约标记价格。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/mark_price

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/mark_price

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
mark_price String 标记价格
timestamp String 系统时间戳

为了防止个别用户恶意操控市场导致合约价格波动剧烈,我们根据现货指数和合理基差设定标记价格。

返回示例

{
    "instrument_id":"BTC-USD-SWAP",
    "mark_price":"3914.3",
    "timestamp":"2019-03-26T03:33:50.064Z"
}

公共-获取合约历史资金费率

获取合约历史资金费率,本接口能查询最近7天的数据。

限速规则:20次/2s
HTTP请求

GET /api/swap/v3/instruments/<instrument_id>/historical_funding_rate

请求示例

GET /api/swap/v3/instruments/BTC-USD-SWAP/historical_funding_rate?limit=2

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 合约名称,如BTC-USD-SWAP
limit String 分页返回的结果集数量,默认为100,最大为100,按时间顺序排列,越早下单的在前面

校验合约名称,只要和数据库中的合约名称不同,就会报错。

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
funding_rate String 当期资金费率
realized_rate String 实际资金费率
interest_rate String 利率
funding_time String 结算时间
返回示例
[
    {
        "instrument_id":"BTC-USD-SWAP",
        "funding_rate":"-0.00007116",
        "realized_rate":"-0.00007116",
        "interest_rate":"0.00000000",
        "funding_time":"2019-03-26T02:00:00.000Z"
    },
    {
        "instrument_id":"BTC-USD-SWAP",
        "funding_rate":"-0.00010248",
        "realized_rate":"-0.00010248",
        "interest_rate":"0.00000000",
        "funding_time":"2019-03-25T14:00:00.000Z"
    }
]

指数 API

指数接口

公共-获取指数成分

获取指数成分。此接口为公共接口,不需要身份验证。

限速规则:20次/2s
HTTP请求

GET /api/index/v3/<instrument_id>/constituents

请求示例

GET /api/index/v3/BTC-USD/constituents

请求参数
参数名 参数类型 是否必须 描述
instrument_id String 指数币对,如BTC指数则为BTC-USD
返回参数
参数名 参数类型 描述
last String 最新指数价格
original_price Price 原始价格
weight String 权重
usd_price String 折算成USD价格
exchange String 交易所名称
instrument_id String 指数币对,如BTC指数则为BTC-USD
timestamp String 系统时间戳
symbol String 交易所币对名称,如BTC-USD
解释说明

指数币对"-"后面的币种表示指数价格的计价单位。

返回示例
{
  "code": 0,
  "data": {
    "last": "5562.42250000",
    "constituents": [
      {
        "symbol": "BTC-USD",
        "original_price": "5562.75",
        "weight": "0.25",
        "usd_price": "5562.75",
        "exchange": "GEMINI"
      },
      {
        "symbol": "BTC-USD",
        "original_price": "5562.44",
        "weight": "0.25",
        "usd_price": "5562.44",
        "exchange": "Coinbase"
      },
      {
        "symbol": "BTC-USD",
        "original_price": "5564.5",
        "weight": "0.25",
        "usd_price": "5564.5",
        "exchange": "Bitstamp"
      },
      {
        "symbol": "BTC-USD",
        "original_price": "5560",
        "weight": "0.25",
        "usd_price": "5560",
        "exchange": "kraken"
      }
    ],
    "instrument_id": "BTC-USD",
    "timestamp": "2019-04-23T12:13:03.848Z"
  },
  "detailMsg": "",
  "msg": ""
}

这里是RestAPI 错误码

公共错误码(30000-31000)

v3API将使用统一30000开头的错误码

公共错误码包括签名以及各个业务线统一的错误码

错误提示 错误码 http状态码
成功(下单成功,撤单成功,操作成功等) 0 200
长时间没有接收到数据 4001 400
缓冲区无法写入数据关闭 4002 400
请求头"OK_ACCESS_KEY"不能为空 30001 400
请求头"OK_ACCESS_SIGN"不能为空 30002 400
请求头"OK_ACCESS_TIMESTAMP"不能为空 30003 400
请求头"OK_ACCESS_PASSPHRASE"不能为空 30004 400
无效的OK_ACCESS_TIMESTAMP 30005 400
无效的OK_ACCESS_KEY 30006 400
无效的Content_Type,请使用“application/json”格式 30007 400
请求时间戳过期 30008 400
系统错误 30009 500
api 校验失败 30010 401
无效的ip 30011 400
无效的授权 30012 401
无效的sign 30013 401
请求太频繁 30014 429
请求头"OK_ACCESS_PASSPHRASE"错误 30015 400
您使用的是v1的apiKey,请调用v1接口。若您希望调用v3接口,请注册v3的apiKey。 30016 400
apikey所属broker ID不匹配 30017 400
apikey所属域名不匹配 30018 400
接口已下线或无法使用 30019 400
body 不能为空 30020 400
非法的json数据 30021 400
Api已被冻结,请联系客服处理 30022 401
{0}参数不能为空 必填参数不能为空(各个业务接口返回各个接口的参数) 30023 400
{0}参数值填写错误(各个业务接口返回各个接口的参数) 30024 400
{0}参数类型错误(各个业务接口返回各个接口的参数) 30025 400
用户请求频率过快,超过该接口允许的限额(调用时超过频率限制) 30026 429
登录失败(操作了别人的订单) 30027 401
非本人操作(Userid错误等) 30028 400
用户被冻结 30029 400
请求接口失败,请您重试(请求接口失败,请您重试) 30030 400
币种不存在 30031 400
币对不存在 30032 400
券商域名不存在(验证apikey所属交易所,为空,报这个错误) 30033 400
券商ID不存在(验证apikey所属交易所ID,为空,报这个错误) 30034 400
该网站暂不支持交易(该交易所请求,交易时,如果该交易已关闭,则提示报这个错误) 30035 400
查询接口时,没有相应数据可以返回(各个接口返回各个接口的内容) 30036 400
用户不存在(无法找到用户的信息) 30038 400
接口已下线或无法使用 30037 400

资金账户错误码(34000-35000)

错误提示 错误码 http状态码
提现冻结(提现接口,账户被冻结) 34001 400
请先添加提现地址(提现接口,地址未添加) 34002 400
该币种暂不支持提现至XX,敬请谅解(提现接口,地址不正确) 34003 400
提现手续费小于最小值(提现接口,手续费输入有误) 34004 400
提现手续费大于最大值(提现接口,提现手续费输入有误) 34005 400
提现金额小于最小提现金额(最小提现金额提现接口,提现金额输入有误) 34006 400
提现金额大于单笔提现最大金额(单笔提现最大金额提现接口,提现金额输入有误) 34007 400
您的余额不足(划转和提现接口,余额不足) 34008 400
今日提现金额累计超过每日限额(提现接口,提现金额超限) 34009 400
转账金额必须大于零(划转接口,金额输入不正确) 34010 400
不符合条件(划转提现接口,不符合条件,如kyc等级不够) 34011 400
NEO最小提现数量为1,且提现数量必须为整数(提现接口,某些币特殊限制) 34012 400
需要传instrument ID(划转接口,转入或转出是币币杠杆时instrument ID未传) 34013 400
划转受限(划转接口,划转资金受限) 34014 400
子账户不存在(划转接口,转入或转出是子账户时,子账户不存在) 34015 400
划转冻结(划转接口,源或目的不允许划转) 34016 400
账户冻结(划转和提现接口,源或目的不允许划转) 34017 400
交易密码错误(交易密码错误) 34018 400
您需要绑定邮箱后,才能提现(提现接口,需要先绑定邮箱) 34019 400
您需设置资金密码后,才能提现(提现接口,需要先设置资金密码) 34020 400
不是认证地址(提现接口,不是认证的地址) 34021 400
提现接口,子账号不允许提现 34022 400
请于转账前确认已开通合约交易 34023 400
请先开通余币宝服务 34025 400
划转过于频繁,请降低划转频率 34026 400
提现手续费应填写为提币数量的*% 34027 400

币币和杠杆错误码(33000-34000)

错误提示 错误码 http状态码
您尚未开通此币种对应杠杆业务(没有开通该币种杠杆业务时调接口会报错) 33001 400
您的此币种对应杠杆账号已被冻结(杠杆账户被冻结) 33002 400
没有借款余额(没有足够的余额进行借币) 33003 400
借币数量不能小于最小借币数(借币时借币的数量) 33004 400
还款金额不能小于等于0(还款金额不对) 33005 400
没有该借币订单(还币或者查询的时候没有借币订单会报此错误) 33006 400
不存在该状态 33007 400
借币数量不能大于您的可借数量 33008 400
用户ID为空 33009 400
价格发现第二阶段您不可撤单(集合竞价时候不可以撤单) 33010 400
没有最新行情信息 33011 400
撤单失败 33012 400
下单失败 33013 400
订单不存在(重复撤单,订单号不对等) 33014 400
批量操作超过最大数量限制(批量下单,批量撤单时候会出现) 33015 400
该币对没有开通杠杆业务 33016 400
下单大于最大可用余额(下单余额不足) 33017 400
该参数值填写错误,要填写小于1的数值 33018 400
暂不支持该请求(有些交易所不支持杠杆业务) 33020 400
币与币对不匹配 33021 400
币对与订单不匹配 33022 400
价格发现期间您只可下市价单(集合竞价时只可以下市价单) 33023 400
交易金额小于最小交易值 33024 400
没有基准币数量(下单时上币时候币对配置不全) 33025 400
订单已完成交易(撤单时完成交易的订单不能撤单) 33026 400
订单已撤销或者撤销中(撤单时已经撤销和撤销中的订单不能撤单) 33027 400
交易价格小数位数超过限制 33028 400
交易数量小数位数超过限制 33029 400
client_oid 或 order_id 至少填一个 33059 400
client_oid 或 order_id 必须且只能填一个 33060 400
集合竞价开始后只能下限价单 33034 400
该委托类型无法进行撤单操作(fok ioc 订单无法撤销) 33035 400
超过最大限制数量 33036 400
买单委托价格需小于等于触发价格的130% 33037 400
卖单委托价格需大于等于触发价格的70% 33038 400
回调幅度限制为0<x<=5% 33039 400
买单激活价格需小于最新成交价格 33040 400
卖单激活价格需大于最新成交价格 33041 400
委托深度限制为0<x<=1% 33042 400
委托总数需要大于0 33043 400
单笔均值 委托总数 1/1000 <=x<=委托总数 33044 400
价格不能为0 包括:触发价格,委托价格,激活价格,价格限制 33045 400
扫单范围应该为 0<x<=1% 33046 400
扫单比例应该为0<x<=100% 33047 400
单笔上限:1/1000<x<=委托总数 33048 400
委托总量应为 X>0 33049 400
委托间隔应该为 5<= x<=120s 33050 400
撤销数量不能超过限制:止盈止损和跟踪委托不超过10单,冰山委托和时间加权委托不超过6单 33051 400
两个参数必须填一个 33059 400
两个参数只能填一个 33060 400
市价委托单笔价值不能超过10万 USD 33061 400

交割合约错误码(32000-33000)

错误提示 错误码 http状态码
合约账户被冻结(当用户合约账户被冻结时) 32001 400
用户合约账户不存在(当用户只是注册了账号没有开通合约) 32002 400
撤单中,请耐心等待 32003 400
您当前没有未成交的订单(当用户查询未成交订单时) 32004 400
超过最大下单量(当用户下单量超过规定数量会出现该异常) 32005 400
委托价格或触发价格超过100万美元(下单当用户委托价格或触发价格超过100万美元) 32006 400
合约相同方向只支持一个杠杆,当用户有10倍杠杆的持仓,在开20倍的时候等 32007 400
当前最多可开仓位(全仓), 当用户开仓(全仓)的时候大于最多可开仓位 32008 400
当前最多可开仓位(逐仓),当用户开仓(逐仓)的时候大于最多可开仓位 32009 400
当前有持仓,无法设置杠杆 32010 400
虚拟合约状态错误,使用了过期的合约 32011 400
合约撤单失败,系统异常时,撤单失败 32012 400
币种类型为空 32013 400
您的平仓张数大于该仓位的可平张数 32014 400
开仓前保证金率低,开仓的是保证金率低于100% 32015 400
开仓后保证金率低,开仓后的是保证金率低于100% 32016 400
暂无对手价 32017 400
下单数量不足1张,请重新选择 32018 400
下单价格高于前一分钟的103%或低于97% 32019 400
价格不在限价范围内 32020 400
杠杆比率错误,设置杆杆的时候不是设置的10倍或者20倍 32021 400
根据相关法律,您所在的国家或地区不能使用该功能,有的地区不能开合约 32022 400
账户存在借款 32023 400
合约交割中,无法下单 32024 400
合约清算中,无法下单,清算的时候无法下单 32025 400
您的账户已被限制开仓操作,禁止开仓 32026 400
撤单数量超过20 32027 400
用户被强平冻结 32028 400
client_oid 或order_id只能传一个 32029 400
该委托类型无法进行撤单操作 32030 400
client_oid 或者 order_id是必要的参数 32031 400
用户不存在 32038 400
用户存在挂单或持仓 32040 400
当前仓位不存在 32041 400
超过保证金最大/最小限额 32042 400
账户模式不正确 32043 400
下单后保证金率小于对应档位要求的最低保证金率 32044 400
委托数量超过100万 32045 400
每个用户最多可同时持有10笔未成交的止盈止损 32046 400
系统错误(当合约暂停或者极端情况会出现) 32047 400
跟踪委托回调幅度错误 32048 400
每个用户最多可同时持有10笔未成交的跟踪委托 32049 400
回调幅度错误 32050 400
冰山委托深度错误 32051 400
委托数量超过10万 32052 400
每个用户最多可同时持有6笔未成交的冰山委托 32053 400
禁止开仓 32054 400
撤单失败 32055 400
冰山委托单笔均值() 32056 400
委托价为0,暂无法进行市价全平操作 32057 400
每个用户最多可同时持有6笔未成交的时间加权 32058 400
委托总数量需大于单笔上限 32059 400
下单类型错误 32060 400
时间加权单笔上限错误(时间加权单笔上线错误) 32061 400
时间加权扫单范围出错 32062 400
时间加权扫单比例出错 32063 400
委托间隔错误,5-120s之间 32064 400
市价全平的数量大于阈值(BTC 最多为 999 张,其他合约未 9999 张) 32065 400
当前存在挂单,请撤销所有挂单后进行杠杆倍数修改 32066 400
调整后,账户权益<所需保证金,请重新调整杠杆倍数 32067 400
调整后本仓位保证金不足开仓所需保证金,请重新调整杠杆倍数或追加保证金后调整 32068 400
杠杆倍数过低,账户中没有足够的可用保证金可以追加(请重新调整杠杆倍数) 32069 400
用户有持仓或者挂单(取消持仓或挂单) 32070 400
您的当前强平模型不支持此操作 32071 400
您下单后仓位总张数所处档位的最高可用杠杆为{0}(请修改杠杆后重新下单) 32072 400
当前币种不支持此操作 32073 400
您当前持仓、开仓挂单及本次下单张数已超过该币种最大限制可开张数 32074 400
账户风险率过高 32075 400
市价全平需先进行撤销平仓挂单操作(市价全平需先进行撤销平仓挂单操作) 32076 400
您该币种合约账户保证金不足,已触发强制平仓 32077 400
您在该币种下存在挂单,请撤销所有挂单后切换 32078 400
当前仓位风险过高,请增加保证金或减少仓位后切换 32079 400
交割结算后30分钟内不能转出 32080 400
错误码示例
错误提示 错误码 http状态码
系统错误, 一般是路径参数有误 1 400
合约不存在,用户调用不存在的合约时 35001 400
合约正在结算时 35002 400
合约暂停 35003 400
合约待资金结算 35004 400
用户不存在,用户未开通合约时 35005 400
账户风险率过高,用户下单前后保证金率不足时 35008 400
平仓数量大于可平数量(用户下平仓单数量大于可平数量时) 35010 400
下单数量错误(用户下单数量不足1张时) 35012 400
下单价格不在限价范围(用户下单价格不在限价范围里时) 35014 400
杠杆倍数超过允许范围(用户调整的杠杆不在范围内时) 35015 400
用户存在挂单(用户修改杠杆时) 35017 400
下单数量超过最大允许的数量(用户下单数量超过设置的最大值时) 35019 400
下单价格超过最大允许的价格(用户下单价格超过设置的最大值时) 35020 400
下单数量超过用户当前档位(用户下单数量超过当前档位的最大值时) 35021 400
合约状态错误(合约处于暂停或关闭状态时) 35022 400
该用户合约未初始化 35024 400
用户账户余额为空 35025 400
用户合约配置未初始化 35026 400
订单不存在 35029 400
批量下单时,超过最大下单数量 35030 400
批量撤单时,超过最大撤单数量 35031 400
用户状态无效 35032 400
缓存中无最新成交价 35037 400
开仓张数大于可开张数 35039 400
无效的order type,当以对手价下单时,order_type只能选择0:普通委托 35040 400
订单已完成,无法撤单 35044
账户余额是负数 35046 400
账户余额不足 35047 400
用户合约正在强平冻结 35048 400
订单类型不合适 35049 400
档位配置为空 35050 400
全仓保证金不足 35052 400
账户风险过高 35053 400
账户余额不足 35055 400
无最新成交 35057 400
无限价 35058 400
必传参数不能为空 30023 400
参数错误 30024 400
两个参数必须填一个(order id和client id 必须填一个) 35059 400
两个参数只能填一个(order id和client id 只能填一个) 35060 400
instrument_id 不正确 35061 400
match_price 不正确 35062 400
order_size 不正确 35063 400
instrument_id 不正确 35064 400
结算后30分钟内不能转出 40029 400
委托间隔错误 35066 400
时间加权扫单比例错误 35067 400
时间加权扫单范围错误 35068 400
时间加权单笔上限错误 35069 400
策略委托类型错误 35070 400
委托总数量需大于单笔上限 35071 400
每个用户最多可同时持有6笔未成交的时间加权单 35072 400
委托价为0,暂无法进行市价全平操作 35073 400
冰山委托单笔均值错误 35074 400
撤单失败 35075 400
LTC20倍杠杆、禁止开仓 35076 400
每个用户最多可同时持有6笔未成交的冰山委托 35077 400
委托数量超过10万 35078 400
冰山委托深度错误 35079 400
回调幅度错误 35080 400
跟踪委托回调幅度错误 35081 400
您当前持仓、开仓挂单及本次下单张数已超过该币种最大限制可开张数 35082 400
每个用户最多可同时持有10笔未成交的止盈止损单 35083 400
委托数量超过100万 35084 400
委托数量不在正确范围内 35085 400
价格超过100万 35086 400
价格超过100万 35087 400
单笔均值错误 35088 400
价格超过100万 35089 400
没有可以撤的止盈止损单 35090 400
没有可以撤的跟踪委托单 35091 400
没有可以撤的冰山委托单 35092 400
没有可以撤的时间加权委托单 35093 400
止盈止损单最新成交价错误 35094 400
合约名非法 35095 400
策略委托订单状态错误 35096 400
订单状态和订单id不能同时存在 35097 400
订单状态或订单id必须存在一个 35098 400
策略委托订单id错误 35099 400

WebsocketAPI

现货

以下是现货V3 WebscoketAPI,除了account有单独频道,其余频道数据对币币和杠杆用户通用。

概述

WebSocket是HTML5一种新的协议(Protocol)。它实现了客户端与服务器全双工通信, 使得数据可以快速地双向传播。通过一次简单的握手就可以建立客户端和服务器连接, 服务器根据业务规则可以主动推送信息给客户端。其优点如下:

  • 客户端和服务器进行数据传输时,请求头信息比较小,大概2个字节。
  • 客户端和服务器皆可以主动地发送数据给对方。
  • 不需要多次创建TCP请求和销毁,节约宽带和服务器的资源。

强烈建议开发者使用WebSocket API获取市场行情和买卖深度等信息。

地址:wss://real.okex.com:8443/ws/v3

访问时需要科学上网

连接说明:

所有返回数据都进行了压缩,需要用户将接收到的数据进行解压。解压缩请参考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 频道首次会接收到200档深度,后续推送的都是增量数据。checksum值为:每次增量更新合并后此200档深度的前25档bids和asks组成的字符串的crc32值, 用户可以拿自己的checksum的值和订阅的checksum值进行比较,如果不匹配可以重新订阅。

深度合并规则说明: 首次发送200档深度数据,后续每次发送增量的数据,拿增量去遍历200档中的ask和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 频道用户收到推送数据为:

首次200档


{
    "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/trade // 交易信息频道

spot/depth //深度数据频道,首次200档,后续增量

spot/depth5 //深度数据频道,每次返回前5档

需登录的频道如下

spot/account //用户币币账户信息频道

spot/margin_account //用户杠杆账户信息频道

spot/order //用户交易数据频道

用户币币账户频道

获取币币账户信息,需用用户登录

send示例
{"op": "subscribe", "args": ["spot/account:BTC"]}

其中spot/account为频道名,BTCcurrency

返回参数
参数名 类型 描述
currency String 币种
balance String 余额
hold String 冻结(不可用)
available 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-USDTinstrument_id

返回参数
参数名 类型 描述
instrument_id String 杠杆币对名称
balance String 余额
hold String 冻结(不可用)
available String 可用于交易或资金划转的数量
borrowed String 已借币(已借未还的部分)
lending_fee String 利息(未还的利息)
返回示例
{
    "table":"spot/margin_account",
    "data":[
        {
            "currency:USDT":{
                "available":"95.4675",
                "balance":"100",
                "borrowed":"0",
                "hold":"4.5325",
                "lending_fee":"0"
            },
            "currency:BTC":{
                "available":"0",
                "balance":"0",
                "borrowed":"0",
                "hold":"0",
                "lending_fee":"0"
            },
            "instrument_id":"BTC-USDT"
        }
    ]
}

用户交易频道

获取用户交易数据,需用用户登录

send示例
{"op": "subscribe", "args": ["spot/order:LTC-USDT"]}

其中spot/order为频道名,LTC-USDTinstrument_id

返回参数
参数名 类型 描述
order_id String 订单ID
client_oid String 由用户设置的订单ID
price String 委托价格
size String 委托数量(交易货币数量)
notional String 买入金额,市价买入时返回
instrument_id String 币对名称
side String buysell
type String limitmarket(默认是limit
timestamp String 订单状态更新时间
filled_size String 已成交数量
filled_notional String 已成交金额
margin_trading String 1:币币交易订单
2:杠杆交易订单
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:撤单中
created_at String 订单创建时间
解释说明

statusstate旧版参数,会短期兼容,建议尽早切换state

返回示例
{
    "table":"spot/order",
    "data":[
        {
            "client_oid":"",
            "filled_notional":"0",
            "filled_size":"0",
            "instrument_id":"ETC-USDT",
            "last_fill_px":"0",
            "last_fill_qty":"0",
            "last_fill_time":"1970-01-01T00:00:00.000Z",
            "margin_trading":"1",
            "notional":"",
            "order_id":"3576398568830976",
            "order_type":"0",
            "price":"5.826",
            "side":"buy",
            "size":"0.1",
            "state":"0",
            "status":"open",
            "timestamp":"2019-09-24T06:45:11.394Z",
            "type":"limit",
            "created_at":"2019-09-24T06:45:11.394Z"
        }
    ]
}

公共-Ticker频道

获取现货最新成交价、买一价、卖一价和24交易量

send示例
{"op": "subscribe", "args": ["spot/ticker:ETH-USDT"]}

其中spot/ticker为频道名,ETH-USDTinstrument_id

返回参数
参数名 参数类型 描述
instrument_id String 币对名称
last String 最新成交价
best_bid String 买一价
best_ask 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":"162.09",
            "best_bid":"162.1",
            "best_ask":"162.12",
            "open_24h":"165.35",
            "high_24h":"166.55",
            "low_24h":"155.69",
            "base_volume_24h":"620062.9352195",
            "quote_volume_24h":"100084770.34604578",
            "timestamp":"2019-04-16T10:44:06.090Z"
        }
    ]
}

公共-K线频道

获取现货的K线数据

频道列表:

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/candle21600 // 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-USDTinstrument_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-USDTinstrument_id

返回参数
参数名 参数类型 描述
trade_id String 成交id
price String 成交价格
size String 成交数量
side String 成交方向(buysell
timestamp String 成交时间
instrument_id String 币对
返回示例
{
    "table":"spot/trade",
    "data":[
        {
            "instrument_id":"ETH-USDT",
            "price":"162.12",
            "side":"buy",
            "size":"11.085",
            "timestamp":"2019-04-16T10:58:17.122Z",
            "trade_id":"1210447366"
        },
        {
            "instrument_id":"ETH-USDT",
            "price":"162.12",
            "side":"buy",
            "size":"8.31375",
            "timestamp":"2019-04-16T10:58:17.122Z",
            "trade_id":"1210447371"
        }
    ]
}

公共-5档深度频道

每次返回前五档的深度数据,此数据为每100毫秒的快照数据,即每隔100毫秒,快照当前时刻市场订单薄的5档深度数据并推送。

send示例
{"op": "subscribe", "args": ["spot/depth5:ETH-USDT"]}

其中spot/depth5为频道名,ETH-USDTinstrument_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"
        }
    ]
}

公共-200档深度频道

订阅后首次返回市场订单薄的200档深度数据并推送;然后每隔100毫秒,快照这个时间段内有更改的订单薄数据,并推送。

send示例
{"op": "subscribe", "args": ["spot/depth:ETH-USDT"]}

其中spot/depth为频道名,ETH-USDTinstrument_id

返回参数
参数名 参数类型 描述
asks List<String> 卖方深度
bids List<String> 买方深度
timestamp String 时间戳
instrument_id String 币对
checksum String 检验和

asks和bids值数组举例说明: [“411.8”,”10”,8”] 411.8为深度价格,10为此价格数量,8为此深度由几笔订单组成。

返回示例
首次200档
{
    "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
        }
    ]
}

交割合约

以下是交割合约V3 WebscoketAPI

概述

WebSocket是HTML5一种新的协议(Protocol)。它实现了客户端与服务器全双工通信, 使得数据可以快速地双向传播。通过一次简单的握手就可以建立客户端和服务器连接, 服务器根据业务规则可以主动推送信息给客户端。其优点如下:

  • 客户端和服务器进行数据传输时,请求头信息比较小,大概2个字节。
  • 客户端和服务器皆可以主动地发送数据给对方。
  • 不需要多次创建TCP请求和销毁,节约宽带和服务器的资源。

强烈建议开发者使用WebSocket API获取市场行情和买卖深度等信息。

地址:wss://real.okex.com:8443/ws/v3

访问时需要科学上网

连接说明:

所有返回数据都进行了压缩,需要用户将接收到的数据进行解压。解压缩请参考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>"}]"}

其中futures/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为futures, channel为此业务下每个具体的名称,如果channel的名字不能以一个字母区分将会以 " _ " 进行连接

例:

"futures/ticker:BTC-USD-170310"or "futures/price_range:BTC-USD-170310"

filter 是可筛选数据,具体参考每个频道说明

示例:

send:

{"op": "subscribe", "args": ["futures/ticker:BTC-USD-170310", "futures/candle60s:BTC-USD-170310"]}

response:

 {"event":"subscribe","channel":"futures/ticker:BTC-USD-170310"}

 {"event":"subscribe","channel":"futures/candle60s:BTC-USD-170310"}

 {"table":"futures/ticker","data":[{"last":3916.9594,"best_bid":3916.508,"high_24h":3918.1759,
 "low_24h":3916.508,"volume_24h":234,"best_ask":3916.9614,"instrument_id":"BTC-USD-170310","timestamp":"2018-12-20T02:33:01.448Z"}]}

 {"table":"futures/candle60s","data":[{"candle":["2018-12-20T02:35:00.000Z","3916.9594",
 "3916.9594","3916.9594","3916.9594","0","0.0"],"instrument_id":"BTC-USD-170310"}]}

取消订阅

可以取消一个或者多个频道

{"op": "unsubscribe", "args": [<SubscriptionTopic>]}

例如:

请求:

{"op": "unsubscribe", "args": ["futures/ticker:BTC-USD-170310", "futures/candle60s:BTC-USD-170310"]}

返回:

{"event":"unsubscribe","channel":"futures/ticker:BTC-USD-170310"}
{"event":"unsubscribe","channel":"futures/candle60s:BTC-USD-170310"}

登录

签名方式说明参考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 频道首次会接收到400档深度,后续推送的都是增量数据。checksum值为:每次增量更新后此400档深度的前 25档 bids 和 asks组成的字符串的crc32值, 用户可以拿自己的checksum的值和订阅的checksum值进行比较,如果不匹配可以重新订阅。

深度合并规则说明: 首次发送400档深度数据,后续每次发送增量的数据。去遍历400档中的ask和bids的price ,如果发现有相同价格 则看数量,数量为0删除此深度,数量有变化则替换此数据; 无相同价格则按照顺序排序。

计算说明: checksum的值为有符号整型(32位)

checksum的字符串都是以冒号连接的ask和bid中的price和数量,例如:

例子1:bid和ask成对档的情况下,要校验的字符串为:bid:ask:bid:ask:...


"data": [{
        "instrument_id": "BTC-USD-181228",
        "asks": [[3366.8, 9, 10, 3],[ 3368,8,3,4 ]],
        "bids": [
            [3366.1, 7, 0, 3],[ 3366,6,3,4 ]
        ],
        "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-USD-181228,
        "asks": [[3366.8, 9, 10, 3],[ 3368,8,3,4 ],[ 3372,8,3,4 ]],
        "bids": [
            [3366.1, 7, 0, 3]
        ],
        "timestamp": "2018-12-04T09:38:36.300Z",
        "checksum": 831078360
    }]

此例子对应的checksum String 将会是 3366.1:7:3366.8:9:3368:8:3372:8

depth 频道用户收到推送数据为:

首次400档


{
    "table": "futures/depth",
    "action": "partial",
    "data": [{
        "instrument_id": "BTC-USD-181228",
        "asks": [[3983, 888, 10, 3],....],
        "bids": [
            [3983, 789, 0, 3],....
        ],
        "timestamp": "2018-12-04T09:38:36.300Z",
        "checksum": 200119424
    }]
}

后续更新:

{
    "table": "futures/depth",
    "action": "update",
    "data": [{
        "instrument_id": "BTC-USD-181228",
        "asks": [],
        "bids": [
            [3983, 789, 0, 3]
        ],
        "timestamp": "2018-12-04T09:38:36.300Z",
        "checksum": -1200119424
    }]
}

频道说明

无需登录的频道包括:行情频道,K线频道,交易数据频道,资金费率频道,限价范围频道,深度数据频道,标记价格频道

需登录的频道包括:用户账户频道,用户交易频道,用户持仓频道

无需登录的频道名称如下:

futures/ticker // 行情数据频道

futures/candle60s // 1分钟k线数据频道

futures/trade // 交易信息频道

futures/estimated_price //获取预估交割价

futures/price_range //限价范围频道

futures/depth_l2_tbt //全量深度数据频道,首次全部深度数据,后续有更改的数据。

futures/depth //深度数据频道,首次200档,后续有更改的数据。

futures/depth5 //深度数据频道,每次返回前5档。

futures/mark_price// 标记价格频道

需登录的频道如下

futures/account //用户账户信息频道

futures/position //用户持仓信息频道

futures/order //用户交易数据频道

用户持仓频道

获取用户持仓信息,需用用户登录

send示例
{"op": "subscribe", "args": ["futures/position:BTC-USD-170317"]}

其中futures/position为频道名,BTC-USD-170317instrument_id

返回参数
逐仓参数名 参数类型 描述
margin_mode String 账户类型
逐仓:fixed
long_qty String 多仓数量
long_avail_qty String 多仓可平仓数量
long_margin String 多仓保证金
long_liqui_price String 多仓强平价格
long_pnl_ratio String 多仓盈亏比
long_avg_cost String 开仓平均价
long_settlement_price String 结算基准价
realised_pnl String 已实现盈余
long_leverage String 多仓杠杆倍数
short_qty String 空仓数量
short_avail_qty String 空仓可平仓数量
short_margin String 空仓保证金
short_liqui_price String 空仓强平价格
short_pnl_ratio String 空仓盈亏比
short_avg_cost String 开仓平均价
short_settlement_price String 结算基准价
short_leverage String 空仓杠杆倍数
instrument_id String 合约ID,如BTC-USDT-180909
created_at String 创建时间
updated_at String 更新时间
short_margin_ratio String 空仓保证金率
short_maint_margin_ratio String 空仓维持保证金率
short_pnl String 空仓收益
short_unrealised_pnl String 空仓未实现盈亏
short_open_outstanding string 空仓开仓冻结张数
short_settled_pnl String 空仓已结算收益
long_margin_ratio String 多仓保证金率
long_maint_margin_ratio String 多仓维持保证金率
long_pnl String 多仓收益
long_unrealised_pnl String 多仓未实现盈亏
long_open_outstanding string 多仓开仓冻结张数
long_settled_pnl String 多仓已结算收益
last String 最新成交价
逐仓返回示例
{
    "table":"futures/position",
    "data":[
        {
            "long_qty":"0",
            "long_avail_qty":"0",
            "long_margin":"0",
            "long_liqui_price":"0",
            "long_pnl_ratio":"0.36112873",
            "long_avg_cost":"9840.02",
            "long_settlement_price":"9840.02",
            "realised_pnl":"0",
            "short_qty":"0",
            "short_avail_qty":"0",
            "short_margin":"0",
            "short_liqui_price":"0",
            "short_pnl_ratio":"-0.33163704",
            "short_avg_cost":"9870.15",
            "short_settlement_price":"9870.15",
            "instrument_id":"BTC-USD-190927",
            "long_leverage":"10",
            "short_leverage":"10",
            "created_at":"2019-09-06T03:39:50.019Z",
            "updated_at":"2019-09-20T10:32:56.003Z",
            "timestamp":"2019-09-20T10:32:56.003Z",
            "margin_mode":"fixed",
            "short_margin_ratio":"10000.0",
            "short_maint_margin_ratio":"0.005",
            "short_pnl":"0.0",
            "short_unrealised_pnl":"0.0",
            "long_margin_ratio":"10000.0",
            "long_maint_margin_ratio":"0.005",
            "long_pnl":"0.0",
            "long_unrealised_pnl":"0.0",
            "long_open_outstanding":"2",
            "short_open_outstanding":"0",
            "long_settled_pnl":"0",
            "short_settled_pnl":"0",
            "last":"10206.46"
        }
    ]
}
返回参数
全仓参数名 参数类型 描述
margin_mode String 账户类型
全仓:crossed
liquidation_price String 预估强平价
long_qty String 多仓数量
long_avail_qty String 多仓可平仓数量
long_avg_cost String 开仓平均价
long_settlement_price String 结算基准价
realised_pnl String 已实现盈余
leverage String 杠杆倍数
short_qty String 空仓数量
short_avail_qty String 空仓可平仓数量
short_avg_cost String 开仓平均价
short_settlement_price String 结算基准价
instrument_id String 合约ID,如BTC-USDT-180213
created_at String 创建时间
updated_at String 更新时间
short_margin String 空仓保证金
short_pnl String 空仓收益
short_pnl_ratio String 空仓收益率
short_unrealised_pnl String 空仓未实现盈亏
long_margin String 多仓保证金
long_pnl String 多仓收益
long_pnl_ratio String 多仓收益率
long_unrealised_pnl String 多仓未实现盈亏
long_open_outstanding string 多仓开仓冻结张数
short_open_outstanding string 空仓开仓冻结张数
long_settled_pnl String 多仓已结算收益
short_settled_pnl String 空仓已结算收益
last String 最新成交价
全仓返回示例
{
    "table":"futures/position",
    "data":[
        {
            "long_qty":"0",
            "long_avail_qty":"0",
            "long_avg_cost":"10195.63",
            "long_settlement_price":"10195.63",
            "realised_pnl":"0",
            "short_qty":"0",
            "short_avail_qty":"0",
            "short_avg_cost":"10868.07",
            "short_settlement_price":"10868.07",
            "liquidation_price":"0.0",
            "instrument_id":"BTC-USD-190927",
            "leverage":"10",
            "created_at":"2019-09-06T03:39:50.019Z",
            "updated_at":"2019-09-19T03:54:16.570Z",
            "timestamp":"2019-09-19T03:54:16.570Z",
            "margin_mode":"crossed",
            "short_margin":"0.0",
            "short_pnl":"0.0",
            "short_pnl_ratio":"1.04333472",
            "short_unrealised_pnl":"0.0",
            "long_margin":"0.0",
            "long_pnl":"0.0",
            "long_pnl_ratio":"-0.359905739",
            "long_unrealised_pnl":"0.0",
            "long_open_outstanding":"2",
            "short_open_outstanding":"0",
            "long_settled_pnl":"0",
            "short_settled_pnl":"0",
            "last":"9840.19"
        }
    ]
}

用户账户频道

获取账户信息,需用用户登录

send示例
{"op": "subscribe", "args": ["futures/account:BTC"]}

其中futures/account为频道名,BTCtoken

返回参数
全仓参数名 参数类型 描述
currency String 币种,如:btc
margin_mode String 账户类型
全仓:crossed
equity String 账户权益
total_avail_balance String 账户余额
margin String 已用保证金
realized_pnl String 已实现盈亏
unrealized_pnl String 未实现盈亏
margin_ratio String 保证金率
margin_frozen String 持仓已用保证金
margin_for_unfilled String 挂单冻结保证金
maint_margin_ratio String 维持保证金率
liqui_mode string 强平模式:tier(梯度强平)
available string 可用保证金
open_max string 最大可开张数
can_withdraw string 可划转数量
全仓返回示例
{
    "table":"futures/account",
    "data":[
        {
            "BTC":{
                "equity":"0.02025145",
                "margin":"0",
                "realized_pnl":"0.00011304",
                "unrealized_pnl":"0",
                "margin_ratio":"10000",
                "margin_mode":"crossed",
                "total_avail_balance":"0.02013841",
                "margin_frozen":"0",
                "margin_for_unfilled":"0",
                "liqui_mode":"tier",
                "maint_margin_ratio":"0.005",
                "available":"0.02025145",
                "open_max":"20",
                "can_withdraw":"0.02013841",
                "timestamp":"2019-09-18T08:00:26.000Z"
            }
        }
    ]
}
返回参数
逐仓参数名 参数类型 描述
currency String 币种,如:btc
margin_mode String 账户类型
逐仓:fixed
instrument_id String 合约ID,如BTC-USD-191227
fixed_balance String 逐仓账户余额
available_qty String 逐仓可用余额
margin_frozen String 冻结的保证金(成交以后仓位所需的)
margin_for_unfilled String 挂单冻结保证金
realized_pnl String 已实现盈亏
unrealized_pnl String 未实现盈亏
equity String 账户权益(账户动态权益)
total_avail_balance String 账户余额(账户静态权益)
liqui_mode string 强平模式
tier(梯度强平)
long_open_max string 多仓最大可开张数
short_open_max string 空仓最大可开张数
can_withdraw string 可划转数量
逐仓返回示例
{
    "table":"futures/account",
    "data":[
        {
            "BTC":{
                "can_withdraw":"0.01705705",
                "contracts":[
                    {
                        "available_qty":"0.01705705",
                        "fixed_balance":"0",
                        "instrument_id":"BTC-USD-190927",
                        "long_open_max":"14",
                        "margin_for_unfilled":"0",
                        "margin_frozen":"0",
                        "realized_pnl":"0",
                        "short_open_max":"14",
                        "timestamp":"2019-09-24T08:00:23.107Z",
                        "unrealized_pnl":"0"
                    },
                    {
                        "available_qty":"0.01705705",
                        "fixed_balance":"0",
                        "instrument_id":"BTC-USD-191227",
                        "long_open_max":"14",
                        "margin_for_unfilled":"0.00236563",
                        "margin_frozen":"0",
                        "realized_pnl":"0",
                        "short_open_max":"14",
                        "timestamp":"2019-09-25T07:58:42.145Z",
                        "unrealized_pnl":"0"
                    }
                ],
                "equity":"0.01942268",
                "liqui_mode":"tier",
                "margin_mode":"fixed",
                "timestamp":"2019-09-25T07:58:42.000Z",
                "total_avail_balance":"0.01942268"
            }
        }
    ]
}

用户交易频道

获取用户交易数据,需用用户登录

send示例
{"op": "subscribe", "args": ["futures/order:BTC-USD-170317"]}

其中futures/order为频道名,BTC-USD-170317instrument_id

返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USDT-180213
client_oid String 由用户设置的订单ID
size String 委托数量
timestamp String 订单状态变化时间
filled_qty String 成交数量
fee String 手续费
order_id String 订单ID
price String 委托价格
price_avg String 成交均价
type String 订单类型
1:开多
2:开空
3:平多
4:平空
contract_val String 合约面值
leverage String 杠杆倍数
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:撤单中
trade_id String 账单ID
解释说明

timestamp会根据订单状态变化分别返回相应的创建时间、成交时间、撤销时间等,具体状态用户可根据state参数判断。

statusstate旧版参数,会短期兼容,建议尽早切换state

system_type:即将被弃用,请使用文档上的字段。

返回示例
{
    "table":"futures/order",
    "data":[
        {
            "leverage":"10",
            "last_fill_time":"1970-01-01T00:00:00.000Z",
            "filled_qty":"0",
            "fee":"0",
            "price_avg":"0.0",
            "type":"2",
            "client_oid":"",
            "last_fill_qty":"0",
            "instrument_id":"BTC-USD-190927",
            "last_fill_px":"0",
            "trade_id":"",
            "size":"2",
            "system_type":0,
            "price":"9870.15",
            "state":"0",
            "contract_val":"100",
            "order_id":"3549018511389696",
            "order_type":"0",
            "timestamp":"2019-09-19T10:42:04.845Z",
            "status":"0"
        }
    ]
}

公共-全量合约信息频道

全量合约订阅频道

每次交割过后有新合约上线且可交易后,就推一次所有币种的全量合约数据(无需登录)。

send示例
{"op": "subscribe", "args": ["futures/instruments"]}

其中futures/instruments为频道名

返回参数
参数名 参数类型 描述
instrument_id String 合约ID,如BTC-USD-190322
underlying_index String 交易货币币种,如:BTC-USD-190322中的BTC
quote_currency String 计价货币币种,如:BTC-USD-190322中的USD
contract_val String 合约面值(美元)
listing String 上线日期
delivery String 交割日期
tick_size String 下单价格精度
trade_increment String 下单数量精度
alias String 本周: this_week
次周: next_week
季度: quarter
返回示例


{
    "table": "futures/instruments",
    "data": [
        [
            {
                "instrument_id": "BTC-USD-190809",
                "underlying_index": "BTC",
                "quote_currency": "USD",
                "tick_size": "0.01",
                "contract_val": "100",
                "listing": "2019-07-26",
                "delivery": "2019-08-09",
                "trade_increment": "1",
                "alias": "next_week"
            },
            {
                "instrument_id": "BTC-USD-190927",
                "underlying_index": "BTC",
                "quote_currency": "USD",
                "tick_size": "0.01",
                "contract_val": "100",
                "listing": "2019-06-14",
                "delivery": "2019-09-27",
                "trade_increment": "1",
                "alias": "quarter"
            }
        ]
    ]
}

公共-Ticker频道

获取合约的最新成交价、买一价、卖一价和24交易量等信息。

send示例
{"op": "subscribe", "args": ["futures/ticker:BTC-USD-170310"]}

其中futures/ticker为频道名,BTC-USD-170310instrument_id

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-170310
last String 最新成交价
best_ask String 卖一价
best_bid String 买一价
high_24h String 24小时最高价
low_24h String 24小时最低价
volume_24h String 24小时成交量(按张数统计)
timestamp String 系统时间戳
open_interest String 持仓量
open_24h String 24小时开盘价
volume_token_24h String 成交量(按币统计)
返回示例
{
    "table":"futures/ticker",
    "data":[
        {
            "last":"8493.94",
            "best_bid":"8493.94",
            "high_24h":"10020",
            "low_24h":"7560.63",
            "volume_24h":"32978462",
            "open_interest":"4116037",
            "best_ask":"8494.98",
            "instrument_id":"BTC-USD-191227",
            "open_24h":"9992.43",
            "timestamp":"2019-09-25T09:34:51.505Z",
            "volume_token_24h":"388258.71150490816"
        }
    ]
}

公共-K线频道

获取合约的K线数据

频道列表:

futures/candle60s // 1分钟k线数据频道

futures/candle180s // 3分钟k线数据频道

futures/candle300s // 5分钟k线数据频道

futures/candle900s // 15分钟k线数据频道

futures/candle1800s // 30分钟k线数据频道

futures/candle3600s // 1小时k线数据频道

futures/candle7200s // 2小时k线数据频道

futures/candle14400s // 4小时k线数据频道

futures/candle21600 // 6小时k线数据频道

futures/candle43200s // 12小时k线数据频道

futures/candle86400s // 1dayk线数据频道

futures/candle604800s // 1week k线数据频道

send示例
{"op": "subscribe", "args": ["futures/candle180s:BTC-USD-191227"]}

其中futures/candle180s为频道名,BTC-USD-191227instrument_id

返回参数
参数名 参数类型 描述
timestamp String 开始时间
open String 开盘价格
high String 最高价格
low String 最低价格
close String 收盘价格
volume String 交易量(张)
currency_volume String 按币折算的交易量
instrument_id String 合约BTC-USD-170310
返回示例
{
    "table":"futures/candle180s",
    "data":[
        {
            "candle":[
                "2019-09-25T10:00:00.000Z",
                "8533.02",
                "8553.74",
                "8527.17",
                "8548.26",
                "45247",
                "529.5858061"
            ],
            "instrument_id":"BTC-USD-191227"
        }
    ]
}

公共-交易频道

获取最近的成交数据。

send示例
{"op": "subscribe", "args": ["futures/trade:BTC-USD-170310"]}

其中futures/trade为频道名,BTC-USD-170310instrument_id

返回参数
参数名 参数类型 描述
trade_id String 成交id
price String 成交价格
qty String 成交数量
side String 成交方向(buysell
timestamp String 成交时间
instrument_id String 合约ID,如BTC-USD-170310
返回示例

{
    "table": "futures/trade",
    "data": [{
        "side": "buy",
        "trade_id": "2778148208082945",
        "price": "5556.91",
        "qty": "5",
        "instrument_id": "BTC-USD-190628",
        "timestamp": "2019-05-06T07:19:37.496Z"
    }]
}

公共-预估交割价频道

获取预估交割价

send示例
{"op": "subscribe", "args": ["futures/estimated_price:BTC-USD-170310"]}

其中futures/estimated_price为频道名,BTC-USD-170310instrument_id

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-170310
settlement_price String 预估交割价格
timestamp String 系统时间戳
返回示例
{
        ”table”: "futures/estimated_price”,
        ”data”: [{
                ”instrument_id”: "BTC-USD-170310”,
                ”settlement_price”: "22616.58”,
                ”timestamp”: "2018-11-22T10:09:31.541Z”
        }]
}

公共-限价频道

获取合约当前交易的最高买价和最低卖价。

send示例
{"op": "subscribe", "args": ["futures/price_range:BTC-USD-170310"]}

其中futures/price_range为频道名,BTC-USD-170310instrument_id

返回参数
参数名 参数类型 描述
timestamp String 系统时间戳
lowest String 最低卖价
instrument_id String 合约名称,如BTC-USD-170310
highest String 最高买价
返回示例
{
    "table": "futures/price_range",
    "data": [{
        "highest": "5729.32",
        "lowest": "5392.32",
        "instrument_id": "BTC-USD-190628",
        "timestamp": "2019-05-06T07:19:35.004Z"
    }]
}

公共-5档深度频道

每次返回前五档的深度数据,此数据为每100毫秒的快照数据,即每隔100毫秒,快照当前时刻市场订单薄的5档深度数据并推送。

send示例
{"op": "subscribe", "args": ["futures/depth5:BTC-USD-190628"]}

其中futures/depth5为频道名,BTC-USD-190628instrument_id

返回参数
参数名 参数类型 描述
asks List<String> 卖方深度
bids List<String> 买方深度
timestamp String 时间戳
instrument_id String 合约ID,如BTC-USD-190628

asks和bids值数组举例说明:

["411.8", "10", "1", "4"] 411.8为深度价格,10为此价格的合约张数,1为此价格的强平单个数,4为此价格的订单个数。

返回示例
{
    "table": "futures/depth5",
    "data": [{
        "asks": [
            ["5556.82", "11", "0", "1"],
            ["5556.84", "98", "0", "4"],
            ["5556.92", "1", "0", "1"],
            ["5557.6", "4", "0", "1"],
            ["5557.85", "2", "0", "1"]
        ],
        "bids": [
            ["5556.81", "1", "0", "1"],
            ["5556.8", "2", "0", "1"],
            ["5556.79", "1", "0", "1"],
            ["5556.19", "100", "0", "1"],
            ["5556.08", "2", "0", "1"]
        ],
        "instrument_id": "BTC-USD-190628",
        "timestamp": "2019-05-06T07:19:39.348Z"
    }]
}

公共-400档深度频道

订阅后首次返回市场订单薄的400档深度数据并推送;然后每隔100毫秒,快照这个时间段内有更改的订单薄数据,并推送。

send示例
{"op": "subscribe", "args": ["futures/depth:BTC-USD-191227"]}

其中futures/depth为频道名,BTC-USD-191227instrument_id

返回参数
参数名 参数类型 描述
asks List<String> 卖方深度
bids List<String> 买方深度
timestamp String 时间戳
instrument_id String 合约ID,如BTC-USD-191227
checksum String 检验和

asks和bids值数组举例说明:

["411.8", "10", "1", "4"] 411.8为深度价格,10为此价格的合约张数,1为此价格的强平单个数,4为此价格的订单个数。

返回示例
首次400档:
{
    "table": "futures/depth",
    "action": "partial",
    "data": [{
        "instrument_id": "BTC-USD-191227",
        "asks": [
            ["8476.98","415","0","13"],
            ["8477","7","0","2"],
            ["8477.34","85","0","1"],
            ["8477.56","1","0","1"],
            ...
            ["8505.84","8","0","1"],
            ["8506.37","85","0","1"],
            ["8506.49","2","0","1"],
            ["8506.96","100","0","2"]
        ],
        "bids": [
            ["8476.97","256","0","12"],
            ["8475.55","101","0","1"],
            ["8475.54","100","0","1"],
            ["8475.3","1","0","1"], 
            ...
            ["8447.32","6","0","1"],
            ["8447.02","246","0","1"],
            ["8446.83","24","0","1"],
            ["8446","95","0","3"]
        ],
        "timestamp": "2019-05-06T07:19:39.348Z",
        "checksum": -855196043
    }]
}

后续更新:
{
    "table":"futures/depth",
    "action":"update",
    "data":[
        {
            "instrument_id":"BTC-USD-191227",
            "asks":[
                ["8476.98", "375", "0", "13"],
                ["8479.61", "0", "0", "0"],
                ["8480.47", "0", "0", "0"],
                ["8481.56", "12", "0", "2"],
                ["8487.07", "0", "0", "0"],
                ["8507", "4", "0", "2"],
                ["8507.19", "142", "0", "2"],
                ["8507.72", "3", "0", "1"]
            ],
            "bids":[
                ["8470.59", "0", "0", "0"],
                ["8467.44", "34", "0", "1"],
                ["8465.33", "0", "0", "0"],
                ["8463.79", "0", "0", "0"],
                ["8447.02", "246", "0", "1"],
                ["8446.83", "24", "0", "1"]
            ],
            "timestamp":"2019-09-26T08:47:43.730Z",
            "checksum":-253252232
        }
    ]
}

公共-全量深度频道

订阅后首次返回市场订单薄的全部深度数据并推送;后续只要订单薄深度有变化就推送有更改的数据。

send示例
{"op": "subscribe", "args": ["futures/depth_l2_tbt:BTC-USD-191018"]}

其中futures/depth_l2_tbt为频道名,BTC-USD-191018instrument_id

返回参数
参数名 参数类型 描述
asks List<String> 卖方深度
bids List<String> 买方深度
timestamp String 时间戳
instrument_id String 合约ID,如BTC-USD-191018
checksum String 检验和

asks和bids值数组举例说明:

["8582.97","40","0","40"] 8582.97为深度价格,40为此价格的合约张数,0为此价格的强平单个数,40为此价格的订单个数。

返回示例
首次全量深度:
{
    "table": "futures/depth",
    "action": "partial",
    "data": [{
        "instrument_id": "BTC-USD-191018",
        "asks": [
            ["8581.44","74","0","74"],
            ["8581.64","14","0","14"],
            ["8582.92","1","0","1"],
            ["8582.97","40","0","40"],
            ...
            ["13170.96","1208","0","1208"],
            ["13210.48","1000","0","1000"],
            ["13250.12","1471","0","1471"]
        ],
        "bids": [
            ["8581.38","37","0","37"],
            ["8581.01","1","0","1"],
            ["8579.38","1","0","1"],
            ["8579.05","14","0","14"], 
            ...
            ["5439.91","829","0","829"],
            ["5423.59","1083","0","1083"],
            ["5407.31","1173","0","1173"]
        ],
        "timestamp": "2019-10-10T08:50:14.528Z",
        "checksum": -182860440
    }]
}

后续更新:
{
    "table":"futures/depth",
    "action":"update",
    "data":[
        {
            "instrument_id":"BTC-USD-191018",
            "asks":[
                ["8581.64","0","0","0"],
                ["8587.64","0","0","0"]
            ],
            "bids":[
                ["8579.05","0","0","0"]
            ],
            "timestamp":"2019-10-10T08:50:14.541Z",
            "checksum":-1794408479
        }
    ]
}

公共-标记价格频道

获取标记价格

send示例
{"op": "subscribe", "args": ["futures/mark_price:BTC-USD-170310"]}

其中futures/mark_price为频道名,BTC-USD-170310instrument_id

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-170310
mark_price String 标记价格
timestamp String 系统时间戳

为了防止个别用户恶意操控市场导致合约价格波动剧烈,我们根据现货指数和合理基差设定标记价格。

返回示例
{
    "table": "futures/mark_price",
    "data": [{
        "instrument_id": "LTC-USD-190628",
        "mark_price": "70.557",
        "timestamp": "2019-05-06T07:19:39.835Z"
    }]
}

永续合约

以下是永续合约V3 WebscoketAPI

可参考SDK(点击跳转SDK详情页面)

概述

WebSocket是HTML5一种新的协议(Protocol)。它实现了客户端与服务器全双工通信, 使得数据可以快速地双向传播。通过一次简单的握手就可以建立客户端和服务器连接, 服务器根据业务规则可以主动推送信息给客户端。其优点如下:

  • 客户端和服务器进行数据传输时,请求头信息比较小,大概2个字节。
  • 客户端和服务器皆可以主动地发送数据给对方。
  • 不需要多次创建TCP请求和销毁,节约宽带和服务器的资源。

强烈建议开发者使用WebSocket API获取市场行情和买卖深度等信息。

地址:wss://real.okex.com:8443/ws/v3

访问时需要科学上网

连接说明:

所有返回数据都进行了压缩,需要用户将接收到的数据进行解压。解压缩请参考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>"}]"}

其中swap/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为swap, channel为此业务下每个具体的名称,如果channel的名字不能以一个字母区分将会以 " _ " 进行连接

例:

"swap/ticker:BTC-USD-SWAP"or "swap/price_range:BTC-USD-SWAP"

filter 是可筛选数据,具体参考每个频道说明

示例:

send:

{"op": "subscribe", "args": ["swap/ticker:BTC-USD-SWAP", "swap/candle60s:BTC-USD-SWAP"]}

response:

 {"event": subscribe,"channel":"swap/ticker:BTC-USD-SWAP"}

 {"event": subscribe,"channel":"swap/candle60s:BTC-USD-SWAP"}

 {"table":"swap/ticker","data":[{"high_24h":"3369","instrument_id":"BTC-USD-SWAP","last":"3299",
 "low_24h":"3112","timestamp":"2018-12-09T08:12:04.659Z","volume_24h":"8389225"}]}

 {"table":"swap/candle60s","data":[{"instrument_id":"BTC-USD-SWAP","candle":["2018-12-09T08:12:00.000Z",
 "3299.8","3299.8","3299","3299","82","2.4854"]}]}

取消订阅

可以取消一个或者多个频道

{"op": "unsubscribe", "args": [<SubscriptionTopic>]}

例如:

请求:

{"op": "unsubscribe", "args": ["swap/ticker:BTC-USD-SWAP", "swap/candle60s:BTC-USD-SWAP"]}

返回:

{"event":"unsubscribe","channel":"swap/ticker:BTC-USD-SWAP"}
{"event":"unsubscribe","channel":"swap/candle60s:BTC-USD-SWAP"}

登录

签名方式说明参考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 频道首次会接收到200档深度,后续推送的都是增量数据。checksum值为:每次增量更新合并后此200档深度的前 25档 bids 和 asks组成的字符串的crc32值, 用户可以拿自己的checksum的值和订阅的checksum值进行比较,如果不匹配可以重新订阅。

深度合并规则说明: 首次发送200档深度数据,后续每次发送增量的数据。去遍历200档中的ask和bids的price ,如果发现有相同价格 则看数量,数量为0删除此深度,数量有变化则替换此数据; 无相同价格则按照顺序排序。

计算说明: checksum的值为有符号整型(32位)

checksum的字符串都是以冒号连接的ask和bid中的price和数量,例如:

例子1:bid和ask成对档的情况下,要校验的字符串为:bid:ask:bid:ask:...


"data": [{
        "instrument_id": "BTC-USD-SWAP",
        "asks": [["3366.8", "9", 10, 3],[ "3368","8",3,4 ]],
        "bids": [
            ["3366.1", "7", 0, 3],[ "3366","6",3,4 ]
        ],
        "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-USD-SWAP",
        "asks": [["3366.8", "9", 10, 3],[ "3368","8",3,4 ],[ "3372","8",3,4 ]],
        "bids": [
            ["3366.1", "7", 0, 3]
        ],
        "timestamp": "2018-12-04T09:38:36.300Z",
        "checksum": 831078360
    }]

此例子对应的checksum String 将会是 3366.1:7:3366.8:9:3368:8:3372:8

depth 频道用户收到推送数据为:

首次200档


{
    "table": "swap/depth",
    "action": "partial",
    "data": [{
        "instrument_id": "BTC-USD-SWAP",
        "asks": [["3983", "888", 10, 3],....],
        "bids": [
            ["3983", "789", 0, 3],....
        ],
        "timestamp": "2018-12-04T09:38:36.300Z",
        "checksum": 200119424
    }]
}

增量:

{
    "table": "swap/depth",
    "action": "update",
    "data": [{
        "instrument_id": "BTC-USD-SWAP",
        "asks": [],
        "bids": [
            ["3983", "789", 0, 3]
        ],
        "timestamp": "2018-12-04T09:38:36.300Z",
        "checksum": -1200119424
    }]
}

频道说明

无需登录的频道包括:行情频道,K线频道,交易数据频道,资金费率频道,限价范围频道,深度数据频道,标记价格频道

需登录的频道包括:用户账户频道,用户交易频道,用户持仓频道

无需登录的频道名称如下:

swap/ticker // 行情数据频道

swap/candle60s // 1分钟k线数据频道

swap/trade // 交易信息频道

swap/funding_rate//资金费率频道

swap/price_range//限价范围频道

swap/depth //深度数据频道,首次200档,后续增量

swap/depth5 //深度数据频道,每次返回前5档

swap/mark_price// 标记价格频道

需登录的频道如下:

swap/account //用户账户信息频道

swap/position //用户持仓信息频道

swap/order //用户交易数据频道

用户持仓频道

获取用户持仓信息,需用用户登录

send示例
{"op": "subscribe", "args": ["swap/position:BTC-USD-SWAP"]}

其中swap/ position为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
liquidation_price String 预估强平价
position String 持仓数量
avail_position String 可平数量
avg_cost String 开仓平均价
settlement_price String 结算基准价
instrument_id String 合约名称
leverage String 杠杆
realized_pnl String 已实现盈亏
side String 方向(long/short
timestamp String 创建时间
margin String 保证金
margin_mode String fixed:逐仓
crossed:全仓
settled_pnl String 已结算收益
last String 最新成交价
maint_margin_ratio String 维持保证金率
返回示例
{
    "table":"swap/position",
    "data":[
        {
            "holding":[
                {
                    "avail_position":"1501",
                    "avg_cost":"231.98",
                    "last":"225.78",
                    "leverage":"50.00",
                    "liquidation_price":"154.48",
                    "maint_margin_ratio":"0.0100",
                    "margin":"1.3296",
                    "position":"1501",
                    "realized_pnl":"-0.0070",
                    "settled_pnl":"-1.9640",
                    "settlement_price":"225.15",
                    "side":"long",
                    "timestamp":"2019-10-11T10:43:32.261Z"
                }
            ],
            "instrument_id":"BCH-USD-SWAP",
            "margin_mode":"crossed",
            "timestamp":"2019-10-11T10:43:32.261Z"
        }
    ]
}

用户账户频道

获取账户信息,需用用户登录

send示例
{"op": "subscribe", "args": ["swap/account:BTC-USD-SWAP"]}

其中swap/account为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
equity String 账户权益(账户动态权益)
instrument_id String 合约名称
margin String 已用保证金
margin_frozen String 开仓冻结保证金
margin_ratio String 保证金率
realized_pnl String 已实现盈亏
timestamp String 创建时间
total_avail_balance String 账户余额(账户静态权益)
unrealized_pnl String 未实现盈亏
fixed_balance String 逐仓账户余额
margin_mode String 账户类型
逐仓:fixed
全仓:crossed
maint_margin_ratio String 维持保证金率
返回示例
{
    "table":"swap/account",
    "data":[
        {
            "equity":"31.7190",
            "fixed_balance":"0.0000",
            "instrument_id":"BCH-USD-SWAP",
            "maint_margin_ratio":"0.0100",
            "margin":"1.3296",
            "margin_frozen":"0.0000",
            "margin_mode":"crossed",
            "margin_ratio":"0.4770",
            "realized_pnl":"-0.0070",
            "timestamp":"2019-10-11T10:43:32.255Z",
            "total_avail_balance":"31.5452",
            "unrealized_pnl":"0.1806"
        }
    ]
}

用户交易频道

获取用户交易数据,需用用户登录

send示例
{"op": "subscribe", "args": ["swap/order:BTC-USD-SWAP"]}

其中swap/order为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
size String 委托数量
timestamp String 订单状态变化时间
filled_qty String 成交数量
fee String 手续费
error_code String error code
order_id String 订单id
client_oid String 用户设置的订单id
price String 委托价格
price_avg String 成交均价
type String 1:开多
2:开空
3:平多
4:平空
contract_val String 合约面值
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:撤单中
解释说明

timestamp会根据订单状态变化分别返回相应的创建时间、成交时间、撤销时间等,具体状态用户可根据state参数判断。

statusstate旧版参数,会短期兼容,建议尽早切换state

返回示例
{
    "table": "swap/order",
    "data": [{
        "last_fill_time": "1970-01-01T00:00:00.000Z",
        "filled_qty": "0",
        "fee": "0.000000",
        "client_oid": "",
        "last_fill_qty": "0",
        "price_avg": "0.0000",
        "type": "2",
        "instrument_id": "XRP-USD-SWAP",
        "last_fill_px": "0",
        "size": "1",
        "price": "0.2935",
        "error_code": "0",
        "contract_val": "10",
        "state": "0",
        "order_id": "6c-a-625f6f638-0",
        "order_type": "0",
        "state": "0",
        "timestamp": "2019-05-06T07:12:25.679Z"
    }]
}

用户委托策略频道

用户委托策略频道

send示例
{"op": "subscribe", "args": ["swap/order_algo:LTC-USD-SWAP"]}

其中swap/order_algo为频道名,LTC-USD-SWAPinstrument_id

返回参数
参数名 类型 描述
algo_id string 委托ID
order_type string 1:止盈止损
2:跟踪委托
3:冰山委托
4:时间加权委托
leverage String 杠杆倍数
size string 委托数量
instrument_id string 币对名称
type String 订单类型
1:开多
2:开空
3:平多
4:平空
timestamp string 委托时间
status string 订单状态
1:待生效
2:已生效
3:已撤销
4:部分生效
5:暂停生效
6:委托失败
【只有冰山和加权有45状态】

止盈止损

参数名 类型 描述
algo_price string 委托价格
trigger_price string 触发价格

跟踪委托

参数名 类型 描述
callback_rate string 回调幅度
trigger_price string 激活价格

冰山委托

参数名 类型 描述
algo_variance string 委托深度
avg_amount string 单笔均值
price_limit string 价格限制

时间加权委托

参数名 类型 描述
sweep_range string 扫单范围
sweep_ratio string 扫单比例
single_limit string 单笔上限
price_limit string 价格限制
time_interval string 委托间隔
返回示例
{
    "table":"swap/order_algo",
    "data":[
        {
            "algo_id":"342507214297841664",
            "leverage":"50.00",
            "size":"1.0000",
            "trigger_price":"280.00",
            "callback_rate":"0.020",
            "type":"1",
            "instrument_id":"BCH-USD-SWAP",
            "order_type":"2",
            "status":"1",
            "timestamp":"2019-10-11T09:59:41.688Z"
        }
    ]
}

公共-Ticker频道

获取平台全部永续合约的最新成交价、买一价、卖一价和24交易量

send示例
{"op": "subscribe", "args": ["swap/ticker:BTC-USD-SWAP"]}

其中swap/ticker为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
best_bid String 买一价
best_ask String 卖一价
last String 最新成交价
high_24h String 24小时最高价
low_24h String 24小时最低价
volume_24h String 24小时成交量(按张数统计)
volume_token_24h String 24小时成交量(按币统计)
timestamp String 系统时间戳
open_interest string 持仓量
open_24h string 24小时开盘价
返回示例
{
    "table":"swap/ticker",
    "data":[
        {
            "best_ask":"8382.7",
            "best_bid":"8382.6",
            "high_24h":"8803.2",
            "instrument_id":"BTC-USD-SWAP",
            "last":"8382.7",
            "low_24h":"8301",
            "open_24h":"8561.1",
            "open_interest":"1135263",
            "timestamp":"2019-10-11T09:10:23.320Z",
            "volume_24h":"4045320",
            "volume_token_24h":"47464.5"
        }
    ]
}

公共-K线频道

获取合约的K线数据

频道列表:

swap/candle60s // 1分钟k线数据频道

swap/candle180s // 3分钟k线数据频道

swap/candle300s // 5分钟k线数据频道

swap/candle900s // 15分钟k线数据频道

swap/candle1800s // 30分钟k线数据频道

swap/candle3600s // 1小时k线数据频道

swap/candle7200s // 2小时k线数据频道

swap/candle14400s // 4小时k线数据频道

swap/candle21600 // 6小时k线数据频道

swap/candle43200s // 12小时k线数据频道

swap/candle86400s // 1day k线数据频道

swap/candle604800s // 1week k线数据频道

send示例
{"op": "subscribe", "args": ["swap/candle60s:BTC-USD-SWAP"]}

其中swap/candle60s为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
timestamp String 开始时间
open String 开盘价格
high String 最高价格
low String 最低价格
close String 收盘价格
volume String 交易量(张)
currency_volume String 按币折算的交易量
instrument_id String 合约BTC-USD-SWAP
返回示例

{
    "table": "swap/candle60s",
    "data": [{
        "instrument_id": "BTC-USD-SWAP",
        "candle": ["2019-05-06T06:51:00.000Z", "5613", "5613", "5611.9", "5611.9", "1218", "21.7009"]
    }]
}

公共-交易频道

获取最近的成交数据。

send示例
{"op": "subscribe", "args": ["swap/trade:BTC-USD-SWAP"]}

其中swap/trade为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
trade_id String 成交id
price String 成交价格
size String 成交数量
side String 成交方向(buysell
timestamp String 成交时间
instrument_id String BTC-USD-SWAP
返回示例
{
    "table": "swap/trade",
    "data": [{
        "instrument_id": "BTC-USD-SWAP",
        "price": "5611.9",
        "side": "buy",
        "size": "2",
        "timestamp": "2019-05-06T06:51:24.389Z",
        "trade_id": "227897880202387456"
    }]}

公共-资金费率频道

获取合约资金费率

send示例
{"op": "subscribe", "args": ["swap/funding_rate:BTC-USD-SWAP"]}

其中swap/funding_rate为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
interest_rate String 利率
instrument_id String 合约名称,如BTC-USD-SWAP
funding_time String 当期资金费率时间
funding_rate String 当期资金费率
estimated_rate String 下一期预测资金费率
settlement_time String 结算时间
返回示例
{
    "table":"swap/funding_rate",
    "data":[
        {
            "estimated_rate":"0.00019",
            "funding_rate":"0.00022993",
            "funding_time":"2019-10-11T16:00:00.000Z",
            "instrument_id":"BTC-USD-SWAP",
            "interest_rate":"0",
            "settlement_time":"2019-10-12T08:00:00.000Z"
        }
    ]
}

公共-限价频道

获取合约当前交易的最高买价和最低卖价。

send示例
{"op": "subscribe", "args": ["swap/price_range:BTC-USD-SWAP"]}

其中swap/ price_range为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
timestamp String 系统时间戳
lowest String 最低卖价
instrument_id String 合约名称,如BTC-USD-SWAP
highest String 最高买价
返回示例
{
    "table": "swap/price_range",
    "data": [{
        "highest": "5665.9",
        "instrument_id": "BTC-USD-SWAP",
        "lowest": "5553.6",
        "timestamp": "2019-05-06T06:51:20.012Z"
    }]
}

公共-5档深度频道

每次返回前五档的深度数据,此数据为每100毫秒的快照数据,即每隔100毫秒,快照当前时刻市场订单薄的5档深度数据并推送。

send示例
{"op": "subscribe", "args": ["swap/depth5:BTC-USD-SWAP"]}

其中swap/depth5为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
asks List<String> 卖方深度
bids List<String> 买方深度
timestamp String 时间戳
instrument_id String 合约ID

["411.8", "10", "1", "4"] 411.8为深度价格,10为此价格的合约张数,1为此价格的强平单个数,4为此价格的订单个数。

返回示例
{
    "table": "swap/depth5",
    "data": [{
        "asks": [
            ["5621.7", "58", “0”, “2”],
            ["5621.8", "125", “0”, “5”],
            ["5622", "84", “0”, “2”],
            ["5622.5", "6", “0”, “1”],
            ["5623", "1", “0”, “1”]
        ],
        "bids": [
            ["5621.3", "287", “0”, ”8”],
            ["5621.2", "41", “0”, “1”],
            ["5621.1", "2", “0”, “1”],
            ["5621", "26", “0”, “2”],
            ["5620.9", "640", “0”, “1”]
        ],
        "instrument_id": "BTC-USD-SWAP",
        "timestamp": "2019-05-06T07:03:33.048Z"
    }]
}

公共-200档深度频道

订阅后首次返回市场订单薄的200档深度数据并推送;然后每隔100毫秒,快照这个时间段内有更改的订单薄数据,并推送。

send示例
{"op": "subscribe", "args": ["swap/depth:BTC-USD-SWAP"]}

其中swap/depth为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
asks List<String> 卖方深度
bids List<String> 买方深度
timestamp String 时间戳
instrument_id String 合约ID
checksum String 检验和

bids and asks value example:

["411.8", "10", "1", "4"] 411.8为深度价格,10为此价格的合约张数,1为此价格的强平单个数,4为此价格的订单个数。

返回示例
首次200档

{
    "table": "swap/depth",
    "action": "update",
    "data": [{
        "instrument_id": "BTC-USD-SWAP",
        "asks": [
            ["5621.7", "58", "0", "2"],
            ["5621.8", "125", "0", "5"],
            ["5621.9", "0", "0", "0"],
            ["5622", "84", "0", "2"],
            ["5623.5", "0", "0", "0"],
            ["5624.2", "4", "0", "1"],
            ["5625.1", "0", "0", "0"],
            ["5625.9", "0", "0", "0"],
            ["5629.3", "2", "0", "1"],
            ["5650", "187", "0", "8"],
            ["5789", "1", "0", "1"]
        ],
        "bids": [
            ["5621.3", "287", "0", "8"],
            ["5621.2", "41", "0", "1"],
            ["5621.1", "2", "0", "1"],
            ["5621", "26", "0", "2"],
            ["5620.8", "194", "0", "2"],
            ["5620", "2", "0", "1"],
            ["5618.8", "204", "0", "2"],
            ["5618.4", "0", "0", "0"],
            ["5617.2", "2", "0", "1"],
            ["5609.9", "0", "0", "0"],
            ["5433", "0", "0", "0"],
            ["5430", "0", "0", "0"]
        ],
        "timestamp": "2019-05-06T07:03:33.048Z",
        "checksum": -186865074
    }]

公共-标记价格频道

获取标记价格

send示例
{"op": "subscribe", "args": ["swap/mark_price:BTC-USD-SWAP"]}

其中swap/mark_price为频道名,BTC-USD-SWAPinstrument_id

返回参数
参数名 参数类型 描述
instrument_id String 合约名称,如BTC-USD-SWAP
mark_price String 标记价格
timestamp String 系统时间戳

为了防止个别用户恶意操控市场导致合约价格波动剧烈,我们根据现货指数和合理基差设定标记价格。

返回示例
{
    "table": "swap/mark_price",
    "data": [{
        "instrument_id": "BTC-USD-SWAP",
        "mark_price": "5620.9",
        "timestamp": "2019-05-06T07:03:33.799Z"
    }]
}

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分”