LogoLogo
Join DiscordFollow on XBridge FundsLong $BERA
  • Doc Bros v1
    • Overview
    • Key Features
      • Speed & Liquidity is Key
      • Bropetual Markets
      • A Hub for Berachain DeFi
    • Proof-of-Liquidity
      • Reward Vault
    • Power of Points
    • Partners & Integrations
    • Campaigns
      • bro.trade Em Up
  • bullish bros
    • SuperBros NFT
  • Technicals
    • What is Proof-of-Liquidity?
    • One-Click Trading
    • Funding Rates
  • Liquidations & Insurance Fund
  • Vertex Edge Sequencer
  • Fees
  • PnL Settlements
  • Withdrawals
  • Pricing (Oracles)
  • links & resources
    • bro.trade Links
      • Website
      • Trade Bropetuals
      • Discord
      • X (Twitter)
      • Medium
      • Swap on OogaBooga
    • Berachain Links
      • Berachain.com
      • Official Bridge
      • BeraHub
      • Berascan
      • Bera Discord
      • Berachain X (Twitter)
      • Berachain Docs
    • FAQ
  • developer bros
    • API
      • Gateway
        • Executes
          • Place Order
          • Cancel Order
          • Cancel and Place
          • Cancel Product Order
          • Withdraw Colleteral
          • Transfer Quote
          • Liquidate Subaccount
          • Mint LP
          • Burn LP
          • Link Signer
        • Queries
          • All Products
          • Contracts
          • Fee Rates
          • Health Groups
          • Insurance
          • Linked Signer
          • Market Liquidity
          • Market Prices
          • Max Lp Mintable
          • Max Order Size
          • Max Withdrawable
          • Min Deposit Rates
          • Nonces
          • Order
          • Orders
          • Status
          • Subaccount Info
          • Symbols
        • Signing
          • Examples
          • Q A
      • Subscriptions
        • Authentication
        • Streams
        • Events
        • Rate Limits
      • Archive (indexer)
        • Candlesticks
        • Events
        • Funding Rate
        • Interest Funding Payments
        • Linked Signer Rate Limit
        • Liquidation Feed
        • Maker Statistics
        • Market Snapshots
        • Matches
        • Merkle Proofs
        • Oracle Price
        • Orders
        • Perp Prices
        • Product Snapshots
        • Rewards
        • Signatures
        • Subaccounts
        • Summary
        • HONEY Price
      • Trigger
        • Executes
          • Place Order
          • Cancel Orders
          • Cancel Product Orders
        • Queries
          • List Trigger Orders
      • V2
        • Apr
        • Assets
        • Contracts
        • Orderbook
        • Pairs
        • Tickers
        • Trades
      • Rate limits
      • Errors
      • Symbols
      • Depositing
      • Withdrawing (on-chain)
      • Integrate via Smart Contracts
      • Definitions / Formulas
    • On-Chain Contracts
Powered by GitBook
On this page
  • Order Update
  • Example Scenarios:
  • Trade
  • Best Bid Offer
  • Fill
  • Position Change
  • Book Depth
  1. developer bros
  2. API
  3. Subscriptions

Events

Order Update

Update speed: real-time

{
  "type": "order_update",
  // timestamp of the event in nanoseconds
  "timestamp": "1695081920633151000", 
  "product_id": 1,
  // order digest
  "digest": "0xf7712b63ccf70358db8f201e9bf33977423e7a63f6a16f6dab180bdd580f7c6c",
  // remaining amount to be filled.
  // will be `0` if the order is either fully filled or cancelled.
  "amount": "82000000000000000",
  // any of: "filled", "cancelled", "placed"
  "reason": "filled"
  // an optional `order id` that can be provided when placing an order
  "id": 100
}

Example Scenarios:

Let's assume your initial order amount is 100 units and each match occurs for an amount of 10 units.

Note: The following events only include amount and reason for simplicity.

Scenario 1: Limit Order Partially Fills and Gets Placed

Your limit order matches against existing orders in the book.

You will receive the following events over websocket, each with the same timestamp but in sequential order:

  • Event 1: (90, "filled") — 10 units of your order are filled.

  • Event 2: (80, "filled") — Another 10 units are filled.

  • Event 3: (80, "placed") — The remaining 80 units are placed on the book.

Scenario 2: Immediate-Or-Cancel (IOC) Order Partially Fills

Your IOC order matches against existing orders but is not completely filled.

The events you will receive are as follows:

  • Event 1: (90, "filled") — 10 units are filled.

  • Event 2: (80, "filled") — Another 10 units are filled.

  • Event 3: (0, "cancelled") — The remaining order is cancelled. Note: If your IOC order is fully filled, the last event you will receive is (0, "filled").

Scenario 3: Resting Limit Order Gets Matched

Your existing, or "resting," limit order matches against an incoming order.

You will receive the following event: (90, "filled") — 10 units of your resting limit order are filled.

Scenario 4: Resting Limit Order Gets Cancelled

Your resting limit order could be cancelled for various reasons, such as manual cancellation, expiration, failing health checks, or self-trade prevention.

In any of these cases, you will receive: (0, "cancelled")

Scenario 5: IOC order doesn't cross the book or FOK order fails to be entirely filled

In any of these cases, you will receive: (0, "cancelled")

Trade

Update speed: real-time

{
    "type": "trade",
    "timestamp": "1676151190656903000", // timestamp of the event in nanoseconds
    "product_id": 1,
    "price": "1000", // price the trade happened at, multiplied by 1e18
    // both taker_qty and maker_qty have the same value;
    // set to filled amount (min amount of taker and maker) when matching against book
    // set to matched amm base amount when matching against amm
    "taker_qty": "1000",
    "maker_qty": "1000",
    "is_taker_buyer": true,
    "is_maker_amm": true // true when maker is amm
}

Best Bid Offer

Update speed: real-time

{
    "type": "best_bid_offer",
    "timestamp": "1676151190656903000", // timestamp of the event in nanoseconds
    "product_id": 1,
    "bid_price": "1000", // the highest bid price, multiplied by 1e18
    "bid_qty": "1000", // quantity at the huighest bid, multiplied by 1e18. 
                       // i.e. if this is HONEY with 6 decimals, one HONEY 
                       // would be 1e12
    "ask_price": "1000", // lowest ask price
    "ask_qty": "1000" // quantity at the lowest ask
}

Fill

Update speed: real-time

{
    "type": "fill",
    "timestamp": "1676151190656903000", // timestamp of the event in nanoseconds
    "product_id": 1,
    // the subaccount that placed this order
    "subaccount": "0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43746573743000000000000000",
    // hash of the order that uniquely identifies it
    "order_digest": "0xf4f7a8767faf0c7f72251a1f9e5da590f708fd9842bf8fcdeacbaa0237958fff",
    // the amount filled, multiplied by 1e18
    "filled_qty": "1000",
    // the amount outstanding unfilled, multiplied by 1e18
    "remaining_qty": "2000",
    // the original order amount, multiplied by 1e18
    "original_qty": "3000",
    // fill price
    "price": "24991000000000000000000",
    // true for `taker`, false for `maker`
    "is_taker": true,
    "is_bid": true,
    // true when matching against amm
    "is_against_amm": true,
    // an optional `order id` that can be provided when placing an order
    "id": 100
}

Position Change

Update speed: real-time

{
    "type":"position_change",
    "timestamp": "1676151190656903000", // timestamp of event in nanoseconds
    "product_id":1,
     // whether this is a position change for the LP token for this product
    "is_lp":false,
    // subaccount who's position changed
    "subaccount":"0x7a5ec2748e9065794491a8d29dcf3f9edb8d7c43706d00000000000000000000",
    // new amount for this product
    "amount":"51007390115411548",
    // new quote balance for this product; zero for everything except non lp perps
    // the negative of the entry cost of the perp
    "v_quote_amount":"0"
}

Note: that it is possible that back to back position_change events have the same fields except for timestamp. Additionally, position_change events are not sent on interest and funding payments, and also are not sent on actions done through slow mode (except deposits). The full list of actions that will trigger a PositionChange event are:

  • Minting or burning LP tokens

  • Liquidating a subaccount

  • Matching orders

  • Depositing or withdrawing spot

  • Settling PNL

Book Depth

Update speed: once every 50ms

{
    "type":"book_depth",
    // book depth aggregates a number of events once every 50ms
    // these are the minimum and maximum timestamps from 
    // events that contributed to this response
    "min_timestamp": "1683805381879572835",
    "max_timestamp": "1683805381879572835",
    // the max_timestamp of the last book_depth event for this product
    "last_max_timestamp": "1683805381771464799",
    "product_id":1,
    // changes to the bid side of the book in the form of [[price, new_qty]]
    "bids":[["21594490000000000000000","51007390115411548"]],
    // changes to the ask side of the book in the form of [[price, new_qty]]
    "asks":[["21694490000000000000000","0"],["21695050000000000000000","0"]]
}

Note: To keep an updated local orderbook, do the following:

  1. Subscribe to the book_depth stream and queue up events.

  2. Get a market data snapshot by calling MarketLiquidity. The snapshot contains a timestamp in the response.

  3. Apply events with max_timestamp > snapshot timestamp.

  4. When you receive an event where its last_max_timestamp is not equal to the max_timestamp of the last event you've received, it means some events were lost and you should repeat 1-3 again.

PreviousStreamsNextRate Limits

Last updated 2 months ago