Order book
Configure the Order Book module (depth book, DOM ladder, and trades tape), connect a DepthFeed data provider, and enable DOM click trading.
The Order Book module adds a side panel displaying real-time market depth and recent executions for the active chart's symbol. It is enabled by default when you call enableVelaPro() and streams data from any DataProvider that implements the DepthFeed interface.
The panel includes three views:
| View | Contents |
|---|---|
| Book | Ask levels stacked above bid levels with horizontal depth bars, bid-ask spread, and buy/sell book imbalance. |
| DOM | A price-stepped depth-of-market ladder with configurable columns that users can toggle from the settings menu and reorder by dragging column headers. |
| Trades | Time-and-sales execution tape with one-minute buy/sell volume share and a pause toggle. |
The panel header also provides a venue selector to inspect depth on individual venues listing the same instrument (or merge them into a combined cross-venue book), and each price row offers a right-click menu to draw a horizontal line, copy the price, or run actions contributed by peer modules.
Configuration
BinanceProvider in Vela's open-source core supplies OHLCV candles only, so the Order Book requires a custom DataProvider that also implements DepthFeed.
import type { DataProvider } from '@luxalgo/vela';
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { enableVelaPro, type DepthFeed } from '@luxalgo/vela-pro';
// Custom data provider implementing both OHLCV candles and DepthFeed streams.
declare const MyProvider: new () => DataProvider & DepthFeed;
enableVelaPro({
orderBook: {
views: ['dom', 'book', 'trades'],
settings: {
domColumns: ['orders', 'bid', 'price', 'ask', 'volume'],
cumulative: false,
},
},
});
const workspace = new VelaWorkspace('#chart', {
layout: false,
symbol: 'BTCUSDT',
live: true,
providers: { acme: () => new MyProvider() },
persist: true,
});Pass enableVelaPro({ orderBook: false }) to disable the module.
Options
| Option | Default | Description |
|---|---|---|
views | ['book', 'dom', 'trades'] | Enabled views and their tab order. The first entry is selected when the panel opens. |
clickTrading | true | Allows placing and managing orders from the DOM ladder when the Trading module is installed. Pass false to keep the ladder read-only. |
settings | See below | Initial display preferences (domColumns, cumulative, and combined). |
width | 400 | Initial side panel width in pixels. Users can resize the panel between 260 and 520 pixels. |
order | 3 | Sort order among side rail panel buttons. |
settings configures initial defaults for preferences exposed in the panel's settings menu:
| Setting | Default | Description |
|---|---|---|
domColumns | ['orders', 'sold', 'bid', 'price', 'ask', 'bought', 'delta'] | Ordered list of visible DOM columns. 'price' is always retained. |
cumulative | true | Renders depth bars using cumulative volume from the best bid/ask instead of per-level size. |
combined | false | Aggregates every matching venue listing of the market into a single book bucketed to the coarsest tick size. |
When persist: true is set on VelaWorkspace, user changes to these preferences are stored in the workspace state document and take precedence over settings on reload.
The Order Book module does not expose a controller because it stores no domain records beyond these three UI settings. To open the panel programmatically, call workspace.context().togglePanel('vela-pro.orderbook', true).
DOM columns
| Column | Displayed value at each price level |
|---|---|
'orders' | Working orders and open position markers. Visible only when Trading is installed and an order or position exists. |
'pnl' | Hypothetical profit or loss if the open position were closed at that price. Visible only while a position is open. |
'bid', 'ask' | Resting bid and ask liquidity at that price level. |
'price' | Price level. |
'sold', 'bought' | Cumulative seller-initiated and buyer-initiated traded volume since session tracking started. |
'delta' | Net traded volume (bought minus sold). |
'volume' | Total traded volume (bought plus sold). |
'last' | Size of the most recent print at that price level. |
DepthFeed port
The Order Book resolves the DataProvider serving the active chart's symbol and checks whether it implements DepthFeed. subscribeBook streams order book snapshots and subscribeTrades streams recent prints. You can implement either method independently; views without a backing stream display an unsupported message.
interface DepthFeed {
subscribeBook?(ticker: string, onBook: (book: BookSnapshot) => void, opts?: { depth?: number; onError?: (reason: string) => void }): DepthSubscription;
subscribeTrades?(ticker: string, onTrades: (trades: TapeTrade[], history?: boolean) => void, opts?: { onError?: (reason: string) => void }): DepthSubscription;
}See Quotes and market depth for the full BookSnapshot and TapeTrade schemas and an example implementation.
Streams open when the panel becomes visible and close shortly after it hides. Error strings passed to onError map to distinct empty states in the UI:
| Panel state | Condition |
|---|---|
| "No order book" or "No trades feed" | The symbol's provider omits subscribeBook or subscribeTrades, or calls onError with a reason containing unsupported or unknown market. |
| "Order book unavailable" (with Try again) | onError is called with a reason containing unavailable, limit, or plan. |
| "The feed dropped" (with Reconnect) | onError is called with any other error message. |
The venue selector lists alternate listings of the same underlying instrument and contract type (matching spot with spot and perpetuals with perpetuals) across registered providers that implement DepthFeed.
Ladder trading
When the Trading module is installed, the DOM ladder automatically enables interactive order entry and management through TradingApi:
- Click-to-trade: Once unlocked in the panel header, clicking the bid column places a buy order at that price and clicking the ask column places a sell order. Click-to-trade automatically relocks whenever the panel opens or switches symbols, and remains disabled while viewing another venue's book because orders execute against the active chart's market.
- Order chips: Clicking an order chip in the
'orders'column cancels that working order. - Position chip: Clicking the position chip at the average entry price opens a menu to close the entire position, close half, or cancel working orders for that symbol.
- Position footer: A summary bar beneath the ladder displays current position size and unrealized PnL alongside Cancel all and Close buttons.
Ladder clicks honor all Trading safety settings, staging a draft in the order panel by default or submitting immediately when one-click trading is enabled. Pass orderBook: { clickTrading: false } to keep the DOM ladder read-only even when Trading is installed.
When the Alerts module is enabled, right-clicking a price row also includes an action to create a price alert at that level.
Widgets
createOrderBook(props) mounts the Order Book as a standalone component outside a workspace (see Standalone widgets). All props are optional. views and rows are read once on creation, while the remaining props can be updated via update(props).
| Prop | Description |
|---|---|
symbol | Market symbol to subscribe to. |
directory | Accessor returning chart data (() => chart.data) used to locate the DepthFeed provider for symbol. Without it, the widget renders its unsupported state. |
views | Enabled views and their order. Defaults to ['book', 'dom', 'trades']. |
rows | Number of price levels shown on each side of the Book view. Defaults to 14. |
host | Portal container for menus. Defaults to the widget's root element. |
active | Controls stream lifecycle. When false, book and trade subscriptions close. Defaults to true. |
trading | Accessor returning a TradingApi (such as a TradingController) for DOM ladder execution, or null for a read-only ladder. |
settings | Initial domColumns, cumulative, and combined preferences. |
onSettingsChange | Callback invoked with the full settings object whenever the user updates a preference. |
onPriceMenu | Callback invoked on price-row right-click with (event, at, actions) so host code can open a context menu. When omitted, right-clicking does nothing. |
The widget's tools element contains the venue selector, price-step grouping control, and settings button. Use settings() and applySettings(settings) to persist user preferences across sessions when mounting outside a workspace.
Related
Alerts
Configure price and Pine Script® alerts, handle notification callbacks and webhooks, manage rules from code, and persist alerts to your server.
Journal
Enable the Trading Journal module, import historical executions, persist journal data to your backend, and embed journal widgets on custom pages.