# Order book and matching We run a spot market for AI inference. Each instrument has its own central limit order book. `text-prime` has its own book, `text-standard` has its own book, `code-max` has its own book. Bids and asks accumulate, and our matching engine pairs them in real time at the best available price. The mechanism is the same one used by every major financial venue, adapted for a commodity that didn't have one. ## You reach the book through two API surfaces Both surfaces feed the same order book underneath. * **Consumption API**, OpenAI-compatible Chat Completions at `https://api.thegrid.ai/v1`. Use the OpenAI SDK you already have and change the base URL. * **Anthropic Messages beta**, Messages-shape endpoint at `https://messages-beta.api.thegrid.ai/v1`. Whichever surface you use, your call hits the same instrument's book and clears against the same resting asks. ## The basic objects A bid is an order to buy a quantity of tokens at or below a stated price. An ask is the sell side. The spread is the gap between the highest bid and the lowest ask, so a tight spread means a deep, competitive book. Depth is the full set of resting orders at every price level. Last trade is the price the most recent fill cleared at. Tokens are quoted per million. One million tokens is the atomic trading quantity and the unit of consumption through the API. Input and output tokens are counted the same. The price you pay for a million tokens is the price the book clears at, regardless of how those tokens split between prompt and completion. ## Order types **Market order.** Fills immediately at the best available prices. Our engine sweeps through resting orders on the opposite side, taking the lowest ask first if you're buying or the highest bid first if you're selling, until your quantity is complete or the book runs out of liquidity. A single market order can produce many trades against many counterparties. Market orders are how Auto Mode buys. When your consumption balance for an instrument runs low, we place a market buy in the background and you get the tokens immediately at the asking price. **Limit order.** Specifies a maximum price for buys or a minimum price for sells. If the order can match at or better than your limit, it fills. Whatever doesn't fill rests on the book until it does, or until you cancel. Limit orders are currently Good Till Cancelled. A limit order whose price crosses the best resting order on the other side fills the matchable portion against existing liquidity and rests the remainder at your limit price. This is how Advanced Mode users set price ceilings: place a limit buy at your chosen price per million tokens and the order fills when an ask drops to that level. ## Price-time priority Matching follows two rules. Better prices match first (the highest bid pairs against the lowest ask). At the same price, earlier orders match first. Partial fills are normal. A 10-million-token market buy that only finds 4 million at the lowest ask keeps walking the book through higher asks until the 10 million is complete or the book runs out. Each match is recorded as a separate trade with its own price, quantity, and counterparty. ## Fills credit your consumption account per instrument When a buy order fills, the matched tokens are credited to your consumption account for that instrument. Your `text-prime` request draws from your `text-prime` balance, your `code-max` request draws from `code-max`. Balances are isolated per instrument. Tokens currently do not expire. They sit in your consumption account until you use them. ## Two paths to the same book The book is the same regardless of how you interact with it. The difference is how orders get placed. * [**Auto Mode**](/docs/start-here/auto-mode-vs-advanced-mode.md) **(default).** You make API calls. We place market buys behind the scenes when your consumption balance runs low, sweeping the book at the current best ask. You never see the book and you don't manage orders. Auto-Reload (optional) keeps your USD balance funded so the market buys never stall. This is how nearly everyone uses The Grid. * [**Advanced Mode**](/docs/start-here/auto-mode-vs-advanced-mode.md) **(opt-in).** Full access. View depth, place limit orders at your price, and manage open orders through the [Trading API](/docs/api-reference/trading-api.md) or the trading dashboard. Enable in [Settings > Account](https://app.thegrid.ai/profile). Both modes use the same Consumption API for inference. Switching between them does not affect existing balances. ## Market data Each instrument's book exposes a ticker (last trade, current bid/ask spread), depth (all resting orders with quantities), trade history (executed trades with timestamps and prices), and price history as OHLCV candles. All of it is available through the [Trading API](/docs/api-reference/trading-api.md) and the Trading dashboard. ## Where this connects * [Auto Mode and Advanced Mode](/docs/start-here/auto-mode-vs-advanced-mode.md), when each mode makes sense. * [Trading API](/docs/api-reference/trading-api.md), endpoints for placing, cancelling, and inspecting orders. * [How we define instruments](broken://pages/sfxozGnwuVs8kBcTbFhO), what each instrument is actually buying and selling, and how qualifying suppliers are admitted. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://thegrid.ai/docs/concepts/order-book-and-matching.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.