Orderbook API

Overview

The Premia Orderbook API can be used to Publish and/or Get quotes from the orderbook and RFQ system for any deployed/deployable option pool. The Orderbook API comprises of both a REST API and a WEBSOCKET. There is no centralized dependency to Publish or Get quotes. The orderbook API is simply a convenience wrapper around web3 calls so that others do not need to aggregate the data themselves.

This API is primarily for the aggregation/display of decentralized orderbook data. Actions such as cancelling, filling, or checking a quotes fillable status is NOT done through this API. If you are a trader please read through this section and then reference our Containerized API.

API KEY

In order to use the API directly or through the SDK, an api key is required. Currently, all api key requests must be made to [e-mail]. Please use subject line: 'API KEY REQUEST' and an api key will be returned.

Pool vs Orderbook

Since all trades must make their way on-chain in some way shape or form, the pool contract for a specific market can be viewed as the "gateway" for this. The pool contract currently supports dual functionality for both interacting with the AMM and interacting with the Orderbook. Functions which include OB in their name are designated for Orderbook functionality

Orderbook

As mentioned in the Orderbook Concepts, quotes are published (by emitting events) to Arbitrum Nova and can be accessed by anyone listening to events on-chain. The Orderbook API will publish quotes for market makers on their behalf and aggregate public order events to create a limit orderbook for any deployed/deployable pool.

When posting an order, a deadline is provided in the quote object which specifies the duration a quote is valid for. When a deadline is surpassed, the quote will expire without the need for action by the quote maker. However, if a user would like to prematurely void a quote before the deadline is hit, they must invoke the cancel function within the pool contract here.

To fill an order that was published to the orderbook, a user must call the fill function available on the pool contract here. Filling orders (as a taker) will incur a transaction fee. Please see Fees for more details.

IMPORTANT: Unlike LP's, makers who utilize the orderbook do NOT collect trading fees.

RFQ

Request-For-Quote is an additional feature available through the orderbook infrastructure in which users can publish requests for a specific pool and receive personalized quotes from market makers. Publishing a request can only be done via WEBSOCKET, but receiving requests can be done via REST API or WEBSOCKET.

What is an RFQ request look like? It is simply an object with the following details:

• PoolKey -> the pool identifier object (base token, quote token, oracle address, strike, maturity, call or put)

• Side -> either a 'bid' or 'ask'

• ChainId -> the chain id (Arbitrum One Mainnet or Goerli Arbitrum Testnet)

• Size -> the quantity that is be requested

• Taker -> the address of the user requesting the quote

When a market maker receives this request (via WEBSOCKET), they will then generate a personalized quote and publish a quote to the orderbook for this request. There is no guarantee that a quote will be returned back after publishing an RFQ request.

Orderbook vs. RFQ Quotes

The main difference between an RFQ quote and an orderbook quote is that the takerAddress is not populated within the quote object for standard quotes. This mean the quote can be filled by any taker address on Arbitrum One. This makes the quote "public". If the takerAddress is populated with an address, it can only be filled by this address, making the order "private". Private quotes are created when a Request-For-Quote is made by a user. See here for more information on how to publish an RFQ.

NOTE: It's important for market makers to publish RFQ quotes with the takerAddress in the quote object populated with the taker address from the request (as opposed to Zero Address). While the quote is viewable by anyone, the quote can only be filled by the requester.