Orders

The orders channel provides APIs to place and cancel orders.

The order object

Both the orders message you send and the orderResponses message you receive contain the Order object payload.

The attributes that you send and receive depend on the requested action and order type.

Order object example

{ "coId":"req7",
  "type":"Limit",
  "timeInForce":"GTC",
  "side":"Buy",
  "currency":"EUR",
  "symbol":"EUR/USD",
  "size":50000.0,
  "org":"MDFFI1",
  "price":1.18923,
  "averagePrice":0.7835,
  "cumQty":50000.0,
  "execId":"FXI4110748548",
  "lastPrice":0.7835,
  "lastQty":50000.0,
  "orderId":"91529825282",
  "valueDate":"20210720",
  "tradeDate":"20210716",
  "settlCurrAmt":39175.0,
  "executionType":"TRADE",
  "leavesQty":0.0,
  "counterParty":"cptyA",
  "transactTime": 1664268780195,
  "action":"place",
  "userFullName":"user1@MAIN.C417",
  "transactTime":1628166823430,
  "status":"FILLED"
}

Attribute	Description
`coId`	string, max size 255: (required) Client order ID assigned by the API user.
`type`	string: (required) `Market`, `Limit`, `Stop`, `StopLimit`, `Pegged`, `Algo`
`timeInForce`	string: (required) `GTC`, `IOC`, `FOK`, `GTT`, `DAY`
`side`	string: (required) `Buy` or `Sell` from the order placer's perspective and always for the dealt currency.
`currency`	string: (required) Dealt currency.
`symbol`	string: (required) Base and term currency separated by a slash "/" (for example `EUR/USD`).
`size`	double: (required) Order amount.
`rateId`	string: Unique identifier for rate. Required for Previously Quoted Orders.
`org`	string (conditional): Organization ID in Integral's system. If placing an order on behalf of another organization, this parameter is required and contains the other organization's ID.
`clientOrderTime`	string: Time the order was submitted in the format `yyyy-MM-dd HH:mm:ss,SSS Z`.
`account`	string: Your organization's account (legal entity).
`price`	double: Order's limit price.
`stopPrice`	double: Stop price for stop orders.
`expiryTime`	long, max value 86399: Expiry time when `timeInForce`=GTT. In seconds. Max value is one day (86399 seconds).
`targetStrategy`	string: `Mid`, `Fixing`, `Twap`, `LitSwitch`, `DarkSwitch`
`originalCoId`	string: The original client order ID of the order to be cancelled or replaced by this request.
`stopPrice`	double: Order's stop price (if any).
`execFlags`	List of strings: Execution strategy requested with order: `BidTrigger`: Stay on bid side, `MidTrigger`: Mid price, `OfferTrigger`: Stay on offer side
`minQty`	double: Minimum fill size (if any) in dealt currency.
`maxShow`	double: Amount of the order visible to other market participants: 0 (zero) or undefined: Hidden: Order is not visible to other customers. Equal to `size`: Display: Full order amount visible to other customers. Less than `size`: Iceberg: Only the value of `maxShow` visible.
`averagePrice`	double: Average price of all fills so far.
`cumQty`	double: Total cumulative amount filled so far.
`orderId`	string: Order ID assigned by Integral.
`valueDate`	string: Value date in the format `YYYY-MM-DD`.
`tradeDate`	string: Trade date of fill in the format `YYYY-MM-DD`.
`executionType`	string: `CANCELED`, `NEW`, `PARTIAL_FILL`, `PENDING_NEW`, `TRADE`
`leavesQty`	double: Unfilled amount as of the most recent fill.
`counterParty`	string: Counterparty organization ID.
`counterPartyAccount`	string: Counterparty legal entity ID.
`transactTime`	long: UTC time of last event on the order in milliseconds.
`action`	string: `place`, `cancel`, `cancelAll`
`userFullName`	string: Fully qualified user name of order submitting user, including namespace and organization ID in the format `userName`@`namespace`.`orgID`.
`status`	string: `RECEIVED`, `NEW`, `PARTIALLY_FILLED`, `FILLED`, `PENDING_CANCEL`, `CANCELED`, `REPLACED`, `STOPPED`, `REJECTED`, `EXPIRED`, `FAILED`
`reason`	string: Orders with `status=Failed` or `status=Failed`, the reason for failure or rejection.
`customerId`	string: Customer ID on whose behalf the order is placed.
`executionStartTime`	string: Relative time at which the strategy should start execution specified in the format `HH:MM:SS.sss`. If not specified, the strategy starts executing immediately.
`executionEndTime`	string: Absolute time in GMT at which the strategy should stop executing in the format `yyyy-MM-dd HH:mm:ss,SSS Z`. If not specified, the order expires based on the value of its time in force.
`pegPriceType`	string: Mid: Pegged to mid rate.
`pegOffsetValue`	double: The amount in pips that is added to the price of the peg. Can be positive or negative.
`actionOnExpiry`	string: Action taken at the end of the algo’s duration if there is an unfilled amount remaining. If not specified, the order is cancelled at expiration. NoAction, FillAtMarket, Twap
`sliceSize`	double: TWAP order: The fixed size of each slice.
`passiveTime`	int: Time for which each slice rests in OCX RiskNet. Specified in milliseconds. Overrides `passiveTimeFactor`.
`passiveTimeFactorPercentage`	double: Determines how long each slice rests in OCX RiskNet, calculated as a percent of the actual slice interval. Required if `passiveTime` is not set
`sliceInterval`	int: TWAP order: Interval between slices. If the interval is fixed, this value is the interval duration. If the interval is randomized, this value is the upper boundary of random values.
`randomizeSliceSizePercentage`	double: The percentage range that the `sliceSize` is randomized.
`randomizeSliceIntervalPercentage`	double: The percentage range that the `sliceInterval` is randomized.
`tobRange`	double: If `sliceSize` undefined, the slice size is this percentage of the top-of-book price size.

Place order

Place a new order. You can place various types of order such as limit, market, stop, algo, pegged, and more. Under algo orders you can execute various strategies such as TWAP.

Place limit order (GTC) example

{ "orders": 
  [ { "coId":"Order25",
      "type":"Limit",
      "side":"Buy",
      "symbol":"EUR/USD",
      "currency":"EUR",
      "size":1000000,
      "price":1.1867,
      "timeInForce":"GTC"
    }
  ]
}

Request body

{ "orders":["order object"] }

Request parameters

The required attributes on the order object depend on the order type.

Order Type	Required Attributes
Limit(GTC)	`coId, type=Limit, side, symbol, size, price, currency,` `timeInForce=GTC`
Limit(GTT)	`coId, type=Limit, side, symbol, size, price, currency,` `timeInForce=GTT, expiryTime`
Market(GTT)	`coId, type=Market, side, symbol, size, price, currency,` `timeInForce=GTT, expiryTime`
Place: Stop	`coId, type=Stop, side, symbol, size, price, currency,` `stopPrice, timeInForce, execFlags=BidTrigger\| OfferTrigger\| MidTrigger`

Place order response filled example

{"orderResponses":[
    { "coId":"Mid9",
      "type":"Algo",
      "timeInForce":"GTC",
      "side":"Buy",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":1000000.0,
      "org":"C417",
      "averagePrice":1.18642,
      "cumQty":1000000.0,
      "execId":"FXI9190073000",
      "lastPrice":1.18642,
      "lastQty":1000000.0,
      "orderId":"4793444872",
      "valueDate":"20210809",
      "tradeDate":"20210805",
      "settlCurrAmt":1186420.0,
      "executionType":"TRADE",
      "leavesQty":0.0,
      "counterParty":"cptyA",
      "userFullName":"user1@MAIN.C417",
      "transactTime":1628166823430,
      "status":"FILLED"
    }
  ]
}

Place order response partially filled example

{ "orderResponses":[
    { "coId":"Ord2010",
      "type":"Limit",
      "timeInForce":"GTC",
      "side":"Buy",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":2.0E7,
      "org":"MDFFI1",
      "price":1.18,
      "averagePrice":0.78353,
      "cumQty":1.7509931E7,
      "execId":"FXI4111742910",
      "lastPrice":0.78353,
      "lastQty":7509931.0,
      "orderId":"91530726273",
      "valueDate":"20210722",
      "tradeDate":"20210720",
      "settlCurrAmt":5884256.24,
      "executionType":"TRADE",
      "leavesQty":2490069.0,
      "counterParty":"cptyB",
      "userFullName":"user1@MAIN.MDFFI1",
      "transactTime":"1628339623535",
      "status":"PARTIALLY_FILLED"
    }
  ]
}

Response body

{ "orderResponses":["order object"] }

When placing orders, you receive orderResponses messages with different status values for a successful order.

See the order object for the full list of parameter details.

Attribute	Description
`coId`	string: Client order ID assigned by the API user.
`type`	string: `Market`, `Limit`, `Stop`, `StopLimit`, `Pegged`, `Algo`
`timeInForce`	string: `GTC`, `IOC`, `FOK`, `GTT`, `DAY`
`side`	string: `Buy` or `Sell` from the order placer's perspective and always for the base currency.
`currency`	string: Dealt currency.
`symbol`	string: Base and term currency separated by a slash "/" (for example `EUR/USD`).
`size`	double: Order amount.
`status`	string: `New`, `Partially Filled`, `Filled`, `Cancelled`, `Pending Cancel`, `Stopped`, `Rejected`, `Pending New`, `Expired`, `Received`
`executionType`	string: `CANCELED`, `NEW`, `PARTIAL_FILL`, `PENDING_NEW`, `TRADE`
`rateId`	string: Unique identifier for rate. Required for Previously Quoted Orders.
`org`	string: Your organization ID in Integral's system.
`price`	double: Order's limit price.
`expiryTime`	long: Expiry time when `timeInForce`=GTT. In seconds. Max value is one day (86399 seconds).
`maxShow`	double: Amount of the order visible to other market participants: 0 (zero) or undefined: Hidden: Order is not visible to other customers. Equal to `size`: Display: Full order amount visible to other customers. Less than `size`: Iceberg: Only the value of `maxShow` visible.
`averagePrice`	double: Average price of all fills so far.
`cumQty`	double: Total cumulative amount filled so far.
`execId`	string: Transaction ID assigned by Integral for each fill.
`lastPrice`	double: Price of the most recent fill.
`lastQty`	double: Size of the most recent fill.
`orderId`	string: Order ID assigned by Integral.
`valueDate`	string: Value date.
`tradeDate`	string: Trade date of fill.
`settlCurrAmt`	double: Amount of the settled currency.
`leavesQty`	double: Unfilled amount as of the most recent fill.
`counterParty`	string: Counterparty organization ID.

Cancel order

Cancel a single active order.

Order cancel request example

{ "orders":[
    { "action":"cancel",
      "coId":"108",
      "requestId":"req6",
      "side":"Sell",
      "symbol":"EUR/USD",
      "size":1000000
    }
  ]
}

Request body

{ "orders":["order object"] }

You must set action=cancel on the order object.

Action
Required Attributes |-|-|

Cancel order
action=cancel, coId, requestId, side, symbol, size

Cancel response pending example

{ "orderResponses":[
    { "type":"Limit",
      "timeInForce":"GTC",
      "side":"Buy",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":1.0E7,
      "org":"SanityOrg",
      "price":0.3,
      "averagePrice":0.0,
      "cumQty":0.0,
      "execId":"0",
      "orderId":"NONE",
      "executionType":"PENDING_CANCEL",
      "leavesQty":1.0E7,
      "requestId":"req6",
      "action":"place",
      "userFullName":"user1@MAIN.MDFFI1",
      "status":"PENDING_CANCEL"
    }
  ]
}

Cancel response verified example

{ "orderResponses":[
    { "type":"Limit",
      "timeInForce":"GTC",
      "side":"Buy",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":1.0E7,
      "org":"SanityOrg",
      "price":0.3,
      "averagePrice":0.0,
      "cumQty":0.0,
      "execId":"0",
      "orderId":"NONE",
      "executionType":"PENDING_CANCEL",
      "leavesQty":1.0E7,
      "requestId":"req6",
      "userFullName":"user1@MAIN.MDFFI1",
      "action":"place",
      "status":"CANCELED"
    }
  ]
}

Response body

Your cancel request is acknowledged with a HTTP 202 Accepted message with no HTTP body.

Subsequent status changes are sent orderResponses messages.

{ "orderResponses":["order object"] }

You receive multiple orderResponses messages in response to a cancel request.

Status
Description |-|-|

status=Pending Cancel
Order cancel is being attempted. The orderResponses message confirms your order attributes with a clientOrderTime timestamp.

status=Canceled
Order has been cancelled.

Cancel all orders

Cancel all active orders.

Cancel all request example

{ "orders":[
    { "action":"cancelAll",
      "requestId":"cancel_all_51"
    }
  ]
}

Request body

{ "orders":["order object"] }

You must set action=cancelAll on the order object.

Action
Required Attributes |-|-|

Cancel all active orders
action=cancelAll, requestId

Cancel all response received example

{ "orderResponses":[
    { "org":"SanityOrg",
      "clientOrderTime":"Aug 4, 2021 11:03:38 AM",
      "requestId":"cancel_all_51",
      "action":"cancelAll",
      "status":"Received"
    }
  ]
}

Cancel all response canceled order example

{ "orderResponses":[
    { "type":"Stop",
      "timeInForce":"GTC",
      "side":"Sell",
      "currency":"EUR",
      "symbol":"EUR/USD",
      "size":1000000.0,
      "org":"order",
      "account":"SanityOrgLE",
      "price":1.18644,
      "stopPrice":1.19353,
      "maxShow":1000000.0,
      "averagePrice":0.0,
      "cumQty":0.0,
      "execId":"FXI9189599068",
      "lastPrice":0.0,
      "orderId":"4792995049",
      "executionType":"Canceled",
      "leavesQty":1000000.0,
      "requestId":"Stop21",
      "action":"place",
      "status":"CANCELED"
    }
  ]
}

Cancel all response summary example

{ "orderCancelReport":
  { "totalAffectedOrders":6,
    "noAffectedOrders":6,
    "requestId":"cancel_all_51"
  }
}

Response body

{ "orderResponses":["order object"] }

You receive multiple orderResponses messages in response to a request to cancel all active orders:

Status
Description |-|-|

status=Received
Request to cancel all received.

status=Canceled
Order canceled. Received for each canceled order.

N/A
Summary of mass cancel.

Orders

The order object

Place order

Cancel order

Cancel all orders

Was this helpful?