FAQ - Zero Hash CLOB Rest API

General

Zero Hash has added new REST API endpoints to allow platforms to integrate to our Central Limit Order Book in our CERT and PROD environments. Existing platforms that are integrated to Zero Hash will not need a new API key to integrate to our CLOB.

Environments

Production

• https://api.zerohash.com

Certification

• https://api.cert.zerohash.com

Authentication

Authentication to this the Zero Hash Rest API is explained in the code recipe section below.

API Request

To reach our search orders endpoint, send a request to the endpoint POST /orders/v1/search_orders.

Parameters

Example Request

{
  "accounts": [
    "firms/I1HSG7/accounts/I1HSG7","firms/I1HSG7/accounts/00SCXM"
  ],
  "clord_id": "2853638224179366356019",
  "end_time": "2023-06-15T10:24:45.470Z",
  "order_id": "1666122693176070209",
  "page_size": 10,
  "start_time": "2023-06-15T10:24:45.470Z",
  "symbol": "BTC/USD",
  "order_state_filter": "ORDER_STATE_FILTER_OPEN"
}

Response Parameters

Example Response

{
  "order":
    [
      {
        "id":"1666122693176070209",
        "type":"ORDER_TYPE_LIMIT",
        "side":"SIDE_BUY",
        "order_qty":"96556859",
        "symbol":"BTC/USD",
        "clord_id":"",
        "time_in_force":"TIME_IN_FORCE_GOOD_TILL_CANCEL",
        "account":"firms/ABC123/accounts/ABC123",
        "cum_qty":"0",
        "avg_px":"0",
        "leaves_qty":"96556859",
        "state":"ORDER_STATE_NEW",
        "participant":"firms/F-ABC123/users/ABC123",
        "price":"2576202",
        "insert_time":"2023-06-14T06:33:10.012984790Z",
        "stop_price":"0",
        "min_qty":"0",
        "create_time":"2023-06-14T06:33:10.006727979Z",
        "all_or_none":false,
        "cross_id":"",
        "host_cross_id":"",
        "submitting_participant":"",
        "client_account_id":"",
        "client_participant_id":"",
        "parent_order_id":"",
        "commissions_basis_points":"18",
        "participate_dont_initiate":false,
        "cash_order_qty":"0",
        "symbol_sub_type":"",
        "strict_limit":false,
        "risk_check_time":"2023-06-14T06:33:10.012288523Z",
        "collateral_memo":"Fully Collateralized",
        "priority_weight":"0",
        "good_till_time":null,
        "context":
      {
      "any_context":
        { 
          "@type":"type.googleapis.com/connamara.ep3.token.v1beta1.TokenContext",
          "user":"firms/F-ABC123/users/ABC123",
          "firm":"firms/F-ABC123",
          "audience":"api",
          "role":"USER_ROLE_TRADING",
          "impersonator":"firms/F-ABC123/users/ABC123",
          "issuer":"",
          "jti":"1666122643676537222",
          "issue_time":"2023-06-14T06:32:21Z",
          "expiration_time":"2023-06-14T06:47:21Z",
          "ott":false
        },
      "fix_context":null
      },
        "best_limit":false,
        "immediately_executable_limit":false,
        "block_trade_indicator":false,
        "last_trade_id":"",
        "trigger_method":"CONDITION_TRIGGER_METHOD_UNDEFINED",
        "price_to_quantity_filled":{},
        "commission_notional_total_collected":"0",
        "self_match_prevention_instruction":"SELF_MATCH_PREVENTION_INSTRUCTION_UNDEFINED",
        "order_capacity":"ORDER_CAPACITY_UNDEFINED"
      }
    ],
  "next_page_token":"2023-06-14T06:33:09.011Z_64895f252aff3a1f4c5af211"
}

Key Fields and Values

OrderState - state for filtering on payload

• ORDER_STATE_FILTER_OPEN
• ORDER_STATE_FILTER_CLOSED
• ORDER_STATE_FILTER_NEW
• ORDER_STATE_FILTER_PARTIALLY_FILLED
• ORDER_STATE_FILTER_FILLED
• ORDER_STATE_FILTER_CANCELED
• ORDER_STATE_FILTER_REPLACED
• ORDER_STATE_FILTER_REJECTED
• ORDER_STATE_FILTER_EXPIRED
• ORDER_STATE_FILTER_PENDING_RISK

OrderState - state value in the response

• ORDER_STATE_NEW
• ORDER_STATE_PARTIALLY_FILLED
• ORDER_STATE_FILLED
• ORDER_STATE_CANCELED
• ORDER_STATE_REPLACED
• ORDER_STATE_REJECTED
• ORDER_STATE_EXPIRED
• ORDER_STATE_PENDING_NEW
• ORDER_STATE_PENDING_REPLACE
• ORDER_STATE_PENDING_CANCEL
• ORDER_STATE_PENDING_RISK

Time In Force - time_in_force

• TIME_IN_FORCE_DAY
• TIME_IN_FORCE_GOOD_TILL_CANCEL
• TIME_IN_FORCE_IMMEDIATE_OR_CANCEL
• TIME_IN_FORCE_GOOD_TILL_TIME

Order Type - type

• ORDER_TYPE_MARKET_TO_LIMIT
• ORDER_TYPE_LIMIT
• ORDER_TYPE_STOP
• ORDER_TYPE_STOP_LIMIT

Example Request

if __name__ == '__main__':

  body = {
    "page_size": 2,
    "symbol": "BTC/USD"
  }

  response = send_signed_http_request('POST', '/orders/v1/search_orders', body)
 

Retrieving the Scale Factor

To find the details of the scale factor for each symbol, you can query POST /orders/v1/list_instruments.

if __name__ == '__main__':
	response = send_signed_http_request('POST', '/orders/v1/list_instruments', {})

Fields that are price related are scaled with the price_scale while fields which related to quantity are scaled with fractional_qty_scale.

Fields that are scaled using price_scale

• avg_px
• close_px
• cost
• first
• high
• high_px
• last
• last_px
• last_trade_px
• low
• low_px
• notional_traded
• open_px
• price
• px
• reference_px
• settlement_px

For these fields that are scaled with price_scale, the API response received is multiplied to the price_scale to get the real value.

e.g. An avg_px of 145000 has been returned as response for an ETH order query, meanwhile ETH has a price_scale of 0.01. To get the real value, multiply the avg_px of 145000 to the price_scale of 0.01 - this then results to 1,450 which approx. the ETH/USD value as of date.

Fields that are scaled using fractional_qty_scale

• bod_position
• cleared_volume
• commissions_basis_points
• cum_qty
• last_shares
• last_trade_qty
• leaves_qty
• net_position
• open_interest
• qty
• qty_bought
• qty_sold
• realized
• shares_traded
• volume

For these fields that are scaled with fractional_qty_scale, the API response received is divided to the fractional_qty_scale to get the real value.

e.g. A leaves_qty of 37647 has been returned as response for an XRP order query, meanwhile XRP has a fractional_qty_scale of 1000000. To get the real value, divide the leaves_qty of 37647 to the fractional_qty_scale of 1000000 - this then results to 0.037647 units of XRP.