Subscribe Message

SubscribeRequest

Subscribe to a price stream of bids and asks, in the requested pair, with respect to the requested settlement quantity, which may be in base or terms as specified in currency.

Request

Field	Req'd	Type	Description
messageType	Y	String	`subscribe`
instrument	Y	String	currency-pair
tag	N	String	For future use
quantity	Y	String	Quantity (in 'Currency')
currency	Y	String	Currency the price stream is quoted in. Should be either the base or quote currency
accountGrpUuid	N	String	Account group ref to use (SeeAccount Groups Message. If dropped will use default account.
tenor	Y	String	The value date of the price stream. FX prices will stream based on available cut-off dates for settlement with either a 'Today' price or a 'Tomorrow' price depending on time of day. The price response message will contain a 'settleDate' field which will indicate for which value date the price is quoted for. ZM also provides an option to request a price for a specific value date. Please contact your Relationship Manager for details on this. - T: Will retrieve price for closest available value date to 'today'. - T1: Will retrieve price for closest available value date to 'tomorrow'.

Request Example:

{
    "messageType": "subscribe",
    "instrument": "USDC.AED",
    "tag": "For future use",
    "quantity": 100000,
    "currency": "AED",
    "accountGrpUuid": "a6898bdd-856b-4259-b6e2-6ef66f2282e1",
    "tenor": "T"
}

Response

Indicates if the subscription is successful and if not, message field will indicate reason.

Field	Req'd	Type	Description
chanId	N	String	For Future use - empty for now
timestamp	Y	Long	Unix time in milliseconds
messageType	Y	String	`subscribe`
success	Y	bool	Indicates if `subscribeRequest` is successful `true`
message	Y	String	Confirmation is successful `subscribed`
subscriptionId	Y	String	Stream subscription ID
tag	N	String	For future use
instrument	Y	String	Currency-pair
quantity	Y	String	Quantity in terms of currency specified in subscription.
code	N	String	Error code
tenor	N	String	The tenor that was requested in the subscription
settleDate	N	String	For future use - empty for now

Response Example:

{
    "chanId": "",
    "timestamp": 1718110925811,
    "messageType": "subscribe",
    "success": true,
    "message": "Subscribed",
    "subscriptionId": "13f07bc9-055f-4054-bb78-73fe9f325ee6",
    "tag": "test-tag",
    "instrument": "USDC.AED",
    "quantity": "10000.000000",
    "code": "",
    "tenor": "T",
    "settleDate": ""
}

Unsubscribe

Unsubscribe from a previously requested price stream by sending the subscriptionId of the desired quote/price stream to terminate.

Request

Field	Req'd	Type	Description
messageType	Y	String	`unsubscribe`
subscriptionId	Y	String	Subscription ID of the `priceStream` to be unsubscribed

Request Example:

{
    "messageType": "unsubscribe",
    "subscriptionId": "13f07bc9-055f-4054-bb78-73fe9f325ee6"
}

Response

Indicates if the unsubscription is successful and if not, message field will indicate reason.

Field	Req'd	Type	Description
timestamp	Y	Long	Unix time in milliseconds
messageType	Y	String	`unsubscribe`
success	Y	bool	Indicates if unsubscribe is successful `true` or `false`
subscriptionId	Y	String	The Subscription ID specified in the request
message	Y	String	Conformation description
instrument	Y	String	Currency-pair
quantity	Y	Double	Requested Quantity
tenor	Y	String	Tenor that was subscribed for

Response Example:

{
    "timestamp": 1718111157195,
    "messageType": "unsubscribe",
    "success": true,
    "subscriptionId": "2ffc8d0c-21f5-4364-b2a6-4007218e57ee",
    "message": "Cancelled subscription 2ffc8d0c-21f5-4364-b2a6-4007218e57ee, client session 8c17bf72-b7f4-4a1c-86f1-5fb28d21e433, userUuid 7687282f-1073-441b-9ff4-694e6b49effe for USDC for 100000 AED",
    "instrument": "USDC.AED",
    "quantity": "100000.000000",
    "tenor": "T"
}

Price Stream

Response

The response contains a two way price (bid and offer) with respective quantities available for trading (partial fills are not available). The full order book is not sent at every tick rather, an updated quote for the subscribed quantity is sent. New prices will automatically replace the previous prices.

In the event the connection is lost users can download their transactions for reconciliation.

Heartbeats are not supported.

Field	Req'd	Type	Description
chanId	N	String	Unique client identifier - can be ignored
timestamp	Y	Long	Unix time in milliseconds
messageType	Y	String	`priceStream`
instrument	Y	String	Currency-pair
quoteId	Y	String	Unique Quote ID
tag	N	String	For future use
offer	Y		Offer
↳ price	Y	String	Quote Offer Price
↳ quantity	Y	String	Quote Offer Quantity. Always specified in base currency (for example for USDC.AED if quantity was specified in AED on subscription, the quantity here will be converted to the USDC equivalent)
bid	Y		Bid
↳ price	Y	String	Quote Bid Price
↳ quantity	Y	String	Quote bid Quantity. Always specified in base currency (for example for USDC.AED if quantity was specified in AED on subscription, the quantity here will be converted to the USDC equivalent)
tenor	Y	String	The value date of the price stream. FX prices will stream based on available cut-off dates for settlement with either a 'Today' price or a 'Tomorrow' price depending on time of day. The price response message will contain a 'settleDate' field which will indicate for which value date the price is quoted for. ZM also provides an option to request a price for a specific value date. Please contact your Relationship Manager for details on this. - T: Will retrieve price for closest available value date to 'today'. - T1: Will retrieve price for closest available value date to 'tomorrow'.
settleDate	N	String	The value date of the quote in YYYMMDD format. This is the date when settlement/delivery is expected of the asset.

{
    "chanId": "",
    "timestamp": 1729156597244,
    "messageType": "pricestream",
    "instrument": "USDC.AED",
    "quoteId": "cmEK+SwelROidy4Sn63WoWU2UJSAFOPy9Xi5UDpnCJPG5oH8ABAFv6fB/HFqNK04uuTveTEPVwYudxg+CwxKLSIzLQx/sXh9Jy8PNRQMHzNaW0RCKVFFRAQ6HDxesCXLN3J1HpFtoOJIu7SGQmM3MMMNrOVfEm1fFtDUIFBlNzacHqLjag1iDTHvjChscyYLQy9EEwQEdDMbFjsjPQMRKj4uRCt0DBkAACoeOnVVEj4Qc0U9FDVXOHUADxMUMRQBBwExDiomABlsIyk0Ei17VSgWBAoEEEY9D3sAEBAiHyp1AQoQEBgYAA9kHX0nFRETDxgRKBAHUz0QEFwTHxMeAhBzWjk=",
    "tag": "a5cf32f7-ae66-4edc-8538-f015020d1952",
    "offer": {
        "price": "3.673050",
        "quantity": "2722.533045"
    },
    "bid": {
        "price": "3.672950",
        "quantity": "2722.607169"
    },
    "tenor": "T",
    "settleDate": "20241021"
}

Stop Stream Response

When subscribing to the 'TOD' Tenor, if the pair has reached cut-off time for the day, the price stream will send a 'streamStop' message type to indicate the price is no longer available.

Only relevant for 'TOD' tenor and will not impact the 'T' and 'T1' tenors.

Field	Req'd	Type	Description
chanId	N	String	Unique client identifier - can be ignored
timestamp	Y	Long	Unix time in milliseconds
messageType	Y	String	`priceStream`
instrument	Y	String	Currency-pair
tag	N	String	For future use
tenor	Y	String	The value date of the price stream. FX prices will stream based on available cut-off dates for settlement with either a 'Today' price or a 'Tomorrow' price depending on time of day. The price response message will contain a 'settleDate' field which will indicate for which value date the price is quoted for. ZM also provides an option to request a price for a specific value date. Please contact your Relationship Manager for details on this. - T: Will retrieve price for closest available value date to 'today'. - T1: Will retrieve price for closest available value date to 'tomorrow'.

{  
  "instrument": "USDC.GBP",  
  "tenor": "TOD",  
  "chanId": "bd00d714-f1bd-49c2-970d-91791b4243ee",  
  "tag": "c8c423ff-6c6c-4cc0-a63d-a2a1251d0bbe",  
  "timestamp": 1747916826063,  
  "messageType": "streamStop"  
}