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
coIdstring, max size 255: (required) Client order ID assigned by the API user.
typestring: (required) Market, Limit, Stop, StopLimit, Pegged, Algo
timeInForcestring: (required) GTC, IOC, FOK, GTT, DAY
sidestring: (required) Buy or Sell from the order placer's perspective and always for the dealt currency.
currencystring: (required) Dealt currency.
symbolstring: (required) Base and term currency separated by a slash "/" (for example EUR/USD).
sizedouble: (required) Order amount.
rateIdstring: Unique identifier for rate. Required for Previously Quoted Orders.
orgstring (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.
clientOrderTimestring: Time the order was submitted in the format yyyy-MM-dd HH:mm:ss,SSS Z.
accountstring: Your organization's account (legal entity).
pricedouble: Order's limit price.
stopPricedouble: Stop price for stop orders.
expiryTimelong, max value 86399: Expiry time when timeInForce=GTT. In seconds. Max value is one day (86399 seconds).
targetStrategystring: Mid, Fixing, Twap, LitSwitch, DarkSwitch
originalCoIdstring: The original client order ID of the order to be cancelled or replaced by this request.
stopPricedouble: Order's stop price (if any).
execFlagsList of strings: Execution strategy requested with order: BidTrigger: Stay on bid side, MidTrigger: Mid price, OfferTrigger: Stay on offer side
minQtydouble: Minimum fill size (if any) in dealt currency.
maxShowdouble: 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.
averagePricedouble: Average price of all fills so far.
cumQtydouble: Total cumulative amount filled so far.
orderIdstring: Order ID assigned by Integral.
valueDatestring: Value date in the format YYYY-MM-DD.
tradeDatestring: Trade date of fill in the format YYYY-MM-DD.
executionTypestring: CANCELED, NEW, PARTIAL_FILL, PENDING_NEW, TRADE
leavesQtydouble: Unfilled amount as of the most recent fill.
counterPartystring: Counterparty organization ID.
counterPartyAccountstring: Counterparty legal entity ID.
transactTimelong: UTC time of last event on the order in milliseconds.
actionstring: place, cancel, cancelAll
userFullNamestring: Fully qualified user name of order submitting user, including namespace and organization ID in the format userName@namespace.orgID.
statusstring: RECEIVED, NEW, PARTIALLY_FILLED, FILLED, PENDING_CANCEL, CANCELED, REPLACED, STOPPED, REJECTED, EXPIRED, FAILED
reasonstring: Orders with status=Failed or status=Failed, the reason for failure or rejection.
customerIdstring: Customer ID on whose behalf the order is placed.
executionStartTimestring: 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.
executionEndTimestring: 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.
pegPriceTypestring: Mid: Pegged to mid rate.
pegOffsetValuedouble: The amount in pips that is added to the price of the peg. Can be positive or negative.
actionOnExpirystring: 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
sliceSizedouble: TWAP order: The fixed size of each slice.
passiveTimeint: Time for which each slice rests in OCX RiskNet. Specified in milliseconds. Overrides passiveTimeFactor.
passiveTimeFactorPercentagedouble: Determines how long each slice rests in OCX RiskNet, calculated as a percent of the actual slice interval. Required if passiveTime is not set
sliceIntervalint: 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.
randomizeSliceSizePercentagedouble: The percentage range that the sliceSize is randomized.
randomizeSliceIntervalPercentagedouble: The percentage range that the sliceInterval is randomized.
tobRangedouble: 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: StopcoId, 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
coIdstring: Client order ID assigned by the API user.
typestring: Market, Limit, Stop, StopLimit, Pegged, Algo
timeInForcestring: GTC, IOC, FOK, GTT, DAY
sidestring: Buy or Sell from the order placer's perspective and always for the base currency.
currencystring: Dealt currency.
symbolstring: Base and term currency separated by a slash "/" (for example EUR/USD).
sizedouble: Order amount.
statusstring: New, Partially Filled, Filled, Cancelled, Pending Cancel, Stopped, Rejected, Pending New, Expired, Received
executionTypestring: CANCELED, NEW, PARTIAL_FILL, PENDING_NEW, TRADE
rateIdstring: Unique identifier for rate. Required for Previously Quoted Orders.
orgstring: Your organization ID in Integral's system.
pricedouble: Order's limit price.
expiryTimelong: Expiry time when timeInForce=GTT. In seconds. Max value is one day (86399 seconds).
maxShowdouble: 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.
averagePricedouble: Average price of all fills so far.
cumQtydouble: Total cumulative amount filled so far.
execIdstring: Transaction ID assigned by Integral for each fill.
lastPricedouble: Price of the most recent fill.
lastQtydouble: Size of the most recent fill.
orderIdstring: Order ID assigned by Integral.
valueDatestring: Value date.
tradeDatestring: Trade date of fill.
settlCurrAmtdouble: Amount of the settled currency.
leavesQtydouble: Unfilled amount as of the most recent fill.
counterPartystring: 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.