API Reference

Three wire shapes matter: what a borrower sends the coordinator, what the coordinator sends a solver, and what a solver returns.

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.

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. Lowercase or all-caps hex is rejected.
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

Field	Type	Bounds
`requestId`	string	UUIDv7
`chainId`	number	`1` (Ethereum) or `9991` (VNet staging)
`borrower`	string	EIP-55 address, non-zero
`receiver`	string	EIP-55 address, non-zero
`collateralToken`	string	EIP-55 address; must be a protocol-supported token
`collateral`	string	uint256, ≥ 1
`debtToken`	string	EIP-55 address; must be a protocol-supported token
`debt`	string	uint256, ≥ 1
`maxFixedRate`	string	WAD, `1e14` – `1e18` (1 bp – 100%)
`duration`	string	seconds, `86400` – `63072000` (1 day – 2 years)
`venueBitmap`	string	uint256, ≥ 1; every set bit must be a registered venue id

{
  "requestId": "0199a3f1-8c00-7000-8000-000000000000",
  "chainId": 1,
  "borrower": "0xAaCce4ec50328120EF3899a978e87FCa6b8bbE84",
  "receiver": "0xAaCce4ec50328120EF3899a978e87FCa6b8bbE84",
  "collateralToken": "0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0",
  "collateral": "1000000000000000000",
  "debtToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "debt": "1000000000",
  "maxFixedRate": "90000000000000000",
  "duration": "7776000",
  "venueBitmap": "3"
}

Response `200`

The winning quote’s fields inline, plus allQuotes, every quote that survived validation in that round, the winner included.

{
  "requestId": "0199a3f1-8c00-7000-8000-000000000000",
  "quoteId": "0199a3f1-8c01-7000-8000-000000000000",
  "solver": "0xE05FCc23807536bEe418f142D19fa0d21BB0CFF7",
  "blm": "0xE0Ae439c391d8DcF870a3045f09Fe901Fe8ef07b",
  "fixedRate": "81000000000000000",
  "venueId": "1",
  "data": "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
  "overdueRate": "162000000000000000",
  "overduePeriod": "604800",
  "bondLltv": "900000000000000000",
  "bond": "905000000",
  "deadline": "1785235562",
  "nonce": "1",
  "signature": "0x…",
  "permit2Nonce": "0",
  "permit2Signature": "0x…",
  "allQuotes": [{ "…": "same shape, one entry per surviving quote" }]
}

Every field is populated on the response; quoteId is generated if the solver omitted it. Responses carry permissive CORS headers, so browser clients can call the coordinator directly.

Errors

Status	`errorCode`	When
`400`	`VALIDATION_ERROR`	Schema failure, unsupported token, or a `venueBitmap` bit outside registered venues
`404`	`QUOTE_ERROR`	No solver returned a valid quote; `detail` is `"No quotes available"`
`422`	`VALIDATION_ERROR`	Body was not valid JSON
`500`	`INTERNAL_ERROR`	Unexpected failure

{
  "detail": "No quotes available",
  "errorCode": "QUOTE_ERROR",
  "id": "0199a3f1-8c00-7000-8000-000000000000"
}

A 404 is a normal outcome, not a fault: it means every solver declined, timed out, or had its quote dropped in validation.

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.

Field	Type	Notes
`quoteId`	string	UUIDv7, injected per solver
all request-body fields		Passed through unchanged

Response

Return 200 with the body below, or decline with 404 / bond: "0".

Field	Type	Bounds
`requestId`	string	UUIDv7; must match the request
`quoteId`	string	UUIDv7, optional (generated if omitted)
`solver`	string	EIP-55 address, non-zero; the EOA whose key signed. Must match your registered signing address
`blm`	string	EIP-55 address, non-zero; must be enabled on `Iris`
`fixedRate`	string	WAD, `1e14` – `1e18`; must be ≤ `maxFixedRate`
`venueId`	string	`0` – `127`; a venue index, and its bit must be set in `venueBitmap`
`data`	string	hex; must be an enabled market-data payload
`overdueRate`	string	WAD, `0` – `1e18`; added to `fixedRate` after maturity
`overduePeriod`	string	seconds, `0` – `2592000` (30 days)
`bondLltv`	string	WAD, `0` – `1e18`; must be enabled on `Iris`
`bond`	string	uint256; `"0"` declines
`deadline`	string	unix seconds; within the 2-minute quote TTL
`nonce`	string	uint256, ≥ 1
`signature`	string	65-byte `r \|\| s \|\| v` hex over the on-chain `Quote`
`permit2Nonce`	string	uint48, `0` – `281474976710655`; `0` is valid
`permit2Signature`	string	65-byte `r \|\| s \|\| v` hex over the Permit2 `PermitSingle`

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.

Registry entry

The shape a solver supplies during onboarding. Not self-service; see Get Started.

Field	Type	Required	Notes
`name`	string	Yes	Label used in logs and per-solver metrics
`endpoint`	string	Yes	HTTPS URL receiving quote requests
`hash`	string	Yes	Opaque 32-byte solver identifier
`address`	string	Yes	Solver signing address; responses whose `solver` differs are dropped
`headers`	object	No	Sent verbatim on every request; the hook for authenticating the caller
`overrides.timeout`	number	No	Response budget in milliseconds; default `5000`
`chainIds`	number[]	No	Restrict to specific chains. Omit for all
`supportedTokens`	string[]	No	Restrict by debt token, EIP-55. Omit for all

{
  "name": "example-solver",
  "hash": "0x0000000000000000000000000000000000000000000000000000000000000001",
  "address": "0xE05FCc23807536bEe418f142D19fa0d21BB0CFF7",
  "endpoint": "https://solver.example.com/rfq",
  "headers": { "x-api-key": "…" },
  "overrides": { "timeout": 5000 },
  "chainIds": [1],
  "supportedTokens": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"]
}

Changes take up to 5 minutes to propagate.

Solver Economics & Lifecycle

Integration & Development

Smart Contracts Reference

Conventions

`POST /quote`

Request body

Response `200`

Errors

Solver webhook

Request

Response

Registry entry

​Conventions

​POST /quote

​Request body

​Response 200

​Errors

​Solver webhook

​Request

​Response

​Registry entry

Conventions

`POST /quote`

Request body

Response `200`

Errors

Solver webhook

Request

Response

Registry entry