# Order-book HTTP API The order-book HTTP API prepares order data, publishes and lists orders, builds cancellation transactions and quotes trades. Endpoint paths below are relative to `/v1/{network}/limit-orders`. The [order reference](/docs/integration-reference/evm-limit-orders/orders) defines the signed fields. [Batch settlement](/docs/integration-reference/evm-limit-orders/quotes-and-execution) defines the contract inputs and router commands returned with executable book quotes. ## Formats and units [#formats-and-units] JSON uint values are decimal strings. `orderType` and `makerTokenType` are numeric enums; order statuses are strings. `LimitOrder` contains the eight signed fields plus `extension`, `orderType`, `makerTokenType`, `pt`, `impliedRate`, `expiry` and `nonce`. | `orderType` | Trade direction | Quote `inputAmount` token | | ----------- | --------------- | ------------------------- | | `1` | Buy PT | Canonical IBT | | `2` | Sell PT | PT | | `3` | Buy YT | Canonical IBT | | `4` | Sell YT | YT | For maker orders, `makerTokenType` selects the quote leg: | `makerTokenType` | Quote token | | ---------------- | ----------- | | `0` | IBT | | `1` | Vault share | | `2` | Underlying | These HTTP values differ from the contract payload's `quoteKind` values in the [order encoding](/docs/integration-reference/evm-limit-orders/encoding#rate-payload). Amounts use the relevant token's base units. `impliedApy` is a positive numeric fraction: `0.05` means 5%. `expiry` is Unix seconds. The order's `impliedRate` and the quote's `limitImpliedRate` are WAD APYs: `50000000000000000` means 5%. ## Generate, publish and list orders [#generate-publish-and-list-orders] | Method and path | Request | Successful response | | --------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `POST /generate-order-data` | `{ pt, maker, orderType, makingAmount, impliedApy, expiry, makerTokenType? }` | `{ success: true, orderData: { order, orderHash, domain } }` | | `POST /create` | `{ order: LimitOrder, signature?, curvePoolAddress?, allowCrossing? }` | `{ success: true, orderHash }` | | `GET /orders` | Optional `market` (PT), `makerAddress`, comma-separated `orderTypes` and `orderStatus`, `limit`, `offset` | `{ success: true, orders }` | `makerTokenType` defaults to IBT when generating order data. The response provides the order and signing domain as separate fields inside `orderData`. Submit the generated `order` with this structure; the signature covers the eight signed fields, and the indexed terms must agree with those fields and the extension: ```text { order: { salt, maker, receiver, makerAsset, takerAsset, makingAmount, takingAmount, makerTraits, extension, orderType, makerTokenType, pt, impliedRate, expiry, nonce }, signature?, curvePoolAddress?, allowCrossing? } ``` The backend requires the [canonical public fee-order profile](/docs/integration-reference/evm-limit-orders/encoding#order-book-admission-profile). It rejects nonconforming fee wiring, extension bytes, traits or indexed terms; an otherwise valid 1inch signature is not sufficient. Omitting `signature` or sending `"0x"` selects contract-wallet pre-sign admission: the maker must already accept the order hash through ERC-1271. Publication checks whether an order is immediately marketable. Without `curvePoolAddress`, that check uses the book alone. A crossing order is rejected with HTTP 409 unless `allowCrossing` is true. Listing records use `ptAddress`, `makerAddress` and `receiverAddress`, retain signed fields, and add `orderHash`, `filledAmount`, `orderStatus`, `makerBalance`, `orderBookBalance` and `invalidReason`. List limit defaults to 100 and caps at 1,000; offset defaults to 0 and ranges up to 9,000. The `orderStatus` filter accepts comma-separated strings: `open`, `partially_filled`, `filled`, `cancelled` and `expired`. ## Prepare cancellation transactions [#prepare-cancellation-transactions] | Method and path | Request | Successful response | | ---------------------------- | --------------------------------------- | ------------------------------------------------------------------ | | `POST /cancel/single` | `{ order }`, eight signed fields | `{ success: true, transaction: { to, data, value: "0" } }` | | `POST /cancel/batch` | `{ orders }`, 1–20 orders | `{ success: true, transaction: { to, data, value: "0" } }` | | `POST /cancel/advance-nonce` | `{ amount? }`, integer 1–255, default 1 | `{ success: true, transaction: { to, data, value: "0" }, amount }` | Cancellation accepts generated `maker`/`receiver` fields or listed `makerAddress`/`receiverAddress` fields. The response contains transaction data to submit; preparing it does not cancel an order onchain. ## Quote a trade [#quote-a-trade] `POST /quote` returns the fillable input, expected output and optional batch execution data. Without `curvePoolAddress`, it uses the book alone. ### Request [#request] ```text { pt, orderType, inputAmount, curvePoolAddress?, limitImpliedRate?, taker?, fillRecipient?, impliedRateFee?, optimizationTolerance?, maxIterations? } ``` | Field | Meaning | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `pt` | PT identifying the market. | | `orderType` | Trade direction from the enum above. | | `inputAmount` | Input in the direction's canonical IBT, PT or YT base units. | | `curvePoolAddress` | Optional AMM pool to include alongside the book. | | `limitImpliedRate` | Optional WAD APY bound. | | `taker` | Excludes that maker's orders from the quote. | | `fillRecipient` | Caller of the batch filler; must be the router address for router execution. Enables batch data when book fills exist. | | `impliedRateFee` | Optional WAD relative APY fee override for quote calculations; otherwise the live fee is read. It does not override the settlement contract's fee. | | `optimizationTolerance` | Positive numeric tolerance; default `1e-6`. | | `maxIterations` | Positive integer up to 10,000; default 100. | ### Response [#response] The response has no outer `data` wrapper: ```text { success, routing: { alpha, ammAmount, bookAmount, totalAmount, remainderAmount, bookAmountWithFees, totalAmountWithFees, expectedOutput }, avgExecutionPrice, ammPrice, bookPrice, iterations, computeTimeMs, fillGroups, batch?, limit?, error? } ``` Quote amounts, rates and `alpha` are strings. `totalAmount` is the fillable fee-free input; `remainderAmount` is unfilled fee-free input. `totalAmountWithFees` is the funded input budget. `expectedOutput` is quoted output in output-token base units. When requested, `limit` contains: ```text { limitImpliedRate, fillableAmount, remainderAmount } ``` When book fills exist and `fillRecipient` was provided, `batch` contains: ```text { fills, budgets, minMakingFilled, skipReverts, commandInput, preSteps, postSteps } ``` `commandInput` encodes the router's [`FILL_1INCH_LIMIT_ORDERS` (`0x27`)](/docs/integration-reference/evm-limit-orders/quotes-and-execution#fill_1inch_limit_orders-0x27) input. Each pre/post step is `{ command, input }`. Batch `minMakingFilled` retains the raw sum of maker-token amounts, which can mix token units. The quote does not submit a transaction or publish the remainder. `expectedOutput` is not an onchain output guarantee; apply a separate [final balance assertion](/docs/integration-reference/evm-limit-orders/quotes-and-execution#assert_min_balance-0x0f) after output conversions and before transfers. ## Failure responses [#failure-responses] Inspect `success` even after HTTP 200: a quote can return `success: false` with `error`. Request validation uses HTTP 400, semantic admission failures 422, crossing rejection 409 and timeouts 504.