FIX API Specification – Orders

Version History

DateDescription
12 May 2021RequestForPositions:

  • per exchange filter moved into NoParties group

  • Account(1) tag now holds Organization ID


PositionReport:

  • added ShortQty



14 May 2021NewOrderSingle:

  • added ExecInst: Post-Only(6)

11 Jun 2021Added two new SecurityTypes:
ul>
  • PERPSWAP - represents Perpetual Swap contracts

  • FUT - represents Futures contracts


  • Updated specification for NewOrderSingle, ExecutionReport, PositionReport
    12 Jun 2021Added option to provide low-res timestamps within SendingTime and TransactTime tags for compatibility with Appia 7.xx
    19 Oct 2021Added new CxlRejReason = UNABLE TO PROCESS(4) to handle the situation when the order is still in a working state but can't be canceled(e.g. due to running settlement process)

    Organizational structure

      
    OrganizationAn organization is an entity, that represents the entire client's company inside the XTRD.
    AccountAn account is an entity that holds links to exchanges. Organizations can have multiple accounts.
    LoginThis entity is used to perform trading operations.

    Order states diagram

    Once the server received client’s order, it will respond with ExecutionReport message with two possible statuses(OrdStatus field):

    • PENDING NEW – order has been accepted for execution 
    • REJECTED – order did not pass initial validation 

    PENDING NEW can be followed with several possible state changes:

    • NEW – order has been accepted by specified exchange
      • after this point, itis possible to receive ExecutionReports in PARTIALLY FILLED/FILLED statuses or CANCELED(in case the order being canceled by corresponding OrderCancelRequest message or by TimeInForce modifier)
    • CANCELED – order has been rejected by the exchange 

    Dictionaries

    Security Type

    TypeValueDescription
    Foreign Exchange ContractFORAll fiat to fiat pairs
    Digital Assets Spot ContractCRYPROSPOTAll crypto to crypto or crypto to fiat spot contracts
    Perpetual Swap Contract PERPSWAP Perpetual swap contracts such as BTC-PERPETUAL
    Futures ContractsFUTFutures contracts

    Order Types

    Order TypeComments
    Market(1) When sending market orders, Price or StopPx is not required to be set
    Limit(2) When sending limit orders, Price(44) field is required to be set

    Order Sides

    Supported 3 sides:

    – Buy(1)
    – Sell(2)

    Time in Force

    Type Comments
    Day(0)If order becomes pending, it will be canceled at the end of the trading session
    Good Till Cancel(1)
    Immediate Or Cancel(3) Limit order will be executed at an exact price or better immediately, else will be canceled
    Fill Or Kill(4) Order will be filled for the quantity specified in OrderQt, else will be canceled

    Messages

    Logon

    TagField NameRequiredCommentsExample
    98EncrypMethodYAlways set to None(0)98=0
    108HeartBtIntYHeartbeat interval, always 30s108=30
    553UsernameY553=1001
    554 PasswordY554=Rr68twd6mw

    Logout

    Tag Field NameRequiredCommentsExample
    58TextNOptional text 58=regular disconnection

    NewOrderSingle

    TagField NameRequiredCommentsExample
    1 Account YLogin ID, associated with given session1=1001
    11 ClOrdID YClient assigned order ID 11=1234
    12=ORD_1234
    38OrderQtyYInitial Order size39=0.125
    40 OrdTypeYType of order
    Supported values:

    • Market(1)

    • Limit(2)

    40=1
    44Price C Conditional field, indicating an expected fill price.
    Required for:
    • Limit
    44=0.033528
    99StopPxCConditional field, required for Stop order type99=0.033612
    54 Side YOrder side used
    Supported Values:

    • Buy(1)

    • Sell(2)

    54=1
    55SymbolYSymbol name55=ETH/BTC
    59 TimeInForce YControl orders lifetime behavior.
    Supported Values:

    • Day(0)

    • Good till Cancel(1)

    • Immediate or Cancel(3)

    • Fill Or Kill(4)

    59=0
    60 TransactionTimeYTimestamp in UTC timezone when the order was created with included milliseconds
    ⚠️ it is possible to send a timestamp with the down to the one-second resolution but this approach is not recommended.
    60=20180912-12:05:
    15.105
    100ExDestinationYECN or Venue name where the order will be sent/executed100=OKEX
    167SecurityTypeYType of security to trade.
    Supported values:

    • CRYPTOSPOT - Digital Assets spot market contract

    • PERPSWAP - Digital Asset perpetual swap contract

    • FOR - Foreign exchange contract

    • FUT - Futures contract

    167=FOR
    18ExecInst NInstructions for orders handling during execution.
    Supported values:

    • Participate, don't initiate(6) - POST-ONLY

    • Do Not Increase(E)

    • No Cross(A)

    18=6

    OrderCancelRequest

    OrderCancelRequest is used to cancel the order in its entirety. Only orders in NEW or PARTIALLY_FILLED statuses can be canceled. If you need to cancel only a part of the non-filled amount (leaves quantity), please refer to OrderCancelReplaceRequest.

    TagFiled NameRequiredCommentsExample
    1 AccountYTrader, which hold particular order to cancel1=1001
    11 ClOrdIDYClient order ID for cancel operation 11=1234
    37OrderIDYOrderID which should be canceled37=312351044
    41OrigClOrdIDYClient order ID of order which should be canceled41=1233
    54SideYOrder side of order, identified by OrigClOrdID/OrderID51=1
    55SymbolYSymbol, association with working order55=ETH/USD
    60 TransactionTimeYTimestamp in UTC timezone when an order was created with included milliseconds
    ⚠️ it is possible to send a timestamp with the down to the one-second resolution but this approach is not recommended.
    60=20180912-12:05:
    15.105

    OrderCancelReject

    This message will be sent by the server in response to OrderCancelRequest if the operation failed for some reason.

    TagField NameRequiredCommentsExample
    1Account Y1=1001
    11ClOrdID C ID of client order which was used to perform cancel operation11=CCL_001
    41OrigClOrdIDC ID of canceling client order41=TRD_00231
    37OrderIDCID of working order on XTRD side. Usually transmitted as OrderID within ExecutionReport message37=1123423
    102CxlRejReasonYSupported Values:

    • 0 - Too late to cancel

    • 1 - Unknown order(send when at least one of order related fields are missed, contains
      incorrect information or order can't be found)

    • 2 - Broker/Exchange option

    • 4 - Unable to Process

    • 99 - Other

    102=0
    434 CxlRejResp
    onseTo
    YSupported Values:

    • 1 - OrderCancelRequest

    434=1
    58 Text C Textual comments about rejection reason 58=Can't cancel
    filled order
    60 Transaction
    Time
    YTimestamp in UTC timezone when Order can rejected 60=20180912-12:
    15:15.105

    ExecutionReport

    TagField NameRequired Comments Example
    1AccountYLogin ID, associated with a given session 1=1001
    11 ClOrdID YClient-assigned order ID 11=1234
    12=ORD_1234
    37OrderIDYOrder ID on XTRD side37=312351043
    198SecondaryOrderIDCOrder ID, assigned by target exchange 198=ea4063b0-4b66-
    11ea-b77f2e728ce88125
    17 ExecID YOrder execution ID
    This field will be set to zero("0") when processing MassOrderStatusRequest message
    (ExecType=ORDER STATUS(I))
    17=4000123541
    584 MassStatusReqIdN Request ID, associated with MassOrdertStatusRequest message584=ord_req_1223
    911TotNumReports
    NA conditional field that will appear in the response to Order Mass Status Request(AF)
    message. Contains a total number of all orders that meet search criteria
    911=14
    912LastRptRequestedNA conditional field that appears only for reports with ExecType=ORDER STATUS.
    Indicates that this is the very last message in the batch
    913=Y
    40 OrdTypeYOrder Type (Market, Limit) 40=1
    44PriceYConditional field, indicating expected fill price for Limit orders44=0.033953
    54SideYOrder side used
    Supported Values:

    • Buy(1)

    • Sell(2)

    54=1
    55Symbol YSymbol name 55=ETH/BTC
    39 OrdStatusY Reports current order status
    Supported values:

    • PENDING NEW(A)

    • NEW(0)

    • PARTIALLY FILLED(1)

    • FILLED(2)

    • CANCELED(4)

    • REJECTED(8)

    39=2
    150ExecTypeYReports current execution status:
    Supported values:

    • NEW(0)

    • TRADE(F)

    • CANCELED(4)

    • REJECTED(8)

    • ORDER STATUS(I)

    150=F
    6AvgPxYAverage price of all executed parts(in case of partial fills)6=0.033959
    31LastPx CPrice of last executed part. If order fully filled at once, LastPx will be same as AvgPx31=0.033951
    32 LastQtyCLast executed size.32=0.100
    14CumQtyYTotal executed quantity for a given order (sum of all fills)14=0.200
    151LeavesQtyYIndicates quantity of order still not-executed yet live.151=0.300
    58TextCMay contain optional text information related to order status. E.g. textual explanation
    of rejection
    58=Account not found.
    Tag 1
    59 TimeInForceYControl order lifetime behavior.
    Supported Values:

    • Day(0)

    • Good till Cancel(1)

    • Immediate or Cancel(3)

    • Fill Or Kill(4)
    59=0
    60TransactionTime
    YTime of the most recent Order's update,timestamp in UTC timezone.60=20180912-12:05:
    15.105
    100ExDestinationYECN or Venue name where the order was sent/executed100=OKEX
    103OrdRejReasonCIf a case of a rejection, this field will help identify the source of error103=11
    167 SecurityTypeYType of security.
    Supported values:

    • FOR - Foreign Exchange Contract

    • CRYPTOSPOT - Digital Assets spot market contract

    • PERPSWAP - Digital Asset perpetual swap contract

    • FUT - Futures contract

    167=CRYPTOSPOT
    12Commission C
    Commission charged for the last execution or for the entire chain of executions(as a response for OrderMassStatusRequest).
    Only orders in status PARTIALLY_FILLED(1) or FILLED(2) have this tag set.
    12=0.001
    13CommisionTypeCSupported values:

    • Absolute(3)


    Only orders in status PARTIALLY_FILLED(1) or FILLED(2) have this tag set.
    13=3
    479CommissionCurrencyCCurrency used to charge given commission
    Only orders in status PARTIALLY_FILLED(1) or FILLED(2) have this tag set.
    479=USD
    18ExecInst N Instructions for orders handling during execution.
    Supported values:

    • Participate, don't initiate(6) - POST-ONLY

    • Do Not Increase(E)

    • No Cross(A)

    18=6

    OrderMassStatusRequest

    This message is used when counterparty needs to obtain a list of list(working) orders that match certain criteria. 

    A response will be provided through a series of ExecutionReports that contains ExecType=Status and echoed back MassStatusReqId (584) field. 

    TagField NameRequiredComments Example
    584MassStatusReqIdYUnique ID, associated with a given request584=request_123
    585MassStatusReqTypeYSpecify the scope of a mass status request.
    Supported Values:

    • 7 - status for all orders that belong to Organization

    • 8 - status for orders that belongs to a certain PartyID. In this case, additional information should be provided using NoPartyIds group. It is possible to provide more, than one PartyID at once.

    585=1
    453NoPartyIDsCMandatory, when MassStatusReqType=8 and holds a list of actual trading Logins.
    Additionally, can be used to narrow request scope by specifying exchanges. If no exchange-related information is provided, the server will respond with a list that includes open orders from all exchanges.
    453=4
    448PartyIDExchange name
    Login ID
    448=HUOBI
    452PartyRoleSupported values:

    • 6 - Introducing Firm(Organization ID in XTRD terminology)

    • 11 - Order Origination Trader(Login in XTRD terminology)

    • 22 - Exchange

    452=22

    Request for Positions

    This message is used to request a list of positions associated with a given exchange and trading login. This information is available in the form of a snapshot or incremental updates send by the server once the position size changed. 

    Examples

    Your Organization ID is 1001 and it manages four trading accounts – 1234, 2000, 2101, 4442.

    You want to get a snapshot of all positions your organization has under the management. In this case, NoPartyIDs group will look as following:

    Entry #TagNameValue
    0448PartyID1001
    0452PartyRole 6

    This request(if executed successfully) should returns positions for logins 1234, 2000, 2101, and 4442. 

    If you are looking for positions that belong to certain logins(e.g. 1234 and 4442) then NoPartyIDs group will be as following:

    Entry #TagNameValue
    0448PartyID 1234
    0452PartyRole 11
    1 448PartyID4442
    1452PartyRole11


    Type: AN
    TagField NameRequiredComments Example
    710 PosReqId YUnique ID, associated with a given request710=req_1
    724PosReqType YUsed to narrow the scope of information transmitted.
    Supported values:

    • Position(0)

    724=0
    263SubscriptionRequestTypeYUsed to subscribe or unsubscribe from reports.
    Supported values:

    • Snapshot(0)

    • Snapshot and Updates(1)

    • Disable previous Snapshot and Updates request(2)

    263=1
    1Account YOrganization ID 1=1001
    581 AccountTypeYType of account associated with a position request
    Supported values:

    • 1 - Account

    581=1
    715ClearingBusinessDayYThe Clearing Business Date referred to by this request 715=20191107
    453NoPartyIDsY453=1
    448PartyIDYCounterparty name e.g. name of the target exchange
    Login ID
    HUOBI
    452PartyRoleYSupported values:

    • 6 - Introducing Firm

    • 11 - Order Origination Trader

    • 22 - Exchange

    452=22
    60TransactTimeYTime, when this request was initiated60=20191107-12:05:15.105

    Request for Positions Ack

    This message will be sent as a confirmation to Request for Positions. It contains basic information such is request status and a number of positions returned with the following snapshot. 

    Type: AO

    TagField NameRequiredCommentsExample
    721PosMaintRptIdYUnique identifier for this position report721=123456021
    710PosReqIdN Request ID, copied from the parent message 710=req_1
    727TotalNumPosReports
    NNumber of positions returned727=246
    728PosReqResult YIndicates the request status.
    Supported values:

    • 0 - Valid Request

    • 1 - Invalid or Unsupported request

    • 2 - No positions found

    • 3 - Not authorized to request positions

    728=0
    729 PosReqStatusYStatus of request for positions.
    Supported values:

    • 0 - Completed

    • 2 - Rejected

    729=0
    453NoPartyIDsY453=2
    448PartyID448=XTRD
    452PartyRole Supported values:

    • 11 - Order Origination Trader(Login ID)

    • 22 - Exchange

    452=11
    1AccountYOrganization ID1=1001
    581AccountTypeYType of account associated with a position
    request
    Supported values:

    • 1 - Account

    581=1
    207 SecurityExchangeNName of the trading venue to get a list of the
    positions
    207=OKEX
    58TextN Human-readable error message58=Not authorized to request positions for given
    Account

    Position Report

    Type: AP

    Tag Field NameRequiredCommentsExample
    721PosMaintRptID YUnique identifier for this position report721=1002312
    710 PosReqIDN This filed will be set when returning positions snapshot and will be omitted for any
    sequential updates
    710=req_12
    728PosReqResultYAlways 0(Valid Request)728=0
    715ClearingBusinessDateYAlways today715=20191107
    453NoPartyIDsYFor a regular report, NoParties group contains 2 entries:

    • Position owner(Order Origination Trader)

    • Exchange

    453=2
    448PartyID448=12
    452PartyRole N Supported values:

    • 11 - Order Origination Trader

    • 22 - Exchange

    1=1001
    1AccountYOrganization ID1=2342
    581AccountTypeYType of account associated with a position request
    Supported values:

    • 1 - Account

    581=1
    55 Symbol YHuman readable asset name55=ETH
    167SecurityType YSupported values:

    • CRYPTOSPOT

    • PERPSWAP

    • FUT

    • PERPSWAP

    702NoPositionsY702=1
    703PosType Supported Values:

    • ETR - Electronic Trade Qty

    703=ETR
    704LongQtyEither LongQty or ShortQty is available as part of this group.
    ShortQty is not available for SPOT markets.
    703=500.
    123000
    705ShortQty