Skip to main content
The Iris SDK is a set of TypeScript packages for building on the protocol: typed entities whose math mirrors the Iris contracts, viem-based fetchers that hydrate them from the chain, and a transaction layer that turns every protocol flow (take, repay, close, supplyCollateral, withdrawCollateral, supplyBond, withdrawBond, claim, escape and refinance) into a ready-to-send transaction. The solver-side signing helpers an RFQ quote response is made of ship in the same package. @iris-credit/iris-sdk is the recommended entry point for all integrations, reads included. The other packages are the layers underneath it: reach for them directly only when iris-sdk does not cover your use case.

Installation

viem (^2) is iris-sdk’s only peer dependency; @iris-credit/core-sdk and @iris-credit/iris-ts ship as regular dependencies. Several examples import from them directly. If yours do too, declare them in your own package.json rather than relying on hoisting: isolated installs like pnpm’s don’t resolve undeclared transitive imports. @iris-credit/core-sdk in turn declares @iris-credit/iris-ts as a peer dependency, so keep your iris-ts pin inside the range your core-sdk version declares: an older iris-ts can fail at import time.
The SDK is pre-1.0 and each package is versioned independently. While packages are on 0.x, a minor bump is the breaking one, so pin exact versions and review the release notes before bumping.

Quick start

Everything hangs off one chain-scoped entity, created from an extended viem client. The namespace is stateless (no init(), no cache, no warm-up) and rides on the viem client you already own, so reads and writes share one transport, chain and account:
From the same entity, every state-changing flow returns the same pair: getRequirements() for the approvals and signatures that must come first, buildTx() for the final transaction. Building Transactions walks through the pattern.

Supported networks

Contract addresses and the enabled protocol configuration ship with the SDK. Resolve them with getChainAddresses(chainId) and getChainRegistry(chainId) rather than hardcoding.

Testing on a local mainnet fork

Test an integration on a local Anvil fork of Ethereum mainnet before sending anything to mainnet. The fork keeps chain ID 1 and every mainnet contract at its mainnet address, so getChainAddresses(ChainId.EthMainnet), getChainRegistry(ChainId.EthMainnet) and client.iris.core(1) apply to it as-is. @iris-credit/test runs the fork from Vitest. It spawns the anvil binary, so install Foundry first. forkUrl must serve state at forkBlockNumber, which for a past block means an archive node.
createViemTest returns a Vitest test whose client fixture is a viem test client on a fresh fork, signing as Anvil’s first dev account:
setup.ts
iris.test.ts
Each test gets its own Anvil process, stopped when the test ends, so no state carries over between tests. Pin forkBlockNumber to a block after Iris’s mainnet deployment so every run starts from the same state. The client also carries viem’s Anvil test actions, such as increaseTime, mine and setBalance. Outside Vitest, spawnAnvil({ forkUrl, forkBlockNumber }) from @iris-credit/test starts the same fork and returns its rpcUrl and a stopAndWait() that shuts it down.

Where to go next

Entities & Reads

The typed model behind every read, and the contract-exact math that runs offline.

Building Transactions

The getRequirements → buildTx pattern, flow by flow.

Solver Signing

Produce the signatures an RFQ quote response carries.

Iris API

Indexed loans, positions and prices over GraphQL, with no fetchers to run.