Skip to main content

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. The loanPositions view pages by offset instead.
  • Addresses are lowercase hex, and filters are exact-match.
  • BigInt values 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, and whitelistEntrys are 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.
Loan rows are immutable: they record the quote as accepted when the loan is opened. Everything that moves lives on 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.
Four things differ from the tables the view is built from:
  • Plural only. There is no single-row loanPosition(chainId:, pod:) lookup; filter on pod instead.
  • No relations. collateralToken and debtToken are raw addresses here, not token objects, so { symbol decimals } does not resolve. Read metadata from tokens in the same request.
  • Offset paging, not cursors. after and before are not arguments on this query, and pageInfo carries hasNextPage and hasPreviousPage without cursors. Page with limit and offset.
  • orderBy is 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, with chainId filtered), or pages can skip and repeat rows.
Everything else matches the underlying tables: the same suffixed operators with 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.
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

A bond is unhealthy when its drawdown, 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:
  • bondHealthFactor is an estimate, liquidatableAt is exact. The factor is accurate as of updatedAt and drifts until the next poll, so filter with a margin above 1 and re-verify onchain before sending a transaction. liquidatableAt comes from the loan’s own terms and does not move.
  • null means no drawdown, not “unknown”: the floating leg is not above the fixed leg. Because null never satisfies a comparison, any bondHealthFactor_* filter drops those rows, which is what a keeper scan wants.
  • It is the bond liquidation check. bondHealthFactor compares drawdown to bondLltv, which is what liquidateBond checks. bondRequirement floors withdrawBond: bond below it is a filter on loanPositions for solvers who cannot withdraw.
  • venueLiquidated is over-inclusive. It turns true when Morpho Blue emits Liquidate, or the Aave V3 or SparkLend pool emits LiquidationCall, for an open loan’s pod, and back to false at the next IRIS action that accrues or rebases the position. It can stay true for a position with nothing left to recognize, so filter on venueLiquidated: true to find positions awaiting a rebase and check onchain before sending one.
  • Rows exist only while the loan is open. A row is created in the block the loan opens, with bondHealthFactor null until 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: liquidatableAt still applies, bondHealthFactor reads null there, and venueLiquidated is never set. There are no relations on this entity, so read the loan and position fields in a second query keyed by pod.
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 from bondRequirement, debt, fixedLeg, surplus, maturity, and overduePeriod.
With 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 a position 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.
A BLM with whitelist rows is a 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.
position.bondRequirement is computed once at loan open as debt × (slope × duration / 86400 + intercept) / 1e18; see Bond Mechanics.

Solver Whitelist

Rows persist with 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 by venueId 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.
Rows persist with 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.
One row per (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.
Leave out 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 until timestamp + delay (both in seconds), ready from then on.
  • CallExecuted: done.
  • Cancelled: cancelled.
A cancelled operation can be scheduled again under the same 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

Tokens that don’t answer a metadata call are stored with 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.
The relation replaces the raw string, so request { 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.
A market is identified by (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 + floatingLeg grows with the market’s debtIndex: at a later snapshot it equals the event’s debt + floatingLeg times debtIndex(snapshot) / debtIndex(event).
  • Fixed leg. fixedLeg grows linearly from the event’s value at the loan’s fixedRate on debt, per year since lastUpdate, plus overdueRate past maturity.
  • Floating rate. The change in debtIndex between two snapshots of the same market.
  • Solver net. fixedLeg - floatingLeg.
Use the pod’s latest event before a given block to know which market it was in: a 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.
Each column exposes suffixed operators, combined with AND by default: AND and OR take lists of filters and nest:
Three notes: 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.