New Update Quote Endpoint (PATCH /liquidity/rfq)

Release Details

Release Date: June 12th, 2024

Release Type

Informational – Optional action from platforms

Summary

Zero Hash has created a new endpoint: PATCH /liquidity/rfq. Platforms can use this endpoint to update an existing, non-expired quote. There are 2 required fields:

• quote_id: the id associated with a valid, non-expired quote that was returned from either GET or POST /liquidity/rfq
• total: the notional value that you'd like to update the quote to reflect

And one optional object:

• fees: object containing fee data
  • name: a string naming the fee
  • amount: the amount of the fee, denominated in the quoted currency of the original quote

Platforms should use the same execution endpoints, POST /liquidity/execute, to execute on the quotes updated via PATCH /liquidity/rfq.

Validations

• If the platform omits the quote_id, we’ll return an error, "quote_id is a required field"
• If the platform sends a quote_id that is valid but expired, we’ll return an error, "quoted_id has expired"
• If the platform sends a fees object containing a name that is not an exact match to one from the original quote, we’ll return an error, “No fee with the submitted ‘name’ exists on this quote”
• If the platform sends a fee object containing an amount that is non-numerical, we’ll return an error, “amount must be a positive integer”

API Behavior

• Upon a successful PATCH /liquidity/rfq call, Zero Hash will function like the following:
  • The quote_id goes unchanged - we’ll keep constant with original POST /liquidity/rfq response
  • The expire_ts goes unchanged - we’ll keep constant with original POST /liquidity/rfq response
  • The trade_price goes unchanged - we’ll keep constant with original POST /liquidity/rfq response
  • [Rest of the fields go unchanged]
  • We’ll update quantity to be the new value
  • We’ll refresh the request_id
  • We’ll change the total value to the one provided on the PATCH call

Action Required

• PATCH /liquidity/rfq is immediately available for all platforms that are configured to use our liquidity endpoints.

Endpoints Impacted

• PATCH /liquidity/rfq

Example Request (zero fees initially)

• Platform (PLAT01) requests a quote on behalf of its customer (CUST01): POST /liquidity/rfq
• Let's assume PLAT01 is configured for 5 minute quote expiries

{
    "side": "buy",
    "participant_code": "CUST01",
    "underlying": "BTC",
    "quoted_currency": "USD",
    "total": "1",
    "spread": "300",
    "fees": [
        {
            "amount": "0",
            "name": "fee_1"
        }
    ]
}

• Zero Hash responds:

{
    "message": {
        "request_id": "7d6d2a79-c421-4e78-b250-5a43b5da479e",
        "participant_code": "PLAT01",
        "quoted_currency": "USD",
        "side": "buy",
        "quantity": "0.00000138",
        "price": "724637.6811594203",
        "quote_id": "38451f54-6289-45b2-b70c-369bdaefdea4",
        "expire_ts": 1717174886754, <-- 5 minute quote
        "account_group": "00SCXM",
        "account_label": "general",
        "obo_participant": {
            "participant_code": "CUST01",
            "account_group": "PLAT01",
            "account_label": "general"
        },
        "fees": [
        {
            "amount": "0.00",
            "name": "fee_1"
        }
                ]
        "underlying": "BTC",
        "asset_cost_notional": "100",
        "spread_notional": "3.00",
        "spread_bps": "300"
    }
}

• [some time before the quote expires, say 90 seconds later] The Platform updates the quote via PATCH /liquidity/rfq:

{
    "quote_id":"38451f54-6289-45b2-b70c-369bdaefdea4"
    "total": "100",
    "fees": [
        {
            "amount": "10.00",
            "name": "fee_1"
        }
    ]
}

• Zero Hash responds:

{
    "message": {
        "request_id": "7d6d2a79-c421-4e78-b250-5a43b5da479e",
        "participant_code": "PLAT01",
        "quoted_currency": "USD",
        "side": "buy",
        "quantity": "0.0001242", <-- updated quantity
        "price": "724637.6811594203", <-- same price
        "quote_id": "38451f54-6289-45b2-b70c-369bdaefdea4",
        "expire_ts": 1717174886754, <-- same expiration
        "account_group": "00SCXM",
        "account_label": "general",
        "obo_participant": {
            "participant_code": "CUST01",
            "account_group": "PLAT01",
            "account_label": "general"
        },
        "fees": [
        {
            "amount": "10.00",
            "name": "fee_1"
        }
                ]
        "underlying": "BTC",
        "asset_cost_notional": "100",
        "spread_notional": "3.00",
        "spread_bps": "300"
    }
}

• Platform executes the quote via POST /liquidity/execute:

{
   "quote_id": "38451f54-6289-45b2-b70c-369bdaefdea4"
}