Listing markets and instruments

How to get a list of markets and instruments

Most implementers need to at least occasionally query for a list of markets (known as assets in Hook's API), and the active instruments within that market.

1. Querying the assets

Use the getAssets GraphQL query to fetch assets.

query {
  assets {
    id
    baseCurrency
    supportedInstrumentTypes
    name
    symbol
    preferredSubaccount
    marketHash
    mmBips
    imBips
  }
}

$ curl 'https://goerli-api.hookdev.xyz/query' -H 'Accept-Encoding: gzip, deflate, br' -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Connection: keep-alive' --data-binary '{"query":"query {\n assets {\n id\n baseCurrency\n supportedInstrumentTypes\n name\n symbol\n preferredSubaccount\n marketHash\n mmBips\n imBips\n }\n}","variables":{}}' --compressed
> {
  "data": {
    "assets": [
      {
        "id": "1",
        "baseCurrency": "ETH",
        "supportedInstrumentTypes": [
          "OPTION",
          "PERPETUAL"
        ],
        "name": "Milady Maker",
        "symbol": "MILADY",
        "preferredSubaccount": 1,
        "marketHash": "0x1b6ab9d6677f2a32d1921d06ab1e6560c2a4ca943309324b1f77c557671eb79a",
        "mmBips": 1500,
        "imBips": 2000
      }
      ...
    ]
  }
}

The response will include information like the symboland supportedInstrumentTypes which are needed to find the instruments.

2. Subscribe to BBO endpoint to get instruments and prices

Use the BBO GraphQL subscription (replacing Milady and Perpetual with your desired types)

subscription {
  bbo(symbol: "MILADY", instrumentType: PERPETUAL) {
    eventType
    timestamp
    instruments {
      id
      name
      instrumentType
      markPrice
      bid {
        price
        size
      }
      ask {
        price
        size
      }
      optionStrike
      optionExpiration
      optionType
    }
  }
}

> {
  "eventType": "SNAPSHOT",
  "timestamp": "2024-01-17T19:56:29.531151Z",
  "instruments": [
    {
      "id": "0x194add7922e3fd9e6c17ca58efc31f97e6b891d13ea1919c751926daf98dd8a6",
      "ask": {
        "size": "1000000000000000000",
        "price": "5000000000000000000"
      },
      "bid": {
        "size": "1000000000000000000",
        "price": "2200000000000000000"
      },
      "name": "MILADY",
      "markPrice": "2608873557754551336",
      "openInterest": "0",
      "instrumentType": "PERPETUAL"
    }
  ]
}  

The initial snapshot includes the instrumentHash (which is the unique ID in the payload) as well as the best bid and offer. Subsequent updates will be sent when the mark price or bid/offer changes. In the case of options, new options will be added or removed as prices change and options expire. This subscription is automatically updated with these additional instruments.

3. Subscribing to the full-depth orderbook

Use the orderbook GraphQL subscription to watch the orderbook for a given instrument. The instrument hash is the ID from the bbo subscription above.

subscription {
  orderbook(instrumentHash: "0x194add7922e3fd9e6c17ca58efc31f97e6b891d13ea1919c751926daf98dd8a6") {
    eventType
    timestamp
    bidLevels {
      direction
      size
      price
    }
    askLevels {
      direction
      size
      price
    }
  }
}

{
  "askLevels": [
    {
      "size": "1000000000000000000",
      "price": "5000000000000000000",
      "direction": "ASK"
    }
  ],
  "bidLevels": [
    {
      "size": "1000000000000000000",
      "price": "2200000000000000000",
      "direction": "BID"
    },
    {
      "size": "1000000000000000000",
      "price": "1000000000000000000",
      "direction": "BID"
    }
  ],
  "eventType": "SNAPSHOT",
  "timestamp": "2024-01-17T19:56:29.529592521Z"
}

The askLevels includes the current firm offers to sell the instrument. The size and price are both represented in 10^18 decimals. The price reflectes the price in the market's BaseCurrency, which was retrieved above in the asset query.