How to query Iris Core data with the API?
You can query Iris Core data with the GraphQL API. Queries run against the GraphQL Playground. A few conventions carry through every example:- Examples read from Ethereum mainnet (
chainId: 1). - By default the API returns only the first 50 results; pass
limit(up to 1000) and page with cursors for more. TheloanPositionsview pages byoffsetinstead. - Addresses are lowercase hex, and filters are exact-match.
BigIntvalues are returned as strings; rates and LLTVs are WAD (1e18), amounts are in the token’s own decimals.- Plural query names are generated from table names:
blmParamss,marketDatas, andwhitelistEntrysare not typos.
Discovery and Listing
Loans List
A loan is identified by its pod, the isolated clone address holding that borrower’s position.(chainId, pod) is the primary key everywhere in this API. The single-pod examples below take the pod as a $pod variable: fill it with any pod a loans query returns.
- All Loans
- By Borrower
- By Solver
- Specific Loan
position.
Loan and position in one filter
where cannot traverse a relation, so a condition spanning both sides (a solver’s loans that still carry a bond requirement, say) needed two queries and a client-side join.
loanPositions is a read-only view over loan joined to position on (chainId, pod). Every column of both tables sits flat on one row, so a single where can filter across both.
- Plural only. There is no single-row
loanPosition(chainId:, pod:)lookup; filter onpodinstead. - No relations.
collateralTokenanddebtTokenare raw addresses here, not token objects, so{ symbol decimals }does not resolve. Read metadata fromtokensin the same request. - Offset paging, not cursors.
afterandbeforeare not arguments on this query, andpageInfocarrieshasNextPageandhasPreviousPagewithout cursors. Page withlimitandoffset. orderByis required to page safely. A view has no primary key to break ties on and no default order, so a paginated read must order on an effectively unique column (pod, withchainIdfiltered), or pages can skip and repeat rows.
AND and OR, a default page of 50 rows, and a totalCount over the whole filtered set.
Position Metrics
Collateral, Debt & Bond
position is one-to-one with loan on (chainId, pod) and holds everything mutable.
- All Positions
- Specific Position
bond and bondRequirement are in the debt token’s decimals, collateral in the collateral token’s. A resolved loan keeps its row; its state follows from the Loan Status table below.
Fixed vs Floating Legs
Legs are as of
lastUpdate, not as of now.
Bond Health
ceil((floatingLeg - fixedLeg) × 1e18 / bond), exceeds bondLltv; a zero bondRequirement is always healthy. bondRequirement floors withdrawBond: a bond a rebase slashed below it cannot be withdrawn. Both legs are as of lastUpdate, so a ratio computed from them understates a position that has not been touched in a while. For that comparison computed against live venue indices, read positionHealths. See Bond Mechanics.
Liquidatability estimates
positionHealths carries one row per open loan. bondHealthFactor is refreshed by a poll that reads each market’s venue indices onchain and accrues the legs to the poll block, and venueLiquidated follows the venues’ liquidation events. The poll runs every 25 blocks (about five minutes). The entity exists so a keeper can filter and sort liquidatability server-side instead of pulling every position and recomputing it client-side.
Five things to know before filtering on it:
bondHealthFactoris an estimate,liquidatableAtis exact. The factor is accurate as ofupdatedAtand drifts until the next poll, so filter with a margin above1and re-verify onchain before sending a transaction.liquidatableAtcomes from the loan’s own terms and does not move.nullmeans no drawdown, not “unknown”: the floating leg is not above the fixed leg. Becausenullnever satisfies a comparison, anybondHealthFactor_*filter drops those rows, which is what a keeper scan wants.- It is the bond liquidation check.
bondHealthFactorcompares drawdown tobondLltv, which is whatliquidateBondchecks.bondRequirementfloorswithdrawBond:bondbelow it is a filter onloanPositionsfor solvers who cannot withdraw. venueLiquidatedis over-inclusive. It turnstruewhen Morpho Blue emitsLiquidate, or the Aave V3 or SparkLend pool emitsLiquidationCall, for an open loan’s pod, and back tofalseat the next IRIS action that accrues or rebases the position. It can staytruefor a position with nothing left to recognize, so filter onvenueLiquidated: trueto find positions awaiting arebaseand check onchain before sending one.- Rows exist only while the loan is open. A row is created in the block the loan opens, with
bondHealthFactornulluntil the first poll, and is deleted by the first poll after the loan resolves (bond requirement, debt, fixed leg and surplus all zero). A loan whose bond requirement is zero but still owes the fixed leg or holds surplus keeps its row:liquidatableAtstill applies,bondHealthFactorreadsnullthere, andvenueLiquidatedis never set. There are no relations on this entity, so read the loan and position fields in a second query keyed bypod.
bondHealthFactor is the solver’s bond against its drawdown. It is unrelated to the borrower’s venue health factor, which IRIS does not index.
Loan Status
Status is not a column: it is derived at read time frombondRequirement, debt, fixedLeg, surplus, maturity, and overduePeriod.
now in unix seconds:
A loan is open until it is resolved. Within open,
bondRequirement > 0 is a bonded loan; bondRequirement == 0 with debt, fixedLeg or surplus still outstanding is an unbonded one: the solver’s bond obligation is over, repay and liquidate are still callable, escape is not yet.
Of these, resolved is a filter on all four balances, and the liquidatable set is positionHealths(where: { liquidatableAt_lte: now }), whose rows are open by construction. For active and overdue, fetch the open set with positions(where: { OR: [{ bondRequirement_gt: "0" }, { debt_gt: "0" }, { fixedLeg_gt: "0" }, { surplus_gt: "0" }] }) and classify client-side, comparing now against the indexed block timestamp from _meta { status }.
Position Tracking
Borrower All Loans Position
Everything a borrower needs on one screen: terms, live balances, and both USD legs.Borrower Account Overview
Loans, claimable balances, and delegated managers in one request.Solver Book
A solver’s whole exposure: loans underwritten, bond posted against bond required, and unclaimed earnings. To narrow the book by aposition field as well as a loan field, filter the loanPositions view instead.
Bond
BLMs List
A bond lock module (BLM) sets how much bond a solver must post.WhitelistBlm; one with none is a plain Blm.
Bond Curve Parameters
Curves are keyed per debt token, so a single BLM prices USDC and USDT loans independently.- All BLMs
- Specific BLM
position.bondRequirement is computed once at loan open as debt × (slope × duration / 86400 + intercept) / 1e18; see Bond Mechanics.
Solver Whitelist
isWhitelisted: false after a removal, so always filter on the flag.
Enabled Bond LLTVs
The set of bond LLTVs governance permits a quote to use.Venue & Settlement
Venue Adapters
Every position sits in exactly one venue, addressed byvenueId and served by an adapter contract.
loan.venueBitmap is the set of venues the loan may move within (bit n set = venue n allowed); position.venueId is where it is right now.
Enabled Market Data
data is keccak256 of a venue-market blob; hash the blob you hold to check whether it is enabled.
Refinance & Rebase State
Refinancing moves a position between venues, re-snapshotting the venue indices and the market blob.position.data is the raw blob for the current venue (0x when the venue takes no parameters), the pre-image whose hash appears in marketDatas.
Protocol Configuration
Owner, Fee & Fee Recipient
One singleton row per chain.config.fee is the live protocol fee; loan.fee is the value snapshotted when that loan was opened. On Ethereum mainnet owner is a Timelock with a 48-hour delay; see Governance and permissions and, for the changes scheduled through it, Timelock events.
Authorization
Borrowers can authorize a manager to act on their positions.isAuthorized: false after revocation, so filter on the flag.
Claimable Balances
Credited earnings (solver interest, protocol fees, collateral surplus) that have not yet been claimed.(chainId, token, account); claims decrement rather than delete, so a zero amount means fully claimed.
Timelock events
On Ethereum mainnet every owner change goes through the Timelock: the Safe schedules a call and, at least 48 hours later, executes it, unless it cancels it first.timelockEvents records each of those steps, so you can list the changes that are scheduled and see whether each is waiting, ready, executed or cancelled.
opId to list every Timelock event on the chain. opId is the operation id the Timelock emits for a scheduled call. The entity is append-only and keyed by (chainId, blockNumber, logIndex), so ordering on blockNumber and then logIndex gives the events in chain order.
The position fields are
chainId, blockNumber, logIndex, timestamp and transactionHash. A field that a kind does not carry reads null. target, value and data describe the call the Timelock makes, so decode data with the ABI of target. delay is the delay in seconds that applied when the call was scheduled (172800 is 48 hours).
The API stores the events as they were emitted, not a state. To derive the state of an operation, take its latest row, ignoring CallSalt:
CallScheduled: waiting untiltimestamp + delay(both in seconds), ready from then on.CallExecuted: done.Cancelled: cancelled.
opId, so read the latest row rather than stopping at the first Cancelled. The entity has no relations, and rows exist for Ethereum mainnet only. The SDK exports the Timelock address and ABI; see Addresses & registries.
Token Metadata
Token metadata is resolved off-chain for every token the protocol references. USD prices are sourced from DefiLlama.Token List
UNKNOWN placeholders rather than omitted.
Prices
priceUsd is refreshed every 5 minutes, is nullable, and is a Float; parse it as a number, not a BigInt.
Token Relations
Any token address field expands in place, which removes the second round trip.{ address } if you need the hex.
Historical Data
Every entity above reflects the latest indexed block. History comes from two append-only entities:positionEvents, the position after each IRIS event that changed it, and marketSnapshots, the venue indices of each market over time. Together they rebuild a pod’s fixed rate, floating rate and solver net over time without a row per pod per block.
Position events
positionEvents carries one row per IRIS event that writes a position: the full position row as it stood right after that event, plus where the event landed. Rows are keyed by (chainId, pod, blockNumber, logIndex), so ordering on blockNumber and then logIndex gives a pod’s events in chain order.
Repay, Liquidate, LiquidateBond and Escape close the position, so their rows read zero legs. The previous row’s legs accrued to the closing event give the legs as they stood just before it, not what was settled. A Repay before maturity also settles the fixed interest still due from the closing timestamp to maturity, since the fixed rate is charged for the full term (see Managing positions): the settled fixed leg is the previous row’s fixedLeg accrued to maturity, and the solver net settled on that repay is that amount minus the floating leg accrued to the closing event. A venue liquidation has no row of its own: it shows up in the pod’s history only once the next Rebase lands.
Market snapshots
marketSnapshots records each market’s venue indices at regular block intervals, starting from the block IRIS was deployed. A market is sampled once any loan has used it, and keeps being sampled after that loan resolves. It is sampled every 300 blocks (about an hour). A block at which a market’s index read fails has no row for that market.
(chainId, venueId, collateralToken, debtToken, data), the same values the position carries. Match all five, since data alone does not identify the token pair on every venue.
Rebuilding a pod’s history
Between two of a pod’s events, its legs follow from the event row and the market’s indices, with no further reads:- Floating leg.
debt + floatingLeggrows with the market’sdebtIndex: at a later snapshot it equals the event’sdebt + floatingLegtimesdebtIndex(snapshot) / debtIndex(event). - Fixed leg.
fixedLeggrows linearly from the event’s value at the loan’sfixedRateondebt, per year sincelastUpdate, plusoverdueRatepast maturity. - Floating rate. The change in
debtIndexbetween two snapshots of the same market. - Solver net.
fixedLeg - floatingLeg.
Refinance switches venueId and data. The SDK’s accrueLegs performs the same leg accrual for a single timestamp.
Neither entity has relations: read loan and position in a second query keyed by pod.
Paging, Ordering & Filtering
Every plural query accepts the same arguments:where, orderBy, orderDirection, limit, and cursor paging via after / before with pageInfo. The one exception is the loanPositions view, which takes offset in place of the cursor arguments; see Loan and position in one filter.
AND and OR take lists of filters and nest:
limit above the 1000 cap fails with a masked INTERNAL_SERVER_ERROR (“Unexpected error.”); where cannot traverse relations, so cross-entity conditions are a second query plus a client-side join, except for loan and position, which the loanPositions view already joins; prefer cursors over offset for full scans, since offset can skip or repeat rows if a write lands mid-scan.
