Get Started

Running a Solver

A solver is an HTTP endpoint. The coordinator POSTs a borrower’s intent to it; the endpoint prices the loan and returns a signed quote, or declines. There is no SDK to embed, no connection to hold open, and no state to keep between requests. Three things stand between you and your first won quote: getting registered, answering the request, and signing correctly.

1. Get registered

Solvers are onboarded through a whitelist rather than open self-service enrolment. Until your endpoint is in the registry, it receives no traffic: there is no way to opt yourself in.

To start onboarding, reach out through Telegram or the team contact links in the docs header. The coordinator’s endpoint URLs and any credentials are shared directly during onboarding.

You supply a registry entry:

Field	Required	Purpose
`name`	Yes	Label for your endpoint in logs and per-solver metrics
`endpoint`	Yes	The HTTPS URL the coordinator POSTs quote requests to
`hash`	Yes	Opaque 32-byte identifier for your solver
`address`	Yes	The signing address your quotes claim as `solver`; quotes claiming a different address are dropped
`headers`	No	Sent verbatim on every request; the hook for authenticating the coordinator to your endpoint
`overrides.timeout`	No	Raises your response budget above the 5-second default, in milliseconds
`chainIds`	No	Restricts you to specific chains. Omit to receive every chain
`supportedTokens`	No	Restricts you by debt token. Omit to receive every token

Both scoping fields are opt-in narrowing: omitting them means “send me everything”. Setting them wrongly is the most common reason a live solver sees no traffic.

Registry changes take up to 5 minutes to take effect. The coordinator caches the registry and refreshes it on a 5-minute interval, so a newly added endpoint or a changed timeout will not apply immediately.

2. Answer a quote request

Your endpoint receives a POST with the borrower’s intent plus a quoteId minted for your call specifically:

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

Return a signed quote within your response budget. Mirror requestId exactly (a mismatch drops the quote) and mirror quoteId too, or omit it and one will be generated. solver must be the signing address registered for your endpoint; a quote claiming a different address is dropped.

{
  "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…"
}

Full field bounds are in the API Reference.

Declining

Not quoting is a normal outcome, not a failure. Decline in either of two ways:

Return HTTP 404, or
Return HTTP 200 with bond: "0"

Both are recorded as non-quotes. Declining cleanly is strictly better than timing out or returning a malformed body, both of which count against your endpoint’s health.

Budget

The default response window is 5 seconds, measured from the coordinator’s request to your last byte. Exceeding it abandons your quote for that round. If your pricing genuinely needs longer, request a higher overrides.timeout during onboarding rather than running close to the limit: every millisecond you take is one the borrower waits.

3. Sign the quote

Every quote carries two EIP-712 signatures, both from the solver’s key. Both are verified by ECDSA recovery against a reconstruction the coordinator builds from your response, so the terms you sign must be exactly the terms you return.

Signing is EOA-only today. Smart-wallet (ERC-1271) signatures are not yet verifiable and will be rejected. Signatures must be 65-byte r || s || v hex; 64-byte EIP-2098 compact signatures are rejected on purpose.

In TypeScript, signResponse from @iris-credit/iris-sdk produces both signatures in one call, deriving the Permit2 payload from the quote so the two can never disagree. The sections below document exactly what it signs.

The `Quote` signature

An EIP-712 signature over the on-chain Quote struct, which is what Iris.take() verifies to bind you to these terms. Build the typed data with getQuoteTypedData from @iris-credit/core-sdk, mixing the request’s fields with your own:

From the request	From your quote
`borrower`, `receiver`, `collateralToken`, `debtToken`, `collateral`, `debt`, `duration`, `venueBitmap`	`solver`, `blm`, `fixedRate`, `overdueRate`, `overduePeriod`, `bond`, `bondLltv`, `venueId`, `deadline`, `nonce`, `data`

The Permit2 signature

take() pulls your bond in the debt token, and you are not in the call path to approve it, so the authorisation travels with the quote. Build it with getPermit2PermitTypedData from @iris-credit/core-sdk. Every field is determined by the quote you just signed plus your Permit2 nonce:

Permit2 field	Value
`details.token`	The request’s `debtToken`
`details.amount`	Your `bond`
`details.nonce`	Your `permit2Nonce`
`details.expiration`	Unlimited; the allowance does not expire
`spender`	The `Iris` contract
`sigDeadline`	Your `deadline`

Because it authorises exactly this quote’s bond and Permit2 allowance nonces are sequential, the permit is single-use by construction.

Quoting concurrently in the same debt token? Maintain a standing ERC-20 approval to Iris for that token. take() tries the direct approval first and falls back to Permit2, so a standing approval keeps concurrent quotes from contending over sequential permit nonces.

Validation

Every check your quote passes, in order, and what each failure means.

Pricing Considerations

What to weigh when deciding the rate you are willing to stand behind.

FAQ

Why am I getting no requests, and other common first-week questions.

API Reference

Field-by-field schemas and bounds.

Solver Economics & Lifecycle

Integration & Development

Smart Contracts Reference

Running a Solver

1. Get registered

2. Answer a quote request

Declining

Budget

3. Sign the quote

The `Quote` signature

The Permit2 signature

Next

Validation

Pricing Considerations

FAQ

API Reference

​Running a Solver

​1. Get registered

​2. Answer a quote request

​Declining

​Budget

​3. Sign the quote

​The Quote signature

​The Permit2 signature

​Next

Validation

Pricing Considerations

FAQ

API Reference

Running a Solver

1. Get registered

2. Answer a quote request

Declining

Budget

3. Sign the quote

The `Quote` signature

The Permit2 signature

Next