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 defines the signed fields. Batch settlement defines the contract inputs and router commands returned with executable book quotes.

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.

For maker orders, makerTokenType selects the quote leg:

These HTTP values differ from the contract payload's quoteKind values in the order encoding. 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

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:

{
  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. 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

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

POST /quote returns the fillable input, expected output and optional batch execution data. Without curvePoolAddress, it uses the book alone.

Request

{ pt, orderType, inputAmount, curvePoolAddress?,
  limitImpliedRate?, taker?, fillRecipient?, impliedRateFee?,
  optimizationTolerance?, maxIterations? }

Response

The response has no outer data wrapper:

{ 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:

{ limitImpliedRate, fillableAmount, remainderAmount }

When book fills exist and fillRecipient was provided, batch contains:

{ fills, budgets, minMakingFilled, skipReverts,
  commandInput, preSteps, postSteps }

commandInput encodes the router's 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 after output conversions and before transfers.

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.