Skip to main content

Orders

danger

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​

ParamtypeDescription
clientOidStringUnique order id created by users to identify their orders, e.g. UUID, Only allows numbers, characters, underline(_), and separator(-)
sideStringbuy or sell
symbolStringa valid contract code. e.g. BTCUSDTPERP
typeString[optional] Either limit or market
leverageStringDeprecated,Leverage of the order
remarkString[optional] remark for the order, length cannot exceed 100 utf8 characters
stopString[optional] Either down or up. Requires stopPrice and stopPriceType to be defined
stopPriceTypeString[optional] Either TP, IP or MP, Need to be defined if stop is specified.
stopPriceString[optional] Need to be defined if stop is specified.
reduceOnlyboolean[optional] A mark to reduce the position size only. Set to false by default.
closeOrderboolean[optional] A mark to close the position. Set to false by default.
forceHoldboolean[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​

ParamtypeDescription
priceStringLimit price
sizeIntegerOrder size. Must be a positive number
quantityString[optional] Order quantity. Must be a positive number. Only takes effect when size is empty
timeInForceString[optional] GTC, IOC(default is GTC), read Time In Force
postOnlyboolean[optional] Post only flag, invalid when timeInForce is IOC. When postOnly chose, not allowed choose hidden or iceberg.
hiddenbooleanDeprecated,[optional] Orders not displaying in order book. When hidden chose, not allowed choose postOnly.
icebergbooleanDeprecated,[optional] Only visible portion of the order is displayed in the order book. When iceberg chose, not allowed choose postOnly.
visibleSizeIntegerDeprecated,[optional] The maximum visible size of an iceberg order

MARKET ORDER PARAMETERS​

ParamtypeDescription
sizeInteger[optional] amount of contract to buy or sell
quantityString[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​

ParamtypeDescription
batchOrdersListorder list. 10 orders at most

batchOrders object detail​

ParamtypeDescription
clientOidStringUnique order id created by users to identify their orders, e.g. UUID, Only allows numbers, characters, underline(_), and separator(-)
sideStringbuy or sell
symbolStringa valid contract code. e.g. BTCUSDTPERP
typeString[optional] Either limit or market
leverageStringDeprecated,Leverage of the order
remarkString[optional] remark for the order, length cannot exceed 100 utf8 characters
stopString[optional] Either down or up. Requires stopPrice and stopPriceType to be defined
stopPriceTypeString[optional] Either TP, IP or MP, Need to be defined if stop is specified.
stopPriceString[optional] Need to be defined if stop is specified.
reduceOnlyboolean[optional] A mark to reduce the position size only. Set to false by default.
closeOrderboolean[optional] A mark to close the position. Set to false by default.
forceHoldboolean[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​

ParamtypeDescription
priceStringLimit price
sizeIntegerOrder size. Must be a positive number
quantityString[optional] Order quantity. Must be a positive number. Only takes effect when size is empty
timeInForceString[optional] GTC, IOC(default is GTC), read Time In Force
postOnlyboolean[optional] Post only flag, invalid when timeInForce is IOC. When postOnly chose, not allowed choose hidden or iceberg.
hiddenbooleanDeprecated,[optional] Orders not displaying in order book. When hidden chose, not allowed choose postOnly.
icebergbooleanDeprecated,[optional] Only visible portion of the order is displayed in the order book. When iceberg chose, not allowed choose postOnly.
visibleSizeIntegerDeprecated,[optional] The maximum visible size of an iceberg order

MARKET ORDER PARAMETERS​

ParamtypeDescription
sizeInteger[optional] amount of contract to buy or sell
quantityString[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 -

orderStateDescription
-1Error validation parameter invalid
-3Order not found
-4Contract not found
-5Order cancellation Paused Temporarily
-6Contract has been closed or cannot be cancelled
-7Please 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​

ParamTypeDescription
symbolString[optional] Cancel all limit orders for a specific contract only
sideString[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 -

orderStateDescription
-1Error validation parameter invalid
-3Order not found
-4Contract not found
-5Order cancellation Paused Temporarily
-6Contract has been closed or cannot be cancelled
-7Please 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​

ParamTypeDescription
orderIdsList<String>[optional] system order id, supports up to 10 orders
clientOidsList<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 -

orderStateDescription
-1Error validation parameter invalid
-3Order not found
-4Contract not found
-5Order cancellation Paused Temporarily
-6Contract has been closed or cannot be cancelled
-7Please 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.

ParamTypeDescription
symbolString[optional] Cancel all untriggered stop orders for a specific contract only

State Code​

The possible values of "orderState" includes -

orderStateDescription
2Order was already closed in the long past (order state = canceled)
3Order was already closed in the long past (order state = partial-canceled)
4Order was already closed in the long past (order state = filled)
5Order was already closed in the long past (order state = partial-filled)
-1Error validation parameter invalid
-3Order not found
-4Contract not found
-5Order cancellation Paused Temporarily
-6Contract 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.

ParamTypeDescription
statusString[optional] active or done, done as default. Only list orders for a specific status
symbolString[optional] Symbol of the contract
sideString[optional] buy or sell
typeString[optional] limit, market, limit_stop or market_stop
startAtlong[optional] Start time (millisecond)
endAtlong[optional] End time (millisecond)
marginTypeNumber[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.

ParamTypeDescription
symbolString[optional] Symbol of the contract
sideString[optional] buy or sell
typeString[optional] limit, market
startAtlong[optional] Start time (millisecond)
endAtlong[optional] End time (millisecond)
marginTypeNumber[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

ParameterRequiredTypeDescription
statusNOStringactive or done, done as default. Only list orders for a specific status
symbolNOStringSymbol of the contract
sideNOStringbuy or sell
typeNOStringlimit, market, limit_stop or market_stop
startAtNOlongStart time (millisecond)
endAtNOlongEnd time (millisecond)
marginTypeNONumber0 (Isolated) or 1 (Cross)
fromNOStringThe starting id of the query, use the nextId in the response result, and pass 0 for the first time
directNOStringPREV - page forward; means starting from the starting id, querying in ascending orderNEXT - page forward; means starting from the starting id, querying in descending order
limitNOintLimit 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

ParameterRequiredTypeDescription
sideNOStringbuy or sell
symbolNOStringSymbol of the contract
fromNOLongThe starting id of the query, use the nextId in the response result, and pass 0 for the first time
directNOStringPREV - page forward; means starting from the starting id, querying in ascending orderNEXT - page forward; means starting from the starting id, querying in descending order
limitNOintLimit 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

ParameterRequiredTypeDescription
sideNOStringbuy or sell
symbolNOStringSymbol of the contract
algoIdNOStringAlgo order ID
stateNOStringCANCEL、TRIGGER、FAIL
fromNOLongThe starting id of the query, use the nextId in the response result, and pass 0 for the first time
directNOStringPREV - page forward; means starting from the starting id, querying in ascending orderNEXT - page forward; means starting from the starting id, querying in descending order
limitNOintLimit 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"
}