Order types

Immediate-or-cancel

The market order. It crosses whatever rests at or under your limit_per_mtok right now, fills what it can, and cancels the rest — it never becomes a resting order. If nothing is inside your limit the call returns 409 no_fill rather than sitting on the book, so you learn immediately that the price was too tight. This is the shape a /v1/chat/completions call takes under the hood when you have no resting capacity to spend.

POST /v1/orders
Authorization: Bearer sk_live_...
{
  "side": "bid",
  "model": "llama-3.3-70b-instruct",
  "limit_per_mtok": 0.40,
  "size_tokens": 512,
  "immediate_or_cancel": true
}

201 Created
{ "id": "bd_9f02", "status": "filled", "filled_tokens": 512, "remaining_tokens": 0 }

Resting limit bid

Leave off immediate_or_cancel and the bid rests. It fills as asks arrive at or below your price, and each fill is capacity you own and spend later — see the API reference for how a completion drains an unspent fill before it touches the book. Escrow is locked at your limit when you post and released the moment a fill comes in cheaper, so you are never charged more than the market cleared at.

POST /v1/orders
{
  "side": "bid",
  "model": "llama-3.3-70b-instruct",
  "limit_per_mtok": 0.372,
  "size_tokens": 12000000,
  "expires_in": 86400
}

Good-til-time

Add expires_in (seconds) to any resting bid and it withdraws itself at the deadline, refunding whatever escrow never filled. A bid without an expiry rests until it fills or you cancel it with DELETE /v1/orders/{id}. Use a deadline when the work stops being worth doing after a point — an overnight batch you need priced by morning, say — so you are not left holding an order the market drifted away from.

Batch bid

A bid can carry its work with it. Send a commands array instead of a size_tokens and the order's size is the sum of each command's max_tokens — the batch owns its own size so the two can never disagree. The venue runs the prompts as fills land and you collect results from the results_url it returns. A batch always rests: its runner needs the fills to survive the post so it can drain them, which is why a batch cannot also be immediate-or-cancel.

POST /v1/orders
{
  "side": "bid",
  "model": "llama-3.1-8b-instruct",
  "limit_per_mtok": 0.20,
  "commands": [
    { "prompt": "Summarise this ticket: ...", "max_tokens": 400 },
    { "prompt": "Classify this review: ...",  "max_tokens": 64 }
  ]
}

201 Created
{
  "id": "bd_71aa",
  "status": "open",
  "batch": { "commands": 2, "results_url": "/v1/orders/bd_71aa" }
}

Growing expense: a bid that chases the fill

A resting bid can raise its own price over time until it wins a fill. Add a growing_expense block and the venue steps your limit up by step_per_mtok every every_seconds, starting from limit_per_mtok, re-checking the book at each step. It is the mirror image of a host's auto-undercut: one climbs toward a ceiling, the other descends toward a floor, and they meet in the middle.

POST /v1/orders
{
  "side": "bid",
  "model": "llama-3.3-70b-instruct",
  "limit_per_mtok": 0.045,          # start here
  "size_tokens": 8000000,
  "growing_expense": {
    "step_per_mtok": 0.001,         # add this each interval
    "every_seconds": 60,            # once a minute
    "max_per_mtok": 0.060           # never bid above this
  }
}

201 Created
{
  "id": "bd_5c30",
  "status": "open",
  "escalation": { "step_per_mtok": 0.001, "every_seconds": 60, "max_per_mtok": 0.060 }
}

Read the example literally: start at 0.045, add 0.001 once a minute, and never pass 0.060. The first interval at which your bid becomes the cheapest thing at or above a resting ask wins the fill and the climb stops — it rises only as far as it must, so a bid that fills on the second step never reaches the fifth. Reach max_per_mtok without filling and it simply rests there at the cap. This is how you engineer a near-guaranteed fill without watching the book: name the most you will pay, and let the order find the price on its way up.

Because a bid escrows at its current price, each step needs a little more funded balance. The venue tops the escrow up from your balance as it climbs; if a step would need more than you hold, that step is skipped and retried next interval rather than failing the order. Fund the account to the cap and the ascent is unbroken. A step that does not move the price — because the cap rounds to where you already are — is a no-op, and themax_per_mtok must sit above limit_per_mtok or the block is rejected as invalid_escalation.

Combining them

Expiry composes with everything: a growing-expense bid with an expires_in climbs until it either fills, hits the cap, or the deadline withdraws it. The two escalation blocks are exclusive to their side — growing_expense on a bid, and auto_undercut on an ask you post as a host — and sending the wrong one for your side is a 400 invalid_escalation rather than a silently ignored field.

Errors worth handling

• 409 no_fill — an immediate-or-cancel that crossed nothing inside its limit. Raise the ceiling, or rest the bid instead.
• 402 escrow_insufficient — the bid needs more funded balance than you hold. Fund the account or lower the size.
• 400 invalid_escalation — a malformed or mismatched escalation block: a cap on the wrong side of the start, a step too small to move the price, or one paired with a batch or an immediate-or-cancel.