> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iris.credit/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Request and response schemas, field bounds, and error codes for the Iris RFQ coordinator.

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

<Tip>
  Coordinator endpoint URLs are not published. They are shared directly during onboarding — reach out through [Telegram](https://t.me/+549-WHvSTztiZTI1) or the team contact links in the docs header.
</Tip>

## 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 |

```json theme={null}
{
  "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.

```json theme={null}
{
  "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                                                                  |

```json theme={null}
{
  "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`                                  |

<Callout kind="alert">
  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.
</Callout>

Signature construction is covered in [Get Started](/rfq/running-a-solver/get-started#3-sign-the-quote); the checks these fields face are in [Validation](/rfq/running-a-solver/validation).

## Registry entry

The shape a solver supplies during onboarding. Not self-service; see [Get Started](/rfq/running-a-solver/get-started#1-get-registered).

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

```json theme={null}
{
  "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.