Iris Core

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 the Ethereum mainnet staging fork (VNet, chainId: 9991); an integration moves to another network by changing the chainId.
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.

All Loans
By Borrower
By Solver
Specific Loan

query {
  loans(limit: 20, orderBy: "maturity", orderDirection: "desc") {
    totalCount
    items {
      chainId
      pod
      borrower
      solver
      fixedRate
      maturity
      collateralToken { symbol decimals }
      debtToken { symbol decimals }
    }
    pageInfo { hasNextPage endCursor }
  }
}

query {
  loans(where: { borrower: "0xaacce4ec50328120ef3899a978e87fca6b8bbe84" }, limit: 20) {
    totalCount
    items {
      pod
      solver
      fixedRate
      maturity
      duration
      collateralToken { symbol }
      debtToken { symbol }
    }
  }
}

query {
  loans(where: { solver: "0xe05fcc23807536bee418f142d19fa0d21bb0cff7" }, limit: 20) {
    totalCount
    items {
      pod
      borrower
      fixedRate
      overdueRate
      bondLltv
      maturity
    }
  }
}

query {
  loan(chainId: 9991, pod: "0x57704b581a00f25c00fa9b44934763958387116d") {
    borrower
    solver
    venueBitmap
    maturity
    duration
    overduePeriod
    fixedRate
    overdueRate
    bondLltv
    fee
    collateralToken { address symbol decimals }
    debtToken { address symbol decimals }
  }
}

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.

query SolverExposure($solver: String!) {
  loanPositions(
    where: { chainId: 9991, solver: $solver, bondRequirement_gt: "0" }
    orderBy: "pod"
    orderDirection: "asc"
    limit: 50
  ) {
    totalCount
    items {
      pod
      borrower
      debt
      bond
      bondRequirement
      maturity
      debtToken
    }
    pageInfo { hasNextPage hasPreviousPage }
  }
}

{ "solver": "0xce9a7244c22680ca9eed709cf36c96b6fc13c27c" }

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.

All Positions
Specific Position

query {
  positions(limit: 20, orderBy: "debt", orderDirection: "desc") {
    totalCount
    items {
      pod
      collateral
      debt
      bond
      bondRequirement
      lastUpdate
      venueId
      loan {
        maturity
        overduePeriod
        collateralToken { symbol decimals priceUsd }
        debtToken { symbol decimals priceUsd }
      }
    }
  }
}

query {
  position(chainId: 9991, pod: "0x57704b581a00f25c00fa9b44934763958387116d") {
    collateral
    debt
    bond
    bondRequirement
    collateralIndex
    debtIndex
    fixedLeg
    floatingLeg
    surplus
    lastUpdate
    venueId
    data
  }
}

bond and bondRequirement are in the debt token’s decimals, collateral in the collateral token’s; a closed loan keeps its row with debt: "0".

Fixed vs Floating Legs

query {
  positions(limit: 20) {
    items {
      pod
      debt
      fixedLeg
      floatingLeg
      surplus
      lastUpdate
      loan { fixedRate overdueRate maturity debtToken { symbol decimals } }
    }
  }
}

Field	Meaning
`fixedLeg`	Fixed interest accrued and owed by the borrower, in debt-token units
`floatingLeg`	Venue interest accrued against the position over the same window
`surplus`	Collateral yield accrued to the solver
`lastUpdate`	Timestamp of the last accrual, i.e. how stale the legs are

Legs are as of lastUpdate, not as of now.

Bond Health

query {
  positions(where: { bondRequirement_gt: "0" }, limit: 50) {
    items {
      pod
      bond
      bondRequirement
      fixedLeg
      floatingLeg
      loan { solver bondLltv debtToken { symbol decimals } }
    }
  }
}

A bond is unhealthy when bond < bondRequirement, or when ceil((floatingLeg - fixedLeg) × 1e18 / bond) exceeds bondLltv. 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 entity exists so a keeper can filter and sort liquidatability server-side instead of pulling every position and recomputing it client-side.

query {
  positionHealths(
    where: { chainId: 9991, bondHealthFactor_lte: 1.05 }
    orderBy: "bondHealthFactor"
    orderDirection: "asc"
    limit: 50
  ) {
    totalCount
    items { pod liquidatableAt bondHealthFactor venueLiquidated updatedAt }
    pageInfo { hasNextPage endCursor }
  }
}

Field	Meaning
`liquidatableAt`	`maturity + overduePeriod + 1`, the first second the loan is liquidatable for being overdue
`bondHealthFactor`	`bondLltv / drawdown` as a `Float`; below `1` the bond is liquidatable, `null` when there is no drawdown
`venueLiquidated`	`true` once the venue has liquidated the pod’s position, until IRIS next rebases it
`updatedAt`	Block timestamp of the last poll (or of the loan opening, before the first poll), i.e. how stale `bondHealthFactor` is

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 does not cover the whole bond check. bondHealthFactor only compares drawdown to bondLltv. A bond is also unhealthy when bond < bondRequirement, which is a filter on loanPositions.
venueLiquidated is over-inclusive. It turns true when Morpho Blue emits Liquidate or Aave V3 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 closes. 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 debt, maturity, and overduePeriod.

query {
  loans(limit: 50) {
    items {
      pod
      maturity
      overduePeriod
      position { debt }
    }
  }
}

With now in unix seconds:

Status	Condition
`closed`	`debt == 0`
`active`	`debt > 0` and `now <= maturity`
`overdue`	`debt > 0` and `maturity < now <= maturity + overduePeriod`
`liquidatable`	`debt > 0` and `now > maturity + overduePeriod`

Of these, closed is a filter on debt, and the liquidatable set is positionHealths(where: { liquidatableAt_lte: now }), whose rows are open by construction. For the rest, fetch the live set with positions(where: { debt_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.

query BorrowerPositions($borrower: String!) {
  loans(where: { borrower: $borrower }, orderBy: "maturity", orderDirection: "asc", limit: 100) {
    totalCount
    items {
      pod
      solver
      fixedRate
      overdueRate
      maturity
      overduePeriod
      collateralToken { symbol decimals priceUsd }
      debtToken { symbol decimals priceUsd }
      position {
        collateral
        debt
        fixedLeg
        lastUpdate
        venueId
        venueAdapter { adapter }
      }
    }
  }
}

{ "borrower": "0xaacce4ec50328120ef3899a978e87fca6b8bbe84" }

Borrower Account Overview

Loans, claimable balances, and delegated managers in one request.

query BorrowerOverview($account: String!) {
  loans(where: { borrower: $account }, limit: 100) {
    totalCount
    items { pod maturity overduePeriod position { debt collateral } }
  }
  claimables(where: { account: $account }) {
    items { amount token { symbol decimals priceUsd } }
  }
  authorizations(where: { authorizer: $account, isAuthorized: true }) {
    items { authorized }
  }
}

{ "account": "0xaacce4ec50328120ef3899a978e87fca6b8bbe84" }

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.

query SolverBook($solver: String!) {
  loans(where: { solver: $solver }, orderBy: "maturity", orderDirection: "asc", limit: 100) {
    totalCount
    items {
      pod
      borrower
      fixedRate
      overdueRate
      bondLltv
      maturity
      overduePeriod
      debtToken { symbol decimals priceUsd }
      position {
        debt
        bond
        bondRequirement
        fixedLeg
        floatingLeg
        surplus
        lastUpdate
      }
    }
  }
  claimables(where: { account: $solver }) {
    items { amount token { symbol decimals priceUsd } }
  }
}

{ "solver": "0xe05fcc23807536bee418f142d19fa0d21bb0cff7" }

Bond

BLMs List

A bond lock module (BLM) sets how much bond a solver must post.

query {
  blms {
    items {
      chainId
      address
      params { totalCount }
      whitelist { totalCount }
    }
  }
}

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.

All BLMs
Specific BLM

query {
  blmParamss(limit: 50) {
    items {
      slope
      intercept
      blm { address }
      token { address symbol decimals }
    }
  }
}

query {
  blm(chainId: 9991, address: "0xe0ae439c391d8dcf870a3045f09fe901fe8ef07b") {
    address
    params {
      items {
        slope
        intercept
        token { symbol decimals }
      }
    }
  }
}

position.bondRequirement is computed once at loan open as debt × (slope × duration / 86400 + intercept) / 1e18; see Bond Mechanics.

Solver Whitelist

query {
  whitelistEntrys(where: { isWhitelisted: true }, limit: 100) {
    totalCount
    items {
      account
      isWhitelisted
      blm { address }
    }
  }
}

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.

query {
  bondLltvs {
    items { chainId lltv }
  }
}

Venue & Settlement

Venue Adapters

Every position sits in exactly one venue, addressed by venueId and served by an adapter contract.

query {
  venueAdapters {
    items {
      venueId
      adapter
      positions(limit: 5, orderBy: "lastUpdate", orderDirection: "desc") {
        totalCount
        items { pod debt lastUpdate }
      }
    }
  }
}

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

query {
  marketDatas {
    items { chainId 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.

query {
  positions(orderBy: "lastUpdate", orderDirection: "desc", limit: 20) {
    items {
      pod
      venueId
      collateralIndex
      debtIndex
      data
      lastUpdate
      venueAdapter { adapter }
      loan { venueBitmap }
    }
  }
}

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.

query {
  config(chainId: 9991) {
    owner
    feeRecipient
    fee
    venueAdapters { items { venueId adapter } }
    blms { items { address } }
    bondLltvs { items { lltv } }
    marketData { totalCount }
  }
}

config.fee is the live protocol fee; loan.fee is the value snapshotted when that loan was opened.

Authorization

Borrowers can authorize a manager to act on their positions.

query {
  authorizations(where: { isAuthorized: true }, limit: 100) {
    items { authorizer authorized isAuthorized }
  }
}

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.

query {
  claimables(where: { account: "0xe05fcc23807536bee418f142d19fa0d21bb0cff7" }) {
    totalCount
    items {
      amount
      token { symbol decimals priceUsd }
    }
  }
}

One row per (chainId, token, account); claims decrement rather than delete, so a zero amount means fully claimed.

Token Metadata

Token metadata is resolved off-chain for every token the protocol references. USD prices are sourced from DefiLlama.

Token List

query {
  tokens(orderBy: "symbol", orderDirection: "asc", limit: 100) {
    totalCount
    items {
      chainId
      address
      name
      symbol
      decimals
      logoURI
      priceUsd
    }
  }
}

Tokens that don’t answer a metadata call are stored with UNKNOWN placeholders rather than omitted.

Prices

query {
  tokens(orderBy: "priceUsd", orderDirection: "desc", limit: 10) {
    items { symbol decimals priceUsd }
  }
}

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.

query {
  loans(limit: 5) {
    items {
      pod
      collateralToken { symbol decimals priceUsd logoURI }
      debtToken { symbol decimals priceUsd logoURI }
      position { collateral debt }
    }
  }
}

The relation replaces the raw string, so request { address } if you need the hex.

Historical Data

The API serves current state only: every row reflects the latest indexed block, with no event log, snapshot table, or timeseries. For now, read the contract event logs directly, or index them yourself; historical timeseries data will be added to the API in a future release.

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.

query {
  loans(
    where: {
      debtToken: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      fixedRate_gte: "70000000000000000"
    }
    orderBy: "fixedRate"
    orderDirection: "desc"
    limit: 25
  ) {
    totalCount
    items { pod fixedRate maturity debtToken { symbol } }
    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
  }
}

Each column exposes suffixed operators, combined with AND by default:

Suffix	Applies to	Example
(none), `_not`	all	`borrower: "0x…"`
`_in`, `_not_in`	all	`chainId_in: [1, 9991]`
`_gt`, `_gte`, `_lt`, `_lte`	numeric	`maturity_gt: "1785220778"`
`_contains`, `_not_contains`	strings	`pod_contains: "abc"`
`_starts_with`, `_ends_with`	strings	`solver_starts_with: "0xe05"`
`_not_starts_with`, `_not_ends_with`	strings	`pod_not_starts_with: "0x00"`

AND and OR take lists of filters and nest:

query {
  loans(
    where: {
      OR: [
        { AND: [{ debtToken: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" }, { fixedRate_gt: "80000000000000000" }] }
        { solver: "0xe05fcc23807536bee418f142d19fa0d21bb0cff7" }
      ]
    }
    limit: 25
  ) {
    totalCount
    items { pod solver fixedRate debtToken { symbol } }
  }
}

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.

Solver Economics & Lifecycle

Integration & Development

Smart Contracts Reference

How to query Iris Core data with the API?

Discovery and Listing

Loans List

Loan and position in one filter

Position Metrics

Collateral, Debt & Bond

Fixed vs Floating Legs

Bond Health

Liquidatability estimates

Loan Status

Position Tracking

Borrower All Loans Position

Borrower Account Overview

Solver Book

Bond

BLMs List

Bond Curve Parameters

Solver Whitelist

Enabled Bond LLTVs

Venue & Settlement

Venue Adapters

Enabled Market Data

Refinance & Rebase State

Protocol Configuration

Owner, Fee & Fee Recipient

Authorization

Claimable Balances

Token Metadata

Token List

Prices

Token Relations

Historical Data

Paging, Ordering & Filtering

​How to query Iris Core data with the API?

​Discovery and Listing

​Loans List

​Loan and position in one filter

​Position Metrics

​Collateral, Debt & Bond

​Fixed vs Floating Legs

​Bond Health

​Liquidatability estimates

​Loan Status

​Position Tracking

​Borrower All Loans Position

​Borrower Account Overview

​Solver Book

​Bond

​BLMs List

​Bond Curve Parameters

​Solver Whitelist

​Enabled Bond LLTVs

​Venue & Settlement

​Venue Adapters

​Enabled Market Data

​Refinance & Rebase State

​Protocol Configuration

​Owner, Fee & Fee Recipient

​Authorization

​Claimable Balances

​Token Metadata

​Token List

​Prices

​Token Relations

​Historical Data

​Paging, Ordering & Filtering

How to query Iris Core data with the API?

Discovery and Listing

Loans List

Loan and position in one filter

Position Metrics

Collateral, Debt & Bond

Fixed vs Floating Legs

Bond Health

Liquidatability estimates

Loan Status

Position Tracking

Borrower All Loans Position

Borrower Account Overview

Solver Book

Bond

BLMs List

Bond Curve Parameters

Solver Whitelist

Enabled Bond LLTVs

Venue & Settlement

Venue Adapters

Enabled Market Data

Refinance & Rebase State

Protocol Configuration

Owner, Fee & Fee Recipient

Authorization

Claimable Balances

Token Metadata

Token List

Prices

Token Relations

Historical Data

Paging, Ordering & Filtering