OrderBook¶

Each trading pair on Sera has its own OrderBook contract that manages orders, matching, and settlement.

Finding Markets¶

Each trading pair has a unique OrderBook contract address (also called a "market"). You can discover available markets using the Markets GraphQL Query:

{
  markets(first: 10) {
    id                    # This is the OrderBook contract address
    baseToken { symbol }
    quoteToken { symbol }
  }
}

The id field returned is the OrderBook contract address you'll use for trading.

View Functions¶

getDepth¶

Returns the total open order amount at a specific price level.

function getDepth(bool isBid, uint16 priceIndex) external view returns (uint64)

Parameters:

• isBid - true for bid depth, false for ask depth
• priceIndex - The price book index

Returns:

• uint64 - Total raw amount at this price level

Example:

const bidDepth = await orderBook.getDepth(true, 6500);
const askDepth = await orderBook.getDepth(false, 6600);

console.log(`Bid depth at 6500: ${bidDepth} raw units`);
console.log(`Ask depth at 6600: ${askDepth} raw units`);

bestPriceIndex¶

Returns the best available price on the order book.

function bestPriceIndex(bool isBid) external view returns (uint16)

Parameters:

• isBid - true for highest bid, false for lowest ask

Returns:

• uint16 - The price index of the best bid/ask

Example:

try {
  const bestBid = await orderBook.bestPriceIndex(true);
  const bestAsk = await orderBook.bestPriceIndex(false);
  console.log(`Spread: ${bestAsk - bestBid} ticks`);
} catch (e) {
  console.log("Order book is empty");
}

isEmpty¶

Checks if one side of the order book is empty.

function isEmpty(bool isBid) external view returns (bool)

Example:

const isBidEmpty = await orderBook.isEmpty(true);
const isAskEmpty = await orderBook.isEmpty(false);

if (isBidEmpty && isAskEmpty) {
  console.log("No liquidity available");
}

getOrder¶

Returns details of a specific order.

function getOrder(OrderKey calldata orderKey) external view returns (Order memory)

Parameters:

struct OrderKey {
    uint16 priceIndex;
    uint256 orderIndex;
    bool isBid;
}

Returns:

struct Order {
    uint64 amount;       // Remaining raw amount
    address owner;       // Order owner
}

Example:

const orderKey = {
  priceIndex: 6500,
  orderIndex: 42,
  isBid: true
};

const order = await orderBook.getOrder(orderKey);
console.log(`Owner: ${order.owner}`);
console.log(`Remaining: ${order.amount} raw units`);

getClaimable¶

Returns the claimable proceeds of a filled order.

function getClaimable(OrderKey calldata orderKey) external view returns (
    uint64 claimableRawAmount,
    uint256 claimableAmount,
    uint256 feeAmount,
    uint256 rebateAmount
)

Returns:

• claimableRawAmount - Raw amount available to claim
• claimableAmount - Token amount after fees
• feeAmount - Maker fee to be paid
• rebateAmount - Maker rebate to be received

Example:

const orderKey = { priceIndex: 6500, orderIndex: 42, isBid: true };
const { claimableAmount, rebateAmount } = await orderBook.getClaimable(orderKey);

console.log(`Claimable: ${claimableAmount}`);
console.log(`Rebate: ${rebateAmount}`);

getExpectedAmount¶

Simulates a market order to get expected input/output amounts.

function getExpectedAmount(
    uint16 limitPriceIndex,
    uint64 rawAmount,
    uint256 baseAmount,
    uint8 options
) external view returns (uint256 inputAmount, uint256 outputAmount)

Options:

• LSB (bit 0): 0 = Ask, 1 = Bid
• Bit 1: 1 = expendInput

Example:

// Simulate buying with 100 USDC
const options = 0b11;  // Bid + expendInput
const [input, output] = await orderBook.getExpectedAmount(
  7000,    // limitPriceIndex
  100n,    // rawAmount (100 USDC in raw)
  0n,      // baseAmount (not used)
  options
);

console.log(`Would spend: ${input}, Would receive: ${output}`);

Market Info¶

quoteToken¶

Returns the quote token address.

function quoteToken() external view returns (address)

baseToken¶

Returns the base token address.

function baseToken() external view returns (address)

quoteUnit¶

Returns the quote unit (raw amount to quote token conversion factor).

function quoteUnit() external view returns (uint256)

makerFee¶

Returns the maker fee in basis points × 100.

function makerFee() external view returns (int24)

Negative values indicate a rebate.

takerFee¶

Returns the taker fee in basis points × 100.

function takerFee() external view returns (uint24)

orderToken¶

Returns the OrderNFT contract address for this market.

function orderToken() external view returns (address)

priceBook¶

Returns the PriceBook contract address for this market.

function priceBook() external view returns (address)

Amount Conversions¶

rawToQuote¶

Converts raw amount to quote token amount.

function rawToQuote(uint64 rawAmount) external view returns (uint256)

quoteToRaw¶

Converts quote token amount to raw amount.

function quoteToRaw(uint256 quoteAmount, bool roundingUp) external view returns (uint64)

rawToBase¶

Converts raw amount to base token amount at a given price.

function rawToBase(
    uint64 rawAmount,
    uint16 priceIndex,
    bool roundingUp
) external view returns (uint256)

baseToRaw¶

Converts base token amount to raw amount at a given price.

function baseToRaw(
    uint256 baseAmount,
    uint16 priceIndex,
    bool roundingUp
) external view returns (uint64)

Price Conversions¶

indexToPrice¶

Converts a price index to the actual price.

function indexToPrice(uint16 priceIndex) external view returns (uint256)

priceToIndex¶

Converts a price to the nearest price index.

function priceToIndex(
    uint256 price,
    bool roundingUp
) external view returns (uint16 index, uint256 correctedPrice)

Block Trade Logs¶

blockTradeLogIndex¶

Returns the current block trade log index.

function blockTradeLogIndex() external view returns (uint16)

blockTradeLogs¶

Returns the trade log for a specific block.

function blockTradeLogs(uint16 index) external view returns (BlockTradeLog memory)

struct BlockTradeLog {
    uint64 blockTime;
    uint64 askVolume;
    uint64 bidVolume;
    uint16 open;
    uint16 high;
    uint16 low;
    uint16 close;
}