Skip to main content
Three wire shapes matter: what a borrower sends the coordinator, what the coordinator sends a solver, and what a solver returns. Each comes in two forms: firm (POST /quote), a signed quote the borrower can take, and indicative (POST /quote/indicative), an unsigned rate preview nothing can take.
Coordinator endpoint URLs are not published. They are shared directly during onboarding — reach out through Telegram or the team contact links in the docs header.
The deployed coordinator answers the browser origins of Iris’s own apps only. Every request must carry an allowlisted Origin header; one that is missing or unrecognised returns 403 with {"detail": "Origin not allowed"} before the body is parsed. Server-side callers that sent no Origin were accepted until 2026-08-23 and are now rejected.Since 2026-08-25 the endpoint is also screened at the edge, ahead of that check. A request arriving without a browser challenge token is answered there with 202 and an HTML challenge page instead of a quote, so a scripted caller sees the challenge rather than the 403. Only a browser running an Iris app mints the token, so neither /quote nor /quote/indicative can be driven from a script or a server.

Conventions

  • Numerics are decimal strings, never JSON numbers. "1000000", not 1000000. The one exception is chainId, which is a number.
  • Addresses are EIP-55 checksummed. All-lowercase hex is also accepted and normalised to EIP-55 on ingress. The two rejected forms are mixed-case hex with an invalid checksum and all-caps hex.
  • Rates and LLTVs are WAD (1e18 = 100%). "81000000000000000" is 8.1%.
  • Amounts are in the token’s own decimals. No implicit scaling.
  • Times are seconds; deadline is a unix timestamp.

POST /quote

Submits a borrower intent and returns the best valid quote from the round.

Request body

venueBitmap is checked venue by venue, so a bit naming a venue with no market for the pair is rejected even when another named venue could serve it. Setting the Morpho Blue bit for a pair with no Morpho Blue market returns 400 with venueBitmap allows morphoBlue but no morphoBlue market exists for 0x…/0x…; clear that venue bit, whether or not another venue’s bit is also set. Clear the bit rather than relying on another venue to cover it.

Response 200

The winning quote’s fields inline, plus allQuotes, every quote that survived validation in that round, the winner included.
Every field is populated on the response except the permit2 pair, which appears only when the winning quote carries it; quoteId is generated if the solver omitted it. Responses echo the caller’s origin in Access-Control-Allow-Origin when it is allowlisted, so only Iris’s own apps can read a response from a browser.

Errors

A 404 is a normal outcome, not a fault: it means every solver declined, timed out, or had its quote dropped in validation. reasons collects the decline reasons solvers gave in their own 404 bodies (see Declining with reasons), with each venue and reason pair listed once across solvers. Where several solvers gave a rate for the same pair, the lowest one is kept, since that is the rate the borrower could get. It is an empty array when no solver gave a reason, so it does not account for solvers that timed out or had their quote dropped. errorCode and detail are unchanged, so callers that only check those keep working.

POST /quote/indicative

Returns a rate preview before the borrower has connected a wallet. The round runs like POST /quote, but only solvers whose registry entry sets an indicativeEndpoint are called, and they answer unsigned. Nothing this route returns can be submitted to Iris.take(): to borrow, request a firm quote from POST /quote.

Request body

The POST /quote body with borrower and receiver optional. When given, each must still be an EIP-55 address, non-zero. Every other field keeps its bounds, and the same request checks run before any solver is called: supported tokens, registered venues, and a market for the pair on every named venue.

Response 200

The winning quote’s terms inline, plus allQuotes, every indicative quote that survived validation. The shape is the POST /quote response with indicative: true added and without quoteId, deadline, nonce, signature or the permit2 pair.

Errors

The same as POST /quote, including the edge 202, the origin 403, and the 404 with reasons when no solver returned a valid quote.

Solver webhook

What the coordinator POSTs to a registered solver’s endpoint.

Request

Identical to the POST /quote body, plus a quoteId minted for this call. Each solver in a round receives a different quoteId and the same requestId.

Response

Return 200 with the body below, or decline with 404 / bond: "0" (a 404 may say why, see Declining with reasons). The permit2 pair is optional together: omit both fields to fund the bond from your standing ERC-20 allowance to Iris, or supply both to stage the Permit2 fallback. Half a pair is rejected.
The deadline window is tight: it is accepted only within the final ~5 seconds before the 2-minute TTL expires. Set deadline to exactly 120 seconds ahead of your own clock at signing time. The slack exists to absorb the trip back to the coordinator, not to allow shorter-lived quotes.
Signature construction is covered in Get Started; the checks these fields face are in Validation.

Declining with reasons

A 404 decline may carry a body saying why you declined. The coordinator passes the reasons on to the borrower in its own 404 (see Errors).
The body is optional, and only a 404 is read for it; a bond: "0" decline carries no reasons. A list that breaks any bound is ignored as a whole, never treated as an error: the decline still counts as a decline.

Indicative requests

For POST /quote/indicative, the coordinator POSTs to your entry’s indicativeEndpoint instead, with the same headers, response budget and scoping filters as endpoint. Entries without an indicativeEndpoint are not called. The request is the indicative request body plus a quoteId; borrower and receiver are left out, not sent as null, when the caller gave none. Return 200 with an unsigned quote, or decline exactly as for a firm request. The response takes the firm response’s fields from requestId to bond with the same bounds, leaves out deadline, nonce, signature and the permit2 pair, and adds one field: solver still has to match your registered address, although nothing is signed. The coordinator does not read your balance or allowances for an indicative quote, so decline with a 404 when you could not fund the bond a firm quote would need, for example {"reasons": [{"venue": "solver", "reason": "insufficient_bond_balance"}]}.

Registry entry

The shape of one registry entry; an organisation registers one entry per endpoint. Entries are created and updated by the team during onboarding, not self-service; see Get Started.
Changes are applied by the team and normally propagate within 5 minutes. A failed refresh leaves the cached registry in place until the next interval, so a change occasionally takes longer.