Price lock
Off by default. A request without it rests at the price you set and pays the level it executes at, which is unknown when you send. With the lock on, the request bids the published quote instead, so the price is fixed before it leaves your machine.
The quote
The quote is the clearing level plus a margin, latched once per interval on the exact UTC boundary and held for every request sent inside that interval. It is published at GET /v1/market/price-lock, with how long the current one has left.
A locked request bids the quote, or your max price if that is lower. It starts within its execute window or is cancelled with 429 and no charge. The three cases are drawn on the front page: no lock, locked while the level falls, and locked while it jumps.
Two clocks
They are independent.
| Clock | Length | Whose |
|---|---|---|
| Quote | 1 minute | Everyone's. Latched on exact UTC boundaries and held for every request sent inside the window. |
| Execute window | 10 seconds | Yours. Timed from your submission, so a request sent a second before a boundary keeps its quote and still gets the full window. |
Miss the execute window and the request is cancelled with 429 and never charged. The window bounds the wait: a request that has started generating runs to completion however long that takes. Any max_wait on a locked request is ignored; the window is its timeout.
What a locked request does
| Case | Outcome | Charged |
|---|---|---|
| The level is at or under the quote when the request arrives. | It starts. The charge is the level at execution, which is at most the quote. | The level, up to the quote. |
| The level rises above the quote inside the window, after the request started. | It runs to completion at the quote it holds. This is what the margin buys. | The quote. |
| The level stays above the quote for the whole window. | The request cancels with 429 capacity_unavailable. | Nothing. |
| Your max price is at or below the quote. | The request bids your max price instead, exactly as it would unlocked, and cancels at the window if the level stays above it. | The level, up to your max price. |
| The market is free (level 0). | The quote is 0 and the request runs free. | Nothing. |
What the lock costs
The quote is the clearing level plus a margin, and the charge is min(level, bid). Raising a bid above the level changes nothing you pay, so the margin is a ceiling rather than a fee and a locked request can never cost more than the same request unlocked.
The quote can stand well above the level when the fleet is short. What limits it is the evidence a raise needs: the margin rises only while locked requests with a max price above the quote are missing their window, or clearing under a level that has passed the quote they hold, and every rise takes requests out of that set. The quote never stands above the dearest max price any locked request stated recently.
A locked request bids the quote instead of your max price, so it clears only while the level is at or under the quote and cancels at its window otherwise. The margin is what raises that bid. What the lock costs is admission: the bid drops from your max price to the quote, and the margin is what buys that admission back.
The market moves that margin to target 95% of requests priced above the lock starting inside their execute window. Over the last 10 minutes it managed 89%, published as clear_rate.
Under scarcity clear_rate comes in below the target. The margin buys book position and cannot buy capacity, so a saturated fleet cancels locked requests at their window. Raising it further would lift the quote past more max prices, which takes requests out of the count rather than starting them.
Using it
Per request, or for the account
Send price_lock: true on one request, or switch it on for the account on Bidding and send price_lock: false on a request that should wait instead. Setting a max price does not lock it; a max price is a cap either way.
# know the price in advancecurl "https://api.openfill.ai/v1/market/price-lock?model=placeholder-large"{"price": 0.021, "previous_price": 0.02, "usd_per_million": {"cached": 0.009, "uncached": 0.091, "output": 0.183}, "valid_until": "...", "valid_for_ms": 30000, "execute_window_seconds": 10, "interval_ms": 60000, "clear_rate": 0.8873239436619719, "clear_rate_window_ms": 600000, "target_start_rate": 0.95}import osfrom openai import OpenAIclient = OpenAI(base_url="https://api.openfill.ai/v1", api_key=os.environ["OPENFILL_API_KEY"]) # default: a limit order at $0.05 that waits for the level, and pays the levelr = client.chat.completions.create( model="placeholder-large", messages=[{"role": "user", "content": "hello"}], extra_body={"max_price": 0.05},) # locked: pays the quote above, capped at $0.05, or cancels in the windowr = client.chat.completions.create( model="placeholder-large", messages=[{"role": "user", "content": "hello"}], extra_body={"price_lock": True, "max_price": 0.05},)When to leave it off
A request that should wait for a low level leaves the lock off: locked, it has 10 seconds to start and then cancels. A detached request can lock, and still cancels at its window. Batch lines never lock, since they wait far longer than a quote stands.
The quote stream, GET /v1/market/price-lock/stream, sends one frame per boundary, so a client that locks can hold the next quote before it sends.
The 429 a locked request answers carries code: capacity_unavailable and a Retry-After of one second. The OpenAI SDKs retry it on their own, each retry under the quote of its moment.