CCXT-11-查询委托单

2020-04-16

1. 委托单说明

大多数时候，你可以按id或符号查询委托单，虽然不是所有的交易所都提供了完整和灵活的委托单查询访问端结点。有些交易所可能没有方法查询最近完成的委托单，另一些可能缺少按id获取委托单的方法，等等。ccxt库考虑了这些情况并尽可能加以解决。查询委托单的方法如下：

fetchOrder (id, symbol = undefined, params = {})
fetchOrders (symbol = undefined, since = undefined, limit = undefined, params = {})
fetchOpenOrders (symbol = undefined, since = undefined, limit = undefined, params = {})
fetchClosedOrders (symbol = undefined, since = undefined, limit = undefined, params = {})

注意这些方法的名字可以看出该方法是返回一个委托单还是多个委托单。如果用户调用了交易所不支持的方法，ccxt库会抛出NotSupported异常。要检查上述方法是否有效，可以查看交易所对象的.has属性。 JavaScript示例代码：

'use strict';
const ccxt = require ('ccxt')
const id = 'poloniex'
exchange = new ccxt[id] ()
console.log (exchange.has)

Python示例代码：

import ccxt
id = 'binance'
exchange = getattr(ccxt, id) ()
print(exchange.has)

PHP示例代码：

$exchange = new \ccxt\liqui ();
print_r ($exchange->has); // or var_dump

一个典型的.hash属性通常包含如下对应上述用于查询委托单的API方法的标志：

exchange.has = {
    // ... other flags ...
    'fetchOrder': true, // available from the exchange directly and implemented in ccxt
    'fetchOrders': false, // not available from the exchange or not implemented in ccxt
    'fetchOpenOrders': true,
    'fetchClosedOrders': 'emulated', // not available from the exchange, but emulated in ccxt
    // ... other flags ...
}

ture和false的含义很明确。emulated表示这个方法是ccxt模拟出来的，不是交易所原生API提供的。

2. 委托单数据结构

ccxt统一API中绝大多数返回委托单的方法，通常会输出如下的委托单数据结构：

{
    'id':                '12345-67890:09876/54321', // string
    'datetime':          '2017-08-17 12:42:48.000', // ISO8601 datetime of 'timestamp' with milliseconds
    'timestamp':          1502962946216, // order placing/opening Unix timestamp in milliseconds
    'lastTradeTimestamp': 1502962956216, // Unix timestamp of the most recent trade on this order
    'status':     'open',         // 'open', 'closed', 'canceled'
    'symbol':     'ETH/BTC',      // symbol
    'type':       'limit',        // 'market', 'limit'
    'side':       'buy',          // 'buy', 'sell'
    'price':       0.06917684,    // float price in quote currency
    'amount':      1.5,           // ordered amount of base currency
    'filled':      1.1,           // filled amount of base currency
    'remaining':   0.4,           // remaining amount to fill
    'cost':        0.076094524,   // 'filled' * 'price' (filling price used where available)
    'trades':    [ ... ],         // a list of order trades/executions
    'fee': {                      // fee info, if available
        'currency': 'BTC',        // which currency the fee is (usually quote)
        'cost': 0.0009,           // the fee amount in that currency
        'rate': 0.002,            // the fee rate (if available)
    },
    'info': { ... },              // the original unparsed order structure as is
}

补充说明如下：

fee：手续费信息这部分的工作还在进行中，取决于交易所提供的接口，这部分信息可能不完整甚至完全没有。
fee.currency：手续费货币可能与所交易的货币都不一样。例如，一个ETH/BTC的委托单可能使用USD支付手续费
lastTradeTimestamp：最后交易时间戳表示该委托单最后一次交易的时间。在有些情况下，这个字段可能没有值或者是undefined/None/null，例如交易所不支持，或者委托单还是敞口状态。
status：委托单状态的优先级高于最后交易时间戳
cost：委托单花费 = filled * price ，表示委托单的总花费，cost字段是处于方便目的而提供，值可以根据其他字段推导出来。

3. 查询指定ID的委托单 - fetchOrder

要获取具有指定ID的委托单，使用fetchOrder / fetch_order方法。即使是你要查询一个特定ID的委托单，有些交易所也要求你提供交易对符号。 fetchOrder/fetch_order方法的原型如下：

if (exchange.has['fetchOrder']) {
    //  you can use the params argument for custom overrides
    let order = await exchange.fetchOrder (id, symbol = undefined, params = {})
}

有些交易所没有提供按ID查询委托单的访问端结点，ccxt会尽可能的提供模拟实现。不过现在这个工作还在进行中，可能你会碰到没有实现这个模拟的交易所。你可以使用额外的键/值参数对象来指定委托单类型等需要的设置。下面是使用fetchOrder方法从一个已经验证过身份的交易所实例获取委托单信息的示例代码。 JavaScript：

(async function () {
    const order = await exchange.fetchOrder (id)
    console.log (order)
}) ()

Python 2/3 同步方式的示例代码：

if exchange.has['fetchOrder']:
    order = exchange.fetch_order(id)
    print(order)
# Python 3.5+ asyncio (asynchronous)
import asyncio
import ccxt.async_support as ccxt
if exchange.has['fetchOrder']:
    order = asyncio.get_event_loop().run_until_complete(exchange.fetch_order(id))
    print(order)

PHP：

if ($exchange->has['fetchOrder']) {
    $order = $exchange->fetch_order ($id);
    var_dump ($order);
}

4. 查询全部委托单 - fetchOrders

使用fetchOrders方法查询交易所的全部委托单，方法原型如下；

if (exchange.has['fetchOrders'])
    exchange.fetchOrders (symbol = undefined, since = undefined, limit = undefined, params = {})

有些交易所没有查询全部委托单的访问端结点，ccxt库会尝试尽可能的模拟实现。不过到目前为止这一工作还在进展当中，因此你可能会碰到不支持此功能的交易所。

5. 查询全部敞口委托单 - fetchOpenOrders

使用fetchOpenOrders方法查询交易所的所有敞口委托单，方法原型如下：

if (exchange.has['fetchOpenOrders'])
    exchange.fetchOpenOrders (symbol = undefined, since = undefined, limit = undefined, params = {})

6. 查询全部已完结委托单 - fetchClosedOrders

使用交易所实例的fetchClosedOrders方法来查询所有已完结的委托单，其方法原型如下：

if (exchange.has['fetchClosedOrders'])
    exchange.fetchClosedOrders (symbol = undefined, since = undefined, limit = undefined, params = {})

_ 不要把已完结委托单和交易搞混了！一个完结的委托单可能会对应多个交易！ 因此，已完结委托单和交易并不是一回事。总的来说，委托单根本不存在手续费，但是每个用户交易的确有手续费、成本及其他属性。然而，许多交易所也会把交易的这些属性传递给委托单。有些交易所没有提供查询全部的已完结委托单的访问端结点，ccxt库会尽可能尝试模拟实现。不过目前这一工作还在进行中，因此你可能会碰到不支持此功能的交易所类。