Subscribe request

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

FieldReq'dTypeDescription
messageTypeYStringsubscribe
instrumentYStringcurrency-pair
tagNStringFor future use
quantityYStringQuantity (in 'Currency')
currencyYStringCurrency the price stream is quoted in. Should be either the base or quote currency
accountGrpUuidNStringAccount group ref to use (SeeAccount Groups Message. If left blank will use default account.
tenorYStringThe 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": "",
    "tenor": "T"
}

Response

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

FieldReq'dTypeDescription
chanIdNStringFor Future use - empty for now
timestampYLongUnix time in milliseconds
messageTypeYStringsubscribe
successYboolIndicates if subscribeRequest is successful true
messageYStringConfirmation is successful subscribed
subscriptionIdYStringStream subscription ID
tagNStringFor future use
instrumentYStringCurrency-pair
quantityYStringQuantity of the currency to be delivered
codeNStringError code
tenorNStringThe tenor that was requested in the subscription
settleDateNStringFor 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": "100000.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

FieldReq'dTypeDescription
messageTypeYStringunsubscribe
subscriptionIdYStringSubscription 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.

FieldReq'dTypeDescription
timestampYLongUnix time in milliseconds
messageTypeYStringunsubscribe
successYboolIndicates if unsubscribe is successful true or false
subscriptionIdYStringThe Subscription ID specified in the request
messageYStringConformation description
instrumentYStringCurrency-pair
quantityYDoubleRequested Quantity
tenorYStringTenor 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.

FieldReq'dTypeDescription
chanIdNStringUnique client identifier - can be ignored
timestampYLongUnix time in milliseconds
messageTypeYStringpriceStream
instrumentYStringCurrency-pair
quoteIdYStringUnique Quote ID
tagNStringFor future use
offerYOffer
↳ priceYStringQuote Offer Price
↳ quantityYStringQuote Offer Quantity
bidYBid
↳ priceYStringQuote Bid Price
↳ quantityYStringQuote Bid Quantity
tenorYStringThe 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'.
settleDateNStringThe 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": "100000"
    },
    "bid": {
        "price": "3.672950",
        "quantity": "100000"
    },
    "tenor": "T",
    "settleDate": "20241021"
}