LogoLogo
AppBlogGovSocials
  • What is Premia?
    • Premia Origins
      • History
      • Principles
      • Mission, Vision, & Values
  • Quick Start
  • The Premia Protocol
    • Options on Premia
      • Options Primer
      • Order-book vs. AMM
    • Key Protocol Features
      • Base Layer (Exchange)
      • Depot Layer (Vaults)
      • Messaging Layer (RFQ & OB)
      • Fee Schedule
      • Differentiators
    • Concepts
      • LP Range Orders
      • Trading
      • Orderbook & Request-for-Quote (RFQ)
      • Fees
      • Exercise & Settlement
      • Margin
      • Oracles
      • Liquidity Mining
      • Referral Programs
      • Advanced Exchange Concepts
        • Token Integration Requirements
        • Flash Swaps and Loans
      • Vault Depot
        • What is a Depot?
        • APY Calculation
        • Underwriter Depot
    • Governance
      • Premian Civitas
        • Parliament
        • Blue Descent
        • Premian Assembly
        • "Influence" Politics
      • Voting (vxPremia)
        • vxPremia Manifold
        • vxPremia Rewards
          • Options Liquidity Mining
          • Protocol Commissions
          • AirDrip Initiative
      • Operator & Facilitator Role
        • Operational Expenditure and Maintenance Costs
        • Insurance Fund
      • Meta Economics
  • Developer Center
    • APIs
      • Orderbook API
        • REST API
        • WEBSOCKET
      • Subgraph API
      • Containerized API
        • API Reference
          • Orderbook
            • Quotes
            • Orders
          • Pool
            • Settle
            • Exercise
            • Annihilate
          • Account
            • Collateral Approval
            • Orders
            • Collateral Balances
            • Native Balance
            • Option Balances
          • Pools
            • Find Pools
            • Create Pools
            • Valid Maturities
            • Valid Strikes
          • Oracles
            • IV
            • Spot
          • Vaults
            • Quote
            • Trade
        • WebSockets Reference
          • Authorization
          • Connection
          • Quotes Channel
          • RFQ Channel
    • SDK
      • Guides
      • SDK Technical Docs
    • Contracts
      • Multi-Signature Wallets
      • V3 Protocol
        • Overview
        • Guides
        • Smart Contract Technical Documentation
      • Margin
      • Orderbook
      • vxPremia
      • Universal Router
      • Vaults
    • Integrations
      • Use Cases
      • Code Snippets
    • Subgraph
    • V3 Change log
  • Bots
    • Range Order Bot
  • Resources
    • VIP & Institutional Services
    • Media Kit
    • Bug Bounty
    • Audits
    • Community Groups
    • Research
      • SSVI
    • Legal, Terms, & Disclaimers
      • Terms of Service
      • Privacy Policy
      • Cookie Policy
      • Prohibited Use
      • Affiliate & Advocate Program
      • Self-Service Affiliate Agreement
      • Bug Bounty Terms
      • Academy/Newsletter Disclaimer
      • Trading Competition Terms and Disclaimers
      • Blue Descent
      • Legal Disclaimer
      • Media Disclaimer
      • AML/KYC Policies
      • Intellectual Property
      • Amendments & Updates
      • Contact Us
      • FAQs (WIP)
    • 📰Newsletter
    • 🌊Crypto News Blotter
    • 🎓Academy
    • 🔵Premia Blue (V3)
    • 💎Premia V2 Docs
Powered by GitBook

Terms and Disclaimers

  • Privacy Policy
On this page

Was this helpful?

  1. Developer Center
  2. APIs
  3. Orderbook API

REST API

Rest API End Points

PreviousOrderbook APINextWEBSOCKET

Last updated 1 year ago

Was this helpful?

Overview

Chain
Base Url

Arbitrum Goerli (421613)

https://test.orderbook.premia.finance

Arbitrum One (42161)

https://orderbook.premia.finance

Publish Quotes

To submit a quote to the orderbook, POST quotes can be used. In the background, we will take this quote an submit an event on Arbitrum Nova on the users behalf. One the quote event is generated on Arbitrum Nova, it will be added to the orderbook.

// Javascript Sample Code
const { fetch } = require ('cross-fetch')
const { parseEther } = require("ethers");

const url = 'https://test.orderbook.premia.finance/quotes'

// Free or Paid Tier API KEY
const MOCK_API_KEY = '3423ee2bfd89491f82b351404ea8c3b7'

// object array of one or more quotes
const mockQuotes = [{
  poolKey: {
    base: '0x9f5D1212514Ac88E26c523387C60F87B67AD1130',
    quote: '0x53421DB1f41368E028A4239954feB5033C7B3729',
    oracleAdapter: '0xB89756634Bae979d13721d9883e67CF22cc31D6b',
    strike: parseEther('2900').toString(),
    maturity: 1688716800,
    isCallPool: false
  },
  chainId: '421613'
  provider: '0x9E600587b9035a8C1254E8256F4E588CC33B8467',
  taker: '0x0000000000000000000000000000000000000000',
  price: parseEther('.195').toString(),
  size: parseEther('1').toString(),
  isBuy: false,
  deadline: 1686592096,
  salt: 1686584896,
  signature: {
    r: '0x7feff79a77a023fd8e034066c5bdb78e9b9e5e3804dfc02c0d5b3979b5be8324',
    s: '0x58229484d69566752b48c49326e6eaca2b4fba5372ba638870bda5b58b4fb25e',
    v: 28
  }
}]


async publishQuote(quotes) {
  const response = await fetch(url, {
      method: 'POST',
      headers: {
          'Content-Type': 'application/json',
          'x-apikey': MOCK_API_KEY,
      },
      body: JSON.stringify(quotes),
  })
  
  if (!response.ok) {
    console.error('Request failed: ', await response.json())
    throw new Error(`Failed to publish quotes: ${response.statusText}`)
  }
		
  return response.json()
}


publishQuote(mockQuotes)

Get Quotes

When using GET quotes, orders are returned based on the params details provided. quotes endpoint is ideal for determining which order(s) will satisfy a specific order size and side. The returned quotes are ordered by price, and only the order(s) that satisfy the size (cumulatively) will be returned.

Additionally, it is possible to receive RFQ quotes along with public quotes by specifying a taker address. The allows users to find the best possible public/private quote combination for a particular quote size.

// Javascript Sample Code
const { fetch } = require ('cross-fetch')
const { parseEther } = require("ethers");

const baseUrl = 'https://test.orderbook.premia.finance'

// Free or Paid Tier API KEY
const MOCK_API_KEY = '3423ee2bfd89491f82b351404ea8c3b7'

// Params
const poolAddress='0xb9e594644D3BB24cfcBa3FA0289F18dB7cf81573'
const size= parseEther('5').toString()
const side='bid' //Side is 'ask'('bid') if the intention is to buy(sell). 
const chainId='421613'


async getQuotes(_addr, _size, _side, _chainId){
  const url = `${baseUrl}/quotes?poolAddress=${_addr}&size=${_size}&side=${_side}&chainId=${_chainId}`
	
  const response = await fetch(url, {
    headers: {
      'Content-Type': 'application/json',
      'x-apikey': MOCK_API_KEY
    }
  })
	
  if (!response.ok) {
    console.error('Request failed: ', await response.json())
    throw new Error(`Failed to fetch quote: ${response.statusText}`)
  }
	
  const quotes = await response.json()	
  
  return quotes
}

getQuotes(poolAddress, size, side, chainId)

Get rfq_quotes

// Javascript Sample Code
const { fetch } = require ('cross-fetch')

const baseUrl = 'https://test.orderbook.premia.finance'

// Free or Paid Tier API KEY
const MOCK_API_KEY = '3423ee2bfd89491f82b351404ea8c3b7'

// Params
const poolAddress='0xb9e594644D3BB24cfcBa3FA0289F18dB7cf81573'.toLowerCase()
const side='bid'
const chainId='421613'
const takerAddress = '0xd18EE1c241e7A7e59797763C94d2Bd8C9169c831'


async getRfqQuotes(_addr, _side, _chainId, _taker){
  const url = `${baseUrl}/quotes?poolAddress=${_addr}&side=${_side}&chainId=${_chainId}&taker=${_taker}`
	
  const response = await fetch(url, {
    headers: {
      'Content-Type': 'application/json',
      'x-apikey': MOCK_API_KEY
    }
  })
	
  if (!response.ok) {
    console.error('Request failed: ', await response.json())
    throw new Error(`Failed to fetch quote: ${response.statusText}`)
  }
	
  const rfqQuotes = await response.json()	
  
  return rfqQuotes
}

getRfqQuotes(poolAddress, side, chainId, takerAddress)

Get Orders

GET orders is a general purpose query of orders in the orderbook. Many of the params are optional to suit the needs of the query. Orders are returned in descending order based on the timestamp in which they were created.

Good To Know: size param in GET orders is not the same as size param in GET quotes. See param descriptions.

// Javascript Sample Code
const { fetch } = require ('cross-fetch')

const baseUrl = 'https://test.orderbook.premia.finance'

// Free or Paid Tier API KEY
const MOCK_API_KEY = '3423ee2bfd89491f82b351404ea8c3b7'

// Params
const poolAddress='0xb9e594644D3BB24cfcBa3FA0289F18dB7cf81573'
const chainId='421613'


async getOrders(_addr, _chainId){
  const url = `${baseUrl}/orders?poolAddress=${_addr}&chainId=${_chainId}`
	
  const response = await fetch(url, {
    headers: {
      'Content-Type': 'application/json',
      'x-apikey': MOCK_API_KEY
    }
  })
	
  if (!response.ok) {
    console.error('Request failed: ', await response.json())
    throw new Error(`Failed to fetch quote: ${response.statusText}`)
  }
	
  const orders = await response.json()	
  
  return orders
}

getOrders(poolAddress, chainId)

When publishing an RFQ, users can for quotes via WEBSOCKET or use the rfq_quotes endpoint to retrieve only RFQ quotes via REST API.

listen

Get all quotes available using query params

get
Authorizations
Query parameters
poolAddressstringOptional

unique address of the pool

Pattern: ^0x[a-fA-F0-9]{40}$
sizestringOptional

min order size of each order (1 contract = 1e18)

Pattern: ^[0-9]*$
sidestringOptional

orderbook side ("ask" or "bid")

Pattern: ^bid$|^ask$
chainIdstringRequired

chain id ("42161" or "421613")

Pattern: ^42161$|^421613$
providerstringOptional

unique address of the provider

Pattern: ^0x[a-fA-F0-9]{40}$
Responses
200
Successful operation
application/json
400
Invalid parameters supplied
application/json
401
Not authorized
application/json
get
GET /orders HTTP/1.1
Host: test.orderbook.premia.finance
x-apikey: YOUR_API_KEY
Accept: */*
{
  "validQuotes": [
    {
      "poolKey": {
        "base": "text",
        "quote": "text",
        "oracleAdapter": "text",
        "strike": "text",
        "maturity": 1,
        "isCallPool": true
      },
      "chainId": "text",
      "provider": "text",
      "taker": "text",
      "price": "text",
      "size": "text",
      "isBuy": true,
      "deadline": 1,
      "salt": 1,
      "signature": {
        "r": "text",
        "s": "text",
        "v": 1
      },
      "quoteId": "text",
      "fillableSize": "text",
      "ts": "1693962436"
    }
  ],
  "invalidQuotes": [
    {
      "reason": "InsufficientCollateralAllowance",
      "quote": {
        "poolKey": {
          "base": "text",
          "quote": "text",
          "oracleAdapter": "text",
          "strike": "text",
          "maturity": 1,
          "isCallPool": true
        },
        "chainId": "text",
        "provider": "text",
        "taker": "text",
        "price": "text",
        "size": "text",
        "isBuy": true,
        "deadline": 1,
        "salt": 1,
        "signature": {
          "r": "text",
          "s": "text",
          "v": 1
        },
        "quoteId": "text",
        "fillableSize": "text",
        "ts": "1693962436"
      }
    }
  ]
}

Publishes the quote into the orderbook

post
Authorizations
Body
chainIdstringRequiredPattern: ^42161$|^421613$
providerstringRequiredPattern: ^0x[a-fA-F0-9]{40}$
takerstringRequiredPattern: ^0x[a-fA-F0-9]{40}$
pricestringRequired
sizestringRequired
isBuybooleanRequired
deadlineintegerRequired
saltintegerRequired
Responses
200
Quote exists
application/json
201
Quote created
application/json
400
Bad request
application/json
401
Not authorized
application/json
post
POST /quotes HTTP/1.1
Host: test.orderbook.premia.finance
x-apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 270

[
  {
    "poolKey": {
      "base": "text",
      "quote": "text",
      "oracleAdapter": "text",
      "strike": "text",
      "maturity": 1,
      "isCallPool": true
    },
    "chainId": "text",
    "provider": "text",
    "taker": "text",
    "price": "text",
    "size": "text",
    "isBuy": true,
    "deadline": 1,
    "salt": 1,
    "signature": {
      "r": "text",
      "s": "text",
      "v": 1
    }
  }
]
{
  "created": [
    {
      "poolKey": {
        "base": "text",
        "quote": "text",
        "oracleAdapter": "text",
        "strike": "text",
        "maturity": 1,
        "isCallPool": true
      },
      "chainId": "text",
      "provider": "text",
      "taker": "text",
      "price": "text",
      "size": "text",
      "isBuy": true,
      "deadline": 1,
      "salt": 1,
      "signature": {
        "r": "text",
        "s": "text",
        "v": 1
      },
      "quoteId": "text",
      "fillableSize": "text",
      "ts": "1693962436"
    }
  ],
  "failed": [
    {
      "reason": "Quote deadline is invalid (cannot be less than 10 sec)",
      "quote": {
        "poolKey": {
          "base": "text",
          "quote": "text",
          "oracleAdapter": "text",
          "strike": "text",
          "maturity": 1,
          "isCallPool": true
        },
        "chainId": "text",
        "provider": "text",
        "taker": "text",
        "price": "text",
        "size": "text",
        "isBuy": true,
        "deadline": 1,
        "salt": 1,
        "signature": {
          "r": "text",
          "s": "text",
          "v": 1
        }
      }
    }
  ],
  "exists": [
    {
      "poolKey": {
        "base": "text",
        "quote": "text",
        "oracleAdapter": "text",
        "strike": "text",
        "maturity": 1,
        "isCallPool": true
      },
      "chainId": "text",
      "provider": "text",
      "taker": "text",
      "price": "text",
      "size": "text",
      "isBuy": true,
      "deadline": 1,
      "salt": 1,
      "signature": {
        "r": "text",
        "s": "text",
        "v": 1
      },
      "quoteId": "text",
      "fillableSize": "text",
      "ts": "1693962436"
    }
  ]
}
  • Overview
  • Publish Quotes
  • POSTPublishes the quote into the orderbook
  • Get Quotes
  • GETGet best quotes to fill the order parametrised by query params
  • Get rfq_quotes
  • GETGet private quotes assigned to user (taker) address
  • Get Orders
  • GETGet all quotes available using query params

Get best quotes to fill the order parametrised by query params

get
Authorizations
Query parameters
poolAddressstringRequired

unique address of the pool

Pattern: ^0x[a-fA-F0-9]{40}$
sizestringRequired

fill size (1 contract = 1e18)

Pattern: ^[0-9]*$
sidestringRequired

orderbook side ("ask" or "bid")

Pattern: ^bid$|^ask$
chainIdstringRequired

chain id ("42161" or "421613")

Pattern: ^42161$|^421613$
providerstringOptional

unique address of the provider

Pattern: ^0x[a-fA-F0-9]{40}$
takerstringOptional

unique address of the taker (for rfq quotes)

Pattern: ^0x[a-fA-F0-9]{40}$
Responses
200
Successful operation
application/json
400
Invalid parameters supplied
application/json
401
Not authorized
application/json
get

Get private quotes assigned to user (taker) address

get
Authorizations
Query parameters
poolAddressstringRequired

unique address of the pool

Pattern: ^0x[a-fA-F0-9]{40}$
sidestringRequired

orderbook side ("ask" or "bid")

Pattern: ^bid$|^ask$
chainIdstringRequired

chain id ("42161" or "421613")

Pattern: ^42161$|^421613$
takerstringRequired

taker address

Pattern: ^0x[a-fA-F0-9]{40}$
Responses
200
Successful operation
application/json
400
Invalid parameters supplied
application/json
401
Not authorized
application/json
get
GET /quotes HTTP/1.1
Host: test.orderbook.premia.finance
x-apikey: YOUR_API_KEY
Accept: */*
[
  {
    "poolKey": {
      "base": "text",
      "quote": "text",
      "oracleAdapter": "text",
      "strike": "text",
      "maturity": 1,
      "isCallPool": true
    },
    "chainId": "text",
    "provider": "text",
    "taker": "text",
    "price": "text",
    "size": "text",
    "isBuy": true,
    "deadline": 1,
    "salt": 1,
    "signature": {
      "r": "text",
      "s": "text",
      "v": 1
    }
  }
]
GET /rfq_quotes HTTP/1.1
Host: test.orderbook.premia.finance
x-apikey: YOUR_API_KEY
Accept: */*
[
  {
    "poolKey": {
      "base": "text",
      "quote": "text",
      "oracleAdapter": "text",
      "strike": "text",
      "maturity": 1,
      "isCallPool": true
    },
    "chainId": "text",
    "provider": "text",
    "taker": "text",
    "price": "text",
    "size": "text",
    "isBuy": true,
    "deadline": 1,
    "salt": 1,
    "signature": {
      "r": "text",
      "s": "text",
      "v": 1
    }
  }
]