Receiving trade events

Whenever Upshot completes a trade, Upshot will notify Market Maker of the result with a trade event. Upshot systems will retry sending a trade event message for every 15 seconds up to five times until an acknowledgment is received. Market maker should send an acknowledge message for every trade event received.

If you do not require this functionality, you should at least send acknowledge messages to stop Upshot from re-sending trade events. See Acknowledgement message

Trade event message

The trade event message will have the following format.

{
    "messageId": "29358e8b43a5d20023850ea392ed5b86a4989e0f",
    "message": {
        "data": {
            "rfqId": "d6c5f51c-ba1a-4182-9f14-340162e2cc8d",
            "baseChain": {
                "chainType": "evm",
                "chainId": 97
            },
            "quoteChain": {
                "chainType": "evm",
                "chainId": 97
            },
            "baseToken": "0xd855b74d4ec7543394e3542091e3f38d97e6ed1f",
            "quoteToken": "0xf0c49279bef38df8479b4f8c08fafa8f99b4794c",
            "trader": "0xf0c49279bef38df8479b4f8c08fafa8f99b4794c",
            "effectiveTrader": "0xf0c49279bef38df8479b4f8c08fafa8f99b4794c",
            "baseTokenAmount": "1000000000",
            "quoteTokenAmount": "100000000000000",
            "blockNumber": 20725574,
            "blockTimestamp": 1726036077,
            "tradeSide": "BUY", // "BUY", "SELL"
            "transactionHash": "0x490ee6c479b107cc3465b503b2021881086af0985030d8358eb3e16dff7a06e6",
            "pool": "0x5ce83ebde268cd84307e864f015c7c63753041ce",
            "tradeStatus": "CONFIRMED" // "CONFIRMED", "CANCELED"
        }
    },
    "messageType": "fill-order"
}

The system guarantees at least one delivery. This means that in some rare cases, a message could be delivered twice. Each event is identified by a unique messageId. So messageId can be used to avoid processing the same event twice.

IMPORTANT: In the case of a chain reorganisation, a message with tradeStatus CANCELED will be sent. This message also has to be acknowledged and processed accordingly. a canceled RFQ may stay on canceled state after a chain reorganization if nobody, after a chain reorganization, cannot take on that RFQ anymore. On the other hand, a canceled RFQ may also become success again after a chain reorganization but with different taker or different amount. In that case, Upshot will send a new message containing the same rfqId but with a different messageId and tradeStatus CONFIRMED to notify market makers of the state after reorganization.

Acknowledgement message

To let Upshot know that a message has been received, a matching messageAck with the same messageId has to be sent back following each trade event message received. Upshot will retry sending the same event message as long as these acknowledgement messages have not been received.

Market maker must send the acknowledgment message in the following format.

{
    "messageType": "messageAck",
    "message": {
        "messageId": "29358e8b43a5d20023850ea392ed5b86a4989e0f"
    }
}