Orders

危险

Poloniex futures v1/v2 API will be officially offline on November 30, 2024. You can access the V3 API to provide you with a better trading experience.

Place an Order

You can place two types of orders: limit and market. Orders can only be placed if your account has sufficient funds. Once an order is placed, your funds will be put on hold for the duration of the order. The amount of funds on hold depends on the order type and parameters specified.

Please note that the system will hold the fees from the orders entered in the orderbook in advance. Read Get Fills to learn more.

Do NOT include extra spaces in JSON strings.

Place Order Limit:

The maximum limit orders for a single contract is 100 per account, and the maximum stop orders for a single contract is 50 per account.

HTTP Request

POST https://futures-api.poloniex.com/api/v1/orders

API Permission

This endpoint requires the Trade permission

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 30 times/3s.

Parameters

Param	type	Description
clientOid	String	Unique order id created by users to identify their orders, e.g. UUID, Only allows numbers, characters, underline(_), and separator(-)
side	String	buy or sell
symbol	String	a valid contract code. e.g. BTCUSDTPERP
type	String	[optional] Either limit or market
leverage	String	Deprecated,Leverage of the order
remark	String	[optional] remark for the order, length cannot exceed 100 utf8 characters
stop	String	[optional] Either down or up. Requires stopPrice and stopPriceType to be defined
stopPriceType	String	[optional] Either TP, IP or MP, Need to be defined if stop is specified.
stopPrice	String	[optional] Need to be defined if stop is specified.
reduceOnly	boolean	[optional] A mark to reduce the position size only. Set to false by default.
closeOrder	boolean	[optional] A mark to close the position. Set to false by default.
forceHold	boolean	[optional] A mark to forcely hold the funds for an order, even though it's an order to reduce the position size. This helps the order stay on the order book and not get canceled when the position size changes. Set to false by default.

See Advanced Description for more details.

LIMIT ORDER PARAMETERS

Param	type	Description
price	String	Limit price
size	Integer	Order size. Must be a positive number
quantity	String	[optional] Order quantity. Must be a positive number. Only takes effect when size is empty
timeInForce	String	[optional] GTC, IOC(default is GTC), read Time In Force
postOnly	boolean	[optional] Post only flag, invalid when timeInForce is IOC. When postOnly chose, not allowed choose hidden or iceberg.
hidden	boolean	Deprecated,[optional] Orders not displaying in order book. When hidden chose, not allowed choose postOnly.
iceberg	boolean	Deprecated,[optional] Only visible portion of the order is displayed in the order book. When iceberg chose, not allowed choose postOnly.
visibleSize	Integer	Deprecated,[optional] The maximum visible size of an iceberg order

MARKET ORDER PARAMETERS

Param	type	Description
size	Integer	[optional] amount of contract to buy or sell
quantity	String	[optional] Order quantity. Must be a positive number. Only takes effect when size is empty

Example:

Request:

{
    "clientOid": "5c52e11203aa677f33e493fb",
    "reduceOnly": false,
    "closeOrder": false,
    "forceHold": false,
    "hidden": false,
    "iceberg": false,
    "leverage": 20,
    "postOnly": false,
    "price": 8000,
    "remark": "remark",
    "side": "buy",
    "size": 20,
    "stop": "",
    "stopPrice": 0,
    "stopPriceType": "",
    "symbol": "BTCUSDTPERP",
    "timeInForce": "",
    "type": "limit",
    "visibleSize": 0
}

Response:

{
    "code": "200000",
    "data": {
        "orderId": "5bd6e9286d99522a52e458de"
    }
}

Advanced Description

SYMBOL

The symbol must match a contract symbol, e.g. BTCUSDTPERP

CLIENT ORDER ID

Generated by yourself, the optional clientOid field must be a unique id (e.g UUID). Only numbers, characters, underline(_) and separator(-) are allowed. The value will be returned in the order detail. You can use this field to identify your orders via the public feed. The client_oid is different from the server-assigned order id. Please do not send a repeated client_oid. The length of the client_oid cannot exceed 40 characters. You should record the server-assigned order_id as it will be used for future queries of your order status.

TYPE

The order type you specify may decide whether other optional parameters are required, as well as how your order will be executed by the matching engine. If order type is not specified, the order will be a limit order by default.

Price and size are required to be specified for a limit order. The order will be filled at the price specified or better, depending on the market condition. If a limit order cannot be filled immediately, it will be outstanding in the open order book until matched by another order, or canceled by the user.

A market order differs from a limit order in that the execution price is not guaranteed. Market order, however, provides a way to buy or sell a specific size of contract without having to specify the price. Market orders will be executed immediately, and no orders will enter the open order book afterwards. Market orders are always considered takers and incur taker fees.

LEVERAGE

The “leverage” parameter is used to calculate the margin to be frozen for the order. If you are to close the position, this parameter is not required.

STOP ORDERS

A stop order is an order to buy or sell at the market or pre-specified limit price once the contact has traded at or through a pre-specified stopPrice. There are two types of stop orders, down and up.

Stop Order Types

• down: Triggers when the price reaches or goes below the stopPrice.
• up: Triggers when the price reaches or goes above the stopPrice.
• stopPriceType: There are three types of stop prices for a contract, including: TP for trade price, MP for mark price, and IP for index price.

The last trade price is the last price at which an order was filled. This price can be found in the latest match message. The mark price and the index price can be obtained through relevant OPEN API for index services.

Note that when triggered, stop orders will be executed as either market or limit orders, depending on the pre-specified type.

When placing a stop order, the system will not pre-freeze the funds in your account. Do note that when triggered, a stop order may be canceled if the available balance is not enough.

PRICE

The price specified must be a multiple number of the contract tickSize, otherwise the system will report an error when you place the order. The tick size is the smallest price increment in which the prices are quoted. A valid price shall not be higher than the maxPrice in the contract specification. Poloniex Futures implements IEPR(Immediately Executable Price Range) rule, in which the price of a buy order cannot be higher than 1.05 * mark price, and the price of a sell order cannot be lower than 0.95 * mark price.

Price field is not required for market orders.

SIZE

The order quantity is the number of contracts, and the unit of measurement for order quantity is the minimum lot size of the contract. The order quantity cannot be less than the minimum order quantity or greater than the maximum order quantity, and must be a multiple of the lot size, otherwise a system error will occur when placing an order. The order quantity represents the size of the contract to be bought or sold. Each BTCUSDTPERP contract corresponds to 0.001BTC.

TIME IN FORCE

Time in force is a special instruction used when placing an order to indicate how long an order will remain active before it is executed or expires. There are two types, Good Till Canceled GTC and Immediate Or Cancel IOC.

• GTC Good Till Canceled: order remains open on the order book until canceled. This is the default type if the field is left empty.
• IOC Immediate Or Cancel: being matched or not, the remaining size of the order will be instantly canceled instead of entering the order book.

Note that self trades belong to match as well.

POST ONLY

The post-only flag ensures that the trader always pays the maker fee and provides liquidity to the order book. If any part of the order is going to pay taker fees, the order will be fully rejected.

HIDDEN AND ICEBERG

The Hidden and iceberg Orders are two options in advanced settings (note: the iceberg order is a special form of the hidden order). You may select “Hidden” or “Iceberg” when placing a limit or stop limit order.

A hidden order will enter but not display on the orderbook.

Different from the hidden order, an iceberg order is divided into visible portion and invisible portion. When placing an iceberg order, you need to set the visible size. The minimum visible size is 1/20 of the order size. The minimum visible size shall be greater than the minimum order size, or an error will occur.

In a matching event, the visible portion of an iceberg order will be executed first, and another visible portion will pop up until the order is fully filled.

Note: 1)The system will charge taker fees for Hidden and iceberg Orders. 2)If both "Iceberg" and "Hidden" are selected, your order will be filled as an iceberg Order by default.

HOLDS

When placing an order, the system will freeze a certain amount of funds in your account for position margin and transaction fees based on the order price and quantity. If not, the order can only be one to reduce the position. If the total amount of these orders exceeds the position size, the system will cancel the extra no-fund-frozen orders to ensure they won’t be executed.

Actual fees are determined when the order is executed. If you cancel a partially filled or unfilled order, any remaining funds will be released from hold and become available.

Different from when an order reduces the position size, certain amount of funds need to be frozen when an order increases the position size. No funds need to be frozen when closeOrder is set to TRUE, or when reduceOnly is set to TRUE.

The execution of the order will incur transaction fees. If a partially filled or unfilled order is canceled, the system will unfreeze the remained frozen funds in your account.

CLOSE ORDER

If closeOrder is set to TRUE, the system will close the position and the position size will become 0. Side, Size and Leverage fields can be left empty and the system will determine the side and size automatically.

CLOSE ONLY

If set to TRUE, only the orders reducing the position size will be executed. If the reduce-only order size exceeds the position size, the extra size will be canceled.

FORCE HOLD

The system will force freeze certain amount of funds for this order, including orders whose direction is opposite to the current positions. This feature is to ensure that the order won’t be canceled by the matching engine in such a circumstance that not enough funds are frozen for the order.

ORDER LIFECYCLE

The HTTP Request will respond when an order is either rejected (insufficient funds, invalid parameters, etc) or received (accepted by the matching engine). A success response with order id indicates that the order has been received. Orders may be execute either partially or fully. After a partial execution, the remaining size of the order will be in active state (excluding IOC orders). A completely filled order will be in done state.

Users listening to streaming market data are encouraged to use the order id and clientOid field to identify their received messages in the feed.

RESPONSE

A successful order will be assigned an order id. A successful order is defined as one that has been accepted by the matching engine.

Open orders will remain open until they are either filled or canceled.

Place Multiple Orders

HTTP Request

POST https://futures-api.poloniex.com/api/v1/batchOrders

API Permission

This endpoint requires the Trade permission

Parameters

Param	type	Description
batchOrders	List	order list. 10 orders at most

batchOrders object detail

Param	type	Description
clientOid	String	Unique order id created by users to identify their orders, e.g. UUID, Only allows numbers, characters, underline(_), and separator(-)
side	String	buy or sell
symbol	String	a valid contract code. e.g. BTCUSDTPERP
type	String	[optional] Either limit or market
leverage	String	Deprecated,Leverage of the order
remark	String	[optional] remark for the order, length cannot exceed 100 utf8 characters
stop	String	[optional] Either down or up. Requires stopPrice and stopPriceType to be defined
stopPriceType	String	[optional] Either TP, IP or MP, Need to be defined if stop is specified.
stopPrice	String	[optional] Need to be defined if stop is specified.
reduceOnly	boolean	[optional] A mark to reduce the position size only. Set to false by default.
closeOrder	boolean	[optional] A mark to close the position. Set to false by default.
forceHold	boolean	[optional] A mark to forcely hold the funds for an order, even though it's an order to reduce the position size. This helps the order stay on the order book and not get canceled when the position size changes. Set to false by default.

See Advanced Description for more details.

LIMIT ORDER PARAMETERS

Param	type	Description
price	String	Limit price
size	Integer	Order size. Must be a positive number
quantity	String	[optional] Order quantity. Must be a positive number. Only takes effect when size is empty
timeInForce	String	[optional] GTC, IOC(default is GTC), read Time In Force
postOnly	boolean	[optional] Post only flag, invalid when timeInForce is IOC. When postOnly chose, not allowed choose hidden or iceberg.
hidden	boolean	Deprecated,[optional] Orders not displaying in order book. When hidden chose, not allowed choose postOnly.
iceberg	boolean	Deprecated,[optional] Only visible portion of the order is displayed in the order book. When iceberg chose, not allowed choose postOnly.
visibleSize	Integer	Deprecated,[optional] The maximum visible size of an iceberg order

MARKET ORDER PARAMETERS

Param	type	Description
size	Integer	[optional] amount of contract to buy or sell
quantity	String	[optional] Order quantity. Must be a positive number. Only takes effect when size is empty

• 10 orders at most
• Paremeter rules are same with New Order
• The order of returned contents for batch orders is the same as the order of the order list.

Example:

Request:

  {
    "batchOrders": 
    [
      {
          "clientOid": "5c52e11203aa677f33e493fb",
          "reduceOnly": false,
          "closeOrder": false,
          "forceHold": false,
          "hidden": false,
          "iceberg": false,
          "leverage": 20,
          "postOnly": false,
          "price": 8000,
          "remark": "remark",
          "side": "buy",
          "size": 20,
          "stop": "",
          "stopPrice": 0,
          "stopPriceType": "",
          "symbol": "BTCUSDTPERP",
          "timeInForce": "",
          "type": "limit",
          "visibleSize": 0
      },
      {
        "clientOid": "5c52e11203aa677f33e493fc",
        "reduceOnly": false,
        "closeOrder": false,
        "forceHold": false,
        "hidden": false,
        "iceberg": false,
        "leverage": 20,
        "postOnly": false,
        "price": 1200,
        "remark": "remark",
        "side": "buy",
        "size": 20,
        "stop": "",
        "stopPrice": 0,
        "stopPriceType": "",
        "symbol": "ETHUSDTPERP",
        "timeInForce": "",
        "type": "limit",
        "visibleSize": 0
      }
    ]
  }

Response:

  {
    "code": "200000",
    "data": [
      {
        "clientOid": "87445124124342",
        "code": "200000",
        "orderId": "5bd6e9286d99522a52e458de"
      },
      {
        "clientOid": "87445124124343",
        "code": "100001",
        "msg": "Price parameter invalid"
      },
      {
        "clientOid": "87445124124344",
        "code": "200000",
        "orderId": "5bd6e9286d99522a52e458dg"
      }
    ]
  }

Cancel an Order

Cancel an order (excluding a stop order).

You will receive a success message once the system has received the cancellation request. The cancellation request will be processed by the matching engine in sequence. To know if the request has been processed, you may check the order status or update message from the pushes.

The order id is the server-assigned order id，not the specified clientOid.

If the order can not be canceled (already filled or previously canceled, etc), then an error response will indicate the reason in the message field.

HTTP Request

DELETE https://futures-api.poloniex.com/api/v1/orders/{order-id}

Example

DELETE https://futures-api.poloniex.com/api/v1/orders/5cdfc120b21023a909e5ad52

API Permission

This endpoint requires the Trade permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 40 times/3s.

State Code

The possible values of "orderState" includes -

orderState	Description
-1	Error validation parameter invalid
-3	Order not found
-4	Contract not found
-5	Order cancellation Paused Temporarily
-6	Contract has been closed or cannot be cancelled
-7	Please terminate the existing grid under this symbol first

Example:

  {
    "code": "200000",
    "data": {
      "cancelFailedOrderIds": [],
      "cancelledOrderIds": [
        "5bd6e9286d99522a52e458de"
      ]
    }
  }

  {
    "code": "100004",
    "data": {
      "cancelFailedOrderIds": [{
        "orderId": "5bd6e9286d99522a52e458de",
        "orderState": -1
      }],
      "cancelledOrderIds": []
    }
  }

Cancel All Limit Order

Cancel all open orders (excluding stop orders). The response is a list of orderIDs of the canceled orders.

HTTP Request

DELETE https://futures-api.poloniex.com/api/v1/orders

Example

DELETE https://futures-api.poloniex.com/api/v1/orders?symbol=BTCUSDTPERP

API Permission

This endpoint requires the Trade permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 1 times/3s.

PARAMETERS

Param	Type	Description
symbol	String	[optional] Cancel all limit orders for a specific contract only
side	String	[optional] buy or sell

You can delete specific symbols using query parameters. If not specified, all the limit orders will be deleted.

State Code

The possible values of "orderState" includes -

orderState	Description
-1	Error validation parameter invalid
-3	Order not found
-4	Contract not found
-5	Order cancellation Paused Temporarily
-6	Contract has been closed or cannot be cancelled
-7	Please terminate the existing grid under this symbol first

Example:

  {
    "code": "200000",
    "data": {
      "cancelFailedOrderIds": [],
      "cancelledOrderIds": [
        "5c52e11203aa677f33e493fb",
        "5c52e12103aa677f33e493fe",
        "5c6265c503aa676fee84129c",
        "5c6269e503aa676fee84129f",
        "5c626b0803aa676fee8412a2"
      ]
    } 
  }

Cancel Multiple Limit Orders

Cancel multiple open orders (excluding stop orders). The response is a list of orderIDs (or clientOids) of the canceled orders.

HTTP Request

DELETE https://futures-api.poloniex.com/api/v1/batchOrders

API Permission

This endpoint requires the Trade permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 3 times/3s.

PARAMETERS

Param	Type	Description
orderIds	List<String>	[optional] system order id, supports up to 10 orders
clientOids	List<String>	[optional] client order id, supports up to 10 orders

orderIds and clientOids must be filled at least one, if both are set, the default is orderIds to cancel the order.

State Code

The possible values of "orderState" includes -

orderState	Description
-1	Error validation parameter invalid
-3	Order not found
-4	Contract not found
-5	Order cancellation Paused Temporarily
-6	Contract has been closed or cannot be cancelled
-7	Please terminate the existing grid under this symbol first

Example:

Request:

  {
     "orderIds": [
       "5c52e11203aa677f33e493fb",
       "5c52e12103aa677f33e493fe",
       "5c6265c503aa676fee84129c",
       "5c6269e503aa676fee84129f",
       "5c626b0803aa676fee8412a2"
     ]
  }

Response:

  {
    "code": "200000",
    "data": {
      "cancelFailedOrders": [{
        "orderId": "5bd6e9286d99522a52e458de",
        "clientOid": "5c52e11203aa677f33e493fc",
        "orderState": -1
      }],
      "cancelledIds": [
        "5c52e11203aa677f33e493fb",
        "5c52e12103aa677f33e493fe",
        "5c6265c503aa676fee84129c",
        "5c6269e503aa676fee84129f",
        "5c626b0803aa676fee8412a2"
      ]
    } 
  }

Cancel All Stop Order

  {
    "code": "200000",
    "data": {
      "cancelFailedOrderIds": [],
      "cancelledOrderIds": [
        "5c52e11203aa677f33e49311",
        "5c52e12103aa677f33e49322"
      ]
    }
  }

Cancel all untriggered stop orders. The response is a list of orderIDs of the canceled stop orders. To cancel triggered stop orders, please use 'Limit Order Mass Cancelation'.

HTTP Request

DELETE https://futures-api.poloniex.com/api/v1/stopOrders

Example

DELETE https://futures-api.poloniex.com/api/v1/stopOrders?symbol=BTCUSDTPERP

API Permission

This endpoint requires the Trade permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 2 times/10s.

PARAMETERS

You can delete specific symbols using query parameters.

Param	Type	Description
symbol	String	[optional] Cancel all untriggered stop orders for a specific contract only

State Code

The possible values of "orderState" includes -

orderState	Description
2	Order was already closed in the long past (order state = canceled)
3	Order was already closed in the long past (order state = partial-canceled)
4	Order was already closed in the long past (order state = filled)
5	Order was already closed in the long past (order state = partial-filled)
-1	Error validation parameter invalid
-3	Order not found
-4	Contract not found
-5	Order cancellation Paused Temporarily
-6	Contract has been closed or cannot be cancelled

Get Order List(Deprecated)

List your current orders.

HTTP Request

GET https://futures-api.poloniex.com/api/v1/orders

Example

GET https://futures-api.poloniex.com/api/v1/orders?status=active

Submit the request to get all the active orders.

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 30 times/3s.

PARAMETERS

You can request data for specific orders using query parameters.

Param	Type	Description
status	String	[optional] active or done, done as default. Only list orders for a specific status
symbol	String	[optional] Symbol of the contract
side	String	[optional] buy or sell
type	String	[optional] limit, market, limit_stop or market_stop
startAt	long	[optional] Start time (millisecond)
endAt	long	[optional] End time (millisecond)
marginType	Number	[optional] 0 (Isolated) or 1 (Cross)

This request is paginated.

Order Status and Settlement

Any limit order on the exchange order book is in active status. Orders removed from the order book will be marked with done status. After an order becomes done, there may be a few milliseconds latency before it’s fully settled.

You can check the orders in any status. If the status parameter is not specified, orders of done status will be returned by default.

When you query orders in active status, there is no time limit. However, when you query orders in done status, the start and end time range cannot exceed 24*7 hours. An error will occur if the specified time window exceeds the range. If you specify the end time only, the system will automatically calculate the start time as end time minus 24 hours, and vice versa.

POLLING

For high-volume trading, it is highly recommended that you maintain your own list of open orders and use one of the streaming market data feeds to keep it updated. You should poll the open orders endpoint to obtain the current state of any open order.

If you need to get your recent trade history with low latency, you may query the endpoint Get List of Orders Completed in 24h.

Example:

  {
   "code": "200000",
    "data": {
      "currentPage": 1,
      "pageSize": 100,
      "totalNum": 1000,
      "totalPage": 10,
      "items": [
        {
          "id": "5cdfc138b21023a909e5ad55", //Order ID
          "symbol": "BTCUSDTPERP",  //Ticker symbol of the contract
          "type": "limit",   //Order type, market order or limit order
          "side": "buy",  //Transaction side
          "price": "3600",  //Order price
          "size": 20000,  //Order quantity
          "value": "56.1167227833",  //Order value
          "filledValue": "0",  //Value of the executed orders
          "filledSize": 0,  //Executed order quantity
          "stp": "",  //Self trade prevention types
          "stop": "",  //Stop order type (stop limit or stop market) 
          "stopPriceType": "",  //Trigger price type of stop orders 
          "stopTriggered": false,  //Mark to show whether the stop order is triggered
          "stopPrice": null,  //Trigger price of stop orders
          "timeInForce": "GTC",  //Time in force policy type 
          "postOnly": false,  // Mark of post only
          "hidden": false,  //Mark of the hidden order
          "iceberg": false,  //Mark of the iceberg order 
          "visibleSize": null,  //Visible size of the iceberg order
          "leverage": "20",  //Leverage of the order
          "forceHold": false,  //A mark to forcely hold the funds for an order 
          "closeOrder": false, //A mark to close the position 
          "reduceOnly": false,  //A mark to reduce the position size only
          "clientOid": "5ce24c16b210233c36ee321d",  //Unique order id created by users to identify their orders  
          "remark": null,  //Remark of the order 
          "isActive": true,  //Mark of the active orders
          "cancelExist": false,  //Mark of the canceled orders
          "createdAt": 1558167872000,  //Time the order created
          "settleCurrency": "XBT", //settlement currency
          "status": "open", //order status: “open” or “done”
          "updatedAt": 1558167872000, //last update time
          "orderTime": 1558167872000000000 //order create time in nanosecond
        }
      ]
    }  
 }

Get Untriggered Stop Order List

Get the un-triggered stop orders list.

HTTP Request

GET https://futures-api.poloniex.com/api/v1/stopOrders

Example

GET https://futures-api.poloniex.com/api/v1/stopOrders?symbol=BTCUSDTPERP

Query this endpoint to get the untriggered stop orders of the position in BTCUSDTPERP.

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 9 times/3s.

PARAMETERS

You can request for specific orders using query parameters.

Param	Type	Description
symbol	String	[optional] Symbol of the contract
side	String	[optional] buy or sell
type	String	[optional] limit, market
startAt	long	[optional] Start time (millisecond)
endAt	long	[optional] End time (millisecond)
marginType	Number	[optional] 0 (Isolated) or 1 (Cross)

This request is paginated.

Example:

  {
    "code": "200000",
    "data": {
      "currentPage": 1,
      "pageSize": 100,
      "totalNum": 1000,
      "totalPage": 10,
      "items": [
        {
            "id": "5cdfc138b21023a909e5ad55", //Order ID
            "symbol": "BTCUSDTPERP",  //Ticker symbol of the contract 
            "type": "limit",   //Order type, market order or limit order
            "marginType": 0,   //Margin Mode, 0 (Isolated) or 1 (Cross)
            "side": "buy",  //Transaction side
            "price": "3600",  //Order price
            "size": 20000,  //Order quantity
            "value": "56.1167227833",  //Order value
            "filledValue": "0",  //Value of the executed orders
            "filledSize": 0,  //Executed order quantity
            "stp": "",  //Self trade prevention types
            "stop": "",  //Stop order type (stop limit or stop market) 
            "stopPriceType": "",  //Trigger price type of stop orders
            "stopTriggered": false,  //Mark to show whether the stop order is triggered
            "stopPrice": null,  //Trigger price of stop orders
            "timeInForce": "GTC",  //Time in force policy type
            "postOnly": false,  //Mark of post only
            "hidden": false,  //Mark of the hidden order
            "iceberg": false,  //Mark of the iceberg order
            "visibleSize": null,  //Visible size of the iceberg order
            "leverage": "20",  //Leverage of the order
            "forceHold": false,  //A mark to forcely hold the funds for an order
            "closeOrder": false, //A mark to close the position
            "reduceOnly": false,  //A mark to reduce the position size only
            "clientOid": "5ce24c16b210233c36ee321d",  //Unique order id created by users to identify their orders 
            "remark": null,  //Remark of the order
            "isActive": true,  //Mark of the active orders
            "cancelExist": false,  //Mark of the canceled orders
            "createdAt": 1558167872000,  //Time the order created
            "settleCurrency": "XBT", //settlement currency
            "status": "open", //order status: “open” or “done”
            "updatedAt": 1558167872000 //last update time
        }
      ]
    }
 }

Get List of Orders Completed in 24h

Get a list of recent 1000 orders in the last 24 hours.

If you need to get your recent traded order history with low latency, you may query this endpoint.

HTTP Request

GET https://futures-api.poloniex.com/api/v1/recentDoneOrders

Example

GET https://futures-api.poloniex.com/api/v1/recentDoneOrders

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 3 times/3s.

Example:

  {
    "code": "200000",
    "data":[
       {
            "id": "5cdfc138b21023a909e5ad55", //Order ID
            "symbol": "BTCUSDTPERP",  //Ticker symbol of the contract
            "type": "limit",   //Order type, market order or limit order
            "marginType": 0,   //Margin Mode, 0 (Isolated) or 1 (Cross)
            "side": "buy",  //Transaction side
            "price": "3600",  //Order price
            "size": 20000,  //Order quantity
            "value": "56.1167227833",  //Order value
            "filledValue": "56.1167227833",  //Value of the executed orders
            "filledSize": 20000,  //Executed order quantity
            "stp": "",  //Self trade prevention types
            "stop": "",  //Stop order type (stop limit or stop market) 
            "stopPriceType": "",  //Trigger price type of stop orders
            "stopTriggered": true,  //Mark to show whether the stop order is triggered
            "stopPrice": null,  //Trigger price of stop orders
            "timeInForce": "GTC",  //Time in force policy type
            "postOnly": false,  //Mark of post only
            "hidden": false,  //Deprecated,Mark of the hidden order
            "iceberg": false,  //Deprecated,Mark of the iceberg order
            "visibleSize": null,  //Deprecated, Visible size of the iceberg order
            "leverage": "20",  //Leverage of the order
            "forceHold": false,  //A mark to forcely hold the funds for an order
            "closeOrder": false, //A mark to close the position
            "reduceOnly": false,  //A mark to reduce the position size only
            "clientOid": "5ce24c16b210233c36ee321d",  //Unique order id created by users to identify their orders
            "remark": null,  //Remark of the order
            "isActive": false,  //Mark of the active orders
            "cancelExist": false,  //Mark of the canceled orders
            "createdAt": 1558167872000,  //Time the order created
            "settleCurrency": "XBT", //settlement currency
            "status": "done", //order status: “open” or “done”
            "updatedAt": 1558167872000, //last update time
            "orderTime": 1558167872000000000 //order create time in nanosecond
          }
      ]
 }

Get Details of a Single Order

Get a single order by order id (including a stop order).

HTTP Request

GET https://futures-api.poloniex.com/api/v1/orders/{order-id}

Example

GET https://futures-api.poloniex.com/api/v1/orders/5cdfc138b21023a909e5ad55

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 40 times/3s.(share the rate limit with the Get Single Order by clientOid)

Example:

  {
    "code": "200000",
    "data": {
      "id": "5cdfc138b21023a909e5ad55", //Order ID
      "symbol": "BTCUSDTPERP",  //Ticker symbol of the contract
      "type": "limit",   //Order type, market order or limit order
      "side": "buy",  //Transaction side
      "price": "3600",  //Order price 
      "size": 20000,  //Order quantity
      "value": "56.1167227833",  //Order value
      "filledValue": "56.1167227833",  //Value of the executed orders
      "filledSize": 20000,  //Executed order quantity
      "stp": "",  //Self trade prevention types
      "stop": "",  //Stop order type (stop limit or stop market)
      "stopPriceType": "",  //Trigger price type of stop orders
      "stopTriggered": true,  //Mark to show whether the stop order is triggered
      "stopPrice": null,  //Trigger price of stop orders
      "timeInForce": "GTC",  //Time in force policy types
      "postOnly": false,  //Mark of post only
      "hidden": false,  //Deprecated,Mark of the hidden order
      "iceberg": false,  //Deprecated,Mark of the iceberg order
      "visibleSize": null,  //Deprecated,Visible size of the iceberg order
      "leverage": "20",  //Leverage of the order
      "forceHold": false,  //A mark to forcely hold the funds for an order
      "closeOrder": false, //A mark to close the position
      "reduceOnly": false,  //A mark to reduce the position size only
      "clientOid": "5ce24c16b210233c36ee321d",  //Unique order id created by users to identify their orders
      "remark": null,  //Remarks of the order
      "isActive": false,  //Mark of the active orders
      "cancelExist": false,  //Mark of the canceled orders
      "createdAt": 1558167872000,  //Time the order created
      "settleCurrency": "XBT", //settlement currency
      "status": "done", //order status: “open” or “done” or “invalid”
      "updatedAt": 1558167872000, //last update time
      "orderTime": 1558167872000000000, //order create time in nanosecond
      "trades": [
                  {
                    "feePay": 0.184,//Transaction Service fee
                    "tradeId": "63be8bfde9edc70006715958"
                  }
                ]
    }
}

Get Single Order by clientOid

Get Single Order by clientOid (including a stop order).

HTTP Request

GET https://futures-api.poloniex.com/api/v1/clientOrderId/{clientOid}

Example

GET https://futures-api.poloniex.com/api/v1/clientOrderId/5cdfc138b21023a909e5ad55

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 40 times/3s.(share the rate limit with the Get Details of a Single Order)

Example:

  {
    "code": "200000",
    "data": {
      "id": "5cdfc138b21023a909e5ad55", //Order ID
      "symbol": "BTCUSDTPERP",  //Ticker symbol of the contract
      "type": "limit",   //Order type, market order or limit order
      "side": "buy",  //Transaction side
      "price": "3600",  //Order price 
      "size": 20000,  //Order quantity
      "value": "56.1167227833",  //Order value
      "filledValue": "56.1167227833",  //Value of the executed orders
      "filledSize": 20000,  //Executed order quantity
      "stp": "",  //Self trade prevention types
      "stop": "",  //Stop order type (stop limit or stop market)
      "stopPriceType": "",  //Trigger price type of stop orders
      "stopTriggered": true,  //Mark to show whether the stop order is triggered
      "stopPrice": null,  //Trigger price of stop orders
      "timeInForce": "GTC",  //Time in force policy types
      "postOnly": false,  //Mark of post only
      "hidden": false,  //Mark of the hidden order
      "iceberg": false,  //Mark of the iceberg order
      "visibleSize": null,  //Visible size of the iceberg order
      "leverage": "20",  //Leverage of the order
      "forceHold": false,  //A mark to forcely hold the funds for an order
      "closeOrder": false, //A mark to close the position
      "reduceOnly": false,  //A mark to reduce the position size only
      "clientOid": "5ce24c16b210233c36ee321d",  //Unique order id created by users to identify their orders
      "remark": null,  //Remarks of the order
      "isActive": false,  //Mark of the active orders
      "cancelExist": false,  //Mark of the canceled orders
      "createdAt": 1558167872000,  //Time the order created
      "settleCurrency": "XBT", //settlement currency
      "status": "done", //order status: “open” or “done”or “invalid”
      "updatedAt": 1558167872000, //last update time
      "orderTime": 1558167872000000000, //order create time in nanosecond
      "trades": [
                  {
                    "feePay": 0.184,//Transaction Service fee
                    "tradeId": "63be8bfde9edc70006715958"
                  }
                ] 
    }
}

Get Order List V2

List your historical orders.

HTTP Request

GET https://futures-api.poloniex.com/api/v2/orders

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 30 times/3s.

Parameters

Parameter	Required	Type	Description
status	NO	String	active or done, done as default. Only list orders for a specific status
symbol	NO	String	Symbol of the contract
side	NO	String	buy or sell
type	NO	String	limit, market, limit_stop or market_stop
startAt	NO	long	Start time (millisecond)
endAt	NO	long	End time (millisecond)
marginType	NO	Number	0 (Isolated) or 1 (Cross)
from	NO	String	The starting id of the query, use the nextId in the response result, and pass 0 for the first time
direct	NO	String	PREV - page forward; means starting from the starting id, querying in ascending orderNEXT - page forward; means starting from the starting id, querying in descending order
limit	NO	int	Limit of items per page

Example:

    {
   "code": "200000",
    "data": {
      "beforeId": "285013592909307905"
      "hasMore": false,
      "items": [
        {
          "id": "5cdfc138b21023a909e5ad55", //Order ID
          "symbol": "BTCUSDTPERP",  //Ticker symbol of the contract
          "type": "limit",   //Order type, market order or limit order
          "side": "buy",  //Transaction side
          "price": "3600",  //Order price
          "size": 20000,  //Order quantity
          "value": "56.1167227833",  //Order value
          "filledValue": "0",  //Value of the executed orders
          "filledSize": 0,  //Executed order quantity
          "stp": "",  //Self trade prevention types
          "stop": "",  //Stop order type (stop limit or stop market) 
          "stopPriceType": "",  //Trigger price type of stop orders 
          "stopTriggered": false,  //Mark to show whether the stop order is triggered
          "stopPrice": null,  //Trigger price of stop orders
          "timeInForce": "GTC",  //Time in force policy type 
          "postOnly": false,  // Mark of post only
          "hidden": false,  //Mark of the hidden order
          "iceberg": false,  //Mark of the iceberg order 
          "visibleSize": null,  //Visible size of the iceberg order
          "leverage": "20",  //Leverage of the order
          "forceHold": false,  //A mark to forcely hold the funds for an order 
          "closeOrder": false, //A mark to close the position 
          "reduceOnly": false,  //A mark to reduce the position size only
          "clientOid": "5ce24c16b210233c36ee321d",  //Unique order id created by users to identify their orders  
          "remark": null,  //Remark of the order 
          "isActive": true,  //Mark of the active orders
          "cancelExist": false,  //Mark of the canceled orders
          "createdAt": 1558167872000,  //Time the order created
          "settleCurrency": "XBT", //settlement currency
          "status": "open", //order status: “open” or “done”
          "updatedAt": 1558167872000, //last update time
          "orderTime": 1558167872000000000 //order create time in nanosecond
        }
      ],
    "nextId": "285013109771624448"
    }  
 }

Get Current Tpsl Orders

get tpsl orders that are not currently triggered

HTTP Request

GET https://futures-api.poloniex.com/api/v2/orders/tpsl/opens

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 10 times/1s.

Parameters

Parameter	Required	Type	Description
side	NO	String	buy or sell
symbol	NO	String	Symbol of the contract
from	NO	Long	The starting id of the query, use the nextId in the response result, and pass 0 for the first time
direct	NO	String	PREV - page forward; means starting from the starting id, querying in ascending orderNEXT - page forward; means starting from the starting id, querying in descending order
limit	NO	int	Limit of items per page

Example:

{
  "code": "200000",
  "data": [
    {
      "algoId": "354954328047648768",
      "side": "BUY",
      "slOrdPx": "-1",
      "slTriggerPx": "2347.37",
      "slTriggerPxType": "MARK",
      "symbol": "ETHUSDTPERP",
      "tpOrdPx": "2210",
      "tpTriggerPx": "2210.63",
      "tpTriggerPxType": "INDEX"
    },
    {
      "algoId": "354699935620558848",
      "side": "BUY",
      "slOrdPx": "-1",
      "slTriggerPx": "60993.427",
      "slTriggerPxType": "MARK",
      "symbol": "BTCUSDTPERP",
      "tpOrdPx": "-1",
      "tpTriggerPx": "57440.412",
      "tpTriggerPxType": "MARK"
    }
  ],
  "msg": "Success"
}

Get Current Tpsl Order History

Get the list of all tpsl orders in the past three months.

HTTP Request

GET https://futures-api.poloniex.com/api/v2/orders/tpsl/history

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 10 times/1s.

Parameters

Parameter	Required	Type	Description
side	NO	String	buy or sell
symbol	NO	String	Symbol of the contract
algoId	NO	String	Algo order ID
state	NO	String	CANCEL、TRIGGER、FAIL
from	NO	Long	The starting id of the query, use the nextId in the response result, and pass 0 for the first time
direct	NO	String	PREV - page forward; means starting from the starting id, querying in ascending orderNEXT - page forward; means starting from the starting id, querying in descending order
limit	NO	int	Limit of items per page

Example:

{
  "code": "200000",
  "data": [
    {
      "actualPx": "2529.6",
      "actualSide": "TP",
      "actualSz": "-1",
      "algoId": "353863239827984384",
      "ordId": "353864996930990080",
      "side": "BUY",
      "slOrdPx": "-1",
      "slTriggerPx": "2530",
      "slTriggerPxType": "LAST",
      "state": "TRIGGER",
      "symbol": "ETHUSDTPERP",
      "tpOrdPx": "-1",
      "tpTriggerPx": "2529.6",
      "tpTriggerPxType": "LAST",
      "triggerTime": "1725334389819"
    },
    {
      "actualPx": "0.1522",
      "actualSide": "SL",
      "actualSz": "1",
      "algoId": "349872304232431616",
      "ordId": "349872306753118208",
      "side": "SELL",
      "slOrdPx": "-1",
      "slTriggerPx": "0.1522",
      "slTriggerPxType": "MARK",
      "state": "TRIGGER",
      "symbol": "TRXUSDTPERP",
      "tpOrdPx": "-1",
      "tpTriggerPx": "20.1522",
      "tpTriggerPxType": "MARK",
      "triggerTime": "1724382458248"
    },
    {
      "actualPx": "2397.6",
      "actualSide": "TP",
      "actualSz": "10",
      "algoId": "348899996181274624",
      "ordId": "348901500493504512",
      "side": "SELL",
      "slOrdPx": "2394",
      "slTriggerPx": "2395",
      "slTriggerPxType": "LAST",
      "state": "TRIGGER",
      "symbol": "ETHUSDTPERP",
      "tpOrdPx": "2399",
      "tpTriggerPx": "2397.5",
      "tpTriggerPxType": "LAST",
      "triggerTime": "1724151000006"
    }
  ],
  "msg": "Success"
}