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.
If desired, the API is also accessible through the SDK via convenience wrapper functions. It is not necessary to do direct calls to the API in order to use it.
{% hint style="info" %} Actions such as cancelling, filling, or checking a quotes fillable status is done directly via the pool contract for a specific option market on Arbitrum One (see pool contract for all available actions). The reason for this is simply because the orderbook is merely a decentralized broadcasting service for quotes. More details of this architecture can be found here. {% endhint %}
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 [email protected]. Please use subject line: 'API KEY REQUEST' and an api key will be returned.
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
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.
{% hint style="warning" %} IMPORTANT: Unlike LP's, makers who utilize the orderbook do NOT collect trading fees. {% endhint %}
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:
- PoolAddress -> the pool address (option market) the quote is for
- 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.
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.
{% hint style="success" %}
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.
{% endhint %}