Authentication

To use private endpoints such as the account notifications channel, or the trading API, you will need to create an API key. Private endpoints require a nonce, which must be an integer greater than the previous nonce used. There is no requirement that nonces increase by a specific amount, so the current epoch time in milliseconds is an easy choice. Note that each API key has its own nonce tracking.

Websockets

Introduction

All websockets data uses the following URL:

wss://api2.poloniex.com

They can be read by any standard websockets library. Websockets data is organized into channels to which an API client may subscribe.

Requests and Responses

There are two type of requests supported; subscribe and unsubscribe. The requests are for a specific channel. For non-book requests, the first response is always an acknowledgement of the request. All channel updates are of the following format

[<channel>, <sequence id>, <update data...>]

<sequence id> is a number increasing by one with each update and is unique within its channel. The sequence-id is always null for non-book channels.

Subscribing and Unsubscribing

To receive updates from a channel you must subscribe to it. To subscribe to a public channel (all except the account notifications channel), determine its channel ID (provided with the description of each channel, and summarized here), send a JSON message with the following properties:

{
"command": "subscribe",
"channel": "<channel id>"
}

To subscribe to a private channel, the parameters described in the authentication section are required in the subscription message. Just like the trading API, an integer nonce must be chosen that is greater than the previous nonce used; for this purpose the current epoch time in milliseconds is a reasonable choice. Note that each API key has its own nonce tracking. If the chosen nonce is 1234, provide a "payload" parameter consisting of nonce=1234, a "key" parameter with your API key, and a "sign" parameter with the HMAC-SHA512 signature of the payload signed by your secret:

Account Notifications (Beta)

Before using this channel, please be aware that it is a beta feature. We will not make breaking API changes, but we may undertake changes such as adding extra data fields to the ends of arrays, or adding new message types. Your code should be tolerant of this. We have made all reasonable efforts to ensure its correctness, but you use this channel at your own risk during the beta phase.

The account notifications channel (id 1000) provides real-time updates of trade and balance changes on your account. You can (and should) use it to track your account's trading activity (instead of relying on repeated calls to the trading API). It is an authenticated websocket endpoint, so subscribing to it requires the parameters discussed in the subscribing section:

Subsequent messages represent updates to your account. In general, a message consists of a combination of updates of different types. Each update is an array of data, where the first element is a character denoting the type of the update, and subsequent elements are various parameters:

A given message may contain multiple updates, multiple types of updates, and multiple updates of the same type. There is no ordering guarantee of update types within a single message. Effectively, each message is a record of all of the changes to your account induced by a single action. There are four types of updates, as described below:

b updates represent an available balance update. They are of the following format:

["b", <currency id>, "<wallet>", "<amount>"]

Currency IDs may be found in the reference table, or using the returnCurrencies REST call. The wallet can be e (exchange). Thus, a b update representing a deduction of 0.06 BTC from the exchange wallet will look like:

["b", 28, "e", "-0.06000000"]

n updates represent a newly created limit order. They are of the following format:

Currency pair IDs are described here, the order type can either be 0 (sell) or 1
(buy), and the date is formatted according to the format string Y-m-d H:i:s. Note that the "<order amount>" is the amount in the open order
after all trades are evaluated. I.e., the sum of amounts in the trades and the order amount will be equal to the "<starting amount>", which is the
amount you placed. Thus, an n update representing a buy order for 2 ETH at rate 0.03 BTC per ETH will look like:

The fee multiplier is the fee schedule applied to the trade (for instance, if a trade had a trading fee of 0.25%, the fee multiplier will be '0.00250000'). The funding type represents the funding used for the trade, and may be 0 (exchange wallet). Note that while the trade ID will always be distinct, the order number may be shared across multiple t updates if multiple trades were required to fill a limit order. A t update representing a purchase of 0.5 ETH at rate 0.03 BTC per ETH using exchange funds with a fee schedule of 0.25% will look like:

["t", 12345, "0.03000000", "0.50000000", '0.00250000', 0, 6083059]

As mentioned above, a single logical action may cause a message with multiple updates. For instance, placing a limit order to buy ETH using BTC, which is immediately partially fulfilled, will cause a update with 4 updates: a b update with a positive ETH balance update (the ETH that was immediately bought), a b update with a negative BTC balance update (the BTC removed from the user's funds to pay for the ETH), a t update representing the trade in which the order was partially fulfilled, and an n update with the new limit order for the rest of the requested ETH.

Note that many actions do not have explicit notification types, but rather are represented by the underlying trade and balance changes:

Stop-limit orders immediately cause a b notification (that the appropriate balance has been decremented to reserve an asset for the limit order). When they are triggered they cause notifications comensurate with a standard limit order being placed (n or t updates depending on whether the limit was immediately fulfilled).

Price Aggregated Book

Subscribe to price aggregated depth of book by currency pair. Response includes an initial book snapshot, book modifications, and trades. Book modification updates with 0 quantity should be treated as removal of the price level. Note that the updates are price aggregated and do not contain individual orders.

Subscription example for BTC_BTS pair (id is 14). You can either subscribe using the currency pair ID or name. Currency pair IDs are listed in the currency pair ID list.

Trading API Methods

Please note that there is a default limit of 6 calls per second. If you require more than this, please consider optimizing your application using the push API, the "moveOrder" command, or the "all" parameter where appropriate. If this is still insufficient, please contact support to discuss a limit raise.

All calls to the trading API are sent via HTTP POST to https://poloniex.com/tradingApi and must contain the following headers:

Key - Your API key.

Sign - The query's POST data signed by your key's "secret" according to the HMAC-SHA512 method.

Additionally, all queries must include a "nonce" POST parameter. The nonce parameter is an integer which must always be greater than the previous nonce used.

All responses from the trading API are in JSON format. In the event of an error, the response will always be of the following format:

{
"error": "<error message>"
}

There are several methods accepted by the trading API, each of which is specified by the "command" POST parameter:

returnBalances

Returns all of your available balances. Sample output:

{
"BTC": "0.59098578",
"LTC": "3.31117268",
...
}

returnCompleteBalances

Returns all of your balances, including available balance, balance on orders, and the estimated BTC value of your balance. Sample output:

Returns your open orders for a given market, specified by the "currencyPair" POST parameter, e.g. "BTC_XCP". Set "currencyPair" to "all" to return open orders for all markets. Sample output for single market:

Returns your trade history for a given market, specified by the "currencyPair" POST parameter. You may specify "all" as the currencyPair to receive your trade history for all markets. You may optionally specify a range via "start" and/or "end" POST parameters, given in UNIX timestamp format; if you do not specify a range, it will be limited to one day. You may optionally limit the number of entries returned using the "limit" parameter, up to a maximum of 10,000. If the "limit" parameter is not specified, no more than 500 entries will be returned. Sample output:

Returns all trades involving a given order, specified by the "orderNumber" POST parameter. If no trades for the order have occurred or you specify an order that does not belong to you, you will receive an error. See the documentation here for how to use the information from returnOrderTrades and returnOrderStatus to determine various status information about an order. Sample output of returnOrderTrades:

Returns the status of a given order, specified by the "orderNumber" POST parameter. If the specified orderNumber is not open, or it is not yours, you will receive an error. Sample output on a fully open order:

If returnOrderStatus returns an error and returnOrderTrades returns a list of trades, then the order had fills and is no longer open (due to being completely filled, or partially filled and then cancelled).

buy

Places a limit buy order in a given market. Required POST parameters are "currencyPair", "rate", and "amount". If successful, the method will return the order number. Sample output:

You may optionally set "fillOrKill", "immediateOrCancel", "postOnly" to 1. A fill-or-kill order will either fill in its entirety or be completely aborted. An immediate-or-cancel order can be partially or completely filled, but any portion of the order that cannot be filled immediately will be canceled rather than left on the order book. A post-only order will only be placed if no portion of it fills immediately; this guarantees you will never pay the taker fee on any part of the order that fills.

sell

Places a sell order in a given market. Parameters and output are the same as for the buy method.

cancelOrder

Cancels an order you have placed in a given market. Required POST parameter is "orderNumber". If successful, the method will return:

{
"success": 1
}

moveOrder

Cancels an order and places a new one of the same type in a single atomic transaction, meaning either both operations will succeed or both will fail. Required POST parameters are "orderNumber" and "rate"; you may optionally specify "amount" if you wish to change the amount of the new order. "postOnly" or "immediateOrCancel" may be specified for exchange orders. Sample output:

Immediately places a withdrawal for a given currency, with no email confirmation. In order to use this method, the withdrawal privilege must be enabled for your API key. Required POST parameters are "currency", "amount", and "address". For XMR withdrawals, you may optionally specify "paymentId". Sample output:

{
"response": "Withdrew 2398 NXT."
}

returnFeeInfo

If you are enrolled in the maker-taker fee schedule, returns your current trading fees and trailing 30-day volume in BTC. This information is updated once every 24 hours.