Skip to main content
Every Borrow integration shares the same three objects: a market you supply collateral to and borrow from, a position that tracks the user’s account across markets, and an action that moves a position from one state to another.

​
Markets

A market is one loan asset paired with its accepted collateral, on one network, behind one integration. Its type is either pool, a shared pool where every eligible asset can be collateral (Aave, SparkLend), or isolated, a single collateral and loan asset pair (Morpho Blue, Lista). Each market has a loanToken and one or more collateralTokens. Every collateral token carries maxLtv (the maximum loan-to-value ratio it supports), liquidationThreshold (the LTV at which the position becomes liquidatable), liquidationPenalty, and supplyRate (the rate the collateral earns while deposited). The market itself carries borrowRate, availableLiquidity, utilizationRate, isBorrowEnabled, and minLoan (the minimum outstanding debt, set on Lista markets; null where no minimum applies). Rates are decimals: "0.0567" means 5.67%. Discover markets with GET /v1/markets, scoped to your project by default (scope=enabled); pass scope=all for every market the integration exposes. See Coverage for the integrations and networks behind these markets.

​
Positions

GET /v1/positions returns one account’s state for an integrationId, network, and address: total supplied, collateral, and borrowed value in USD, an account-level healthFactor, and a supplyBalances/debtBalances breakdown per market. healthFactor is Σ(collateralUsd × liquidationThreshold) / totalBorrowedUsd. Above 1 the position is safe, at 1 it sits at the liquidation threshold, and below 1 it is liquidatable.
Account-level healthFactor and availableToBorrowUsd are always null for isolated-market integrations (Morpho Blue, Lista), because risk is per-market, not per-account. Read positionState.healthFactor and positionState.availableToBorrowUsd on each supplyBalances entry instead.
Each balance carries pendingActions: the actions available on it next (for example repay, withdraw, or toggle collateral), each with pre-filled args you can pass straight into POST /v1/actions. For Morpho Blue, a position that reaches full liquidation stops appearing in GET /v1/positions and shows up only in GET /v1/positions/liquidations, a paginated liquidation history for the borrower address.

​
Actions

POST /v1/actions moves a position between states. The actions available to a market come from its integration and market type: GET /v1/integrations returns the exact actions and argument schemas available to your project for each integration: treat it as authoritative over this table for a given project. An action response can include preview metadata, which is optional in the response: predictedHealthFactor and predictedLtv show the position after the action settles, alongside the currentHealthFactor and currentLtv before it. When an action needs more than one transaction (for example an approval before a supply), all of them come back together in transactions[]: sign and submit each in order.
On Lista, a market’s minLoan is the smallest debt the market allows. A borrow that would leave debt below it, or a partial repay that would leave dust below it, fails; use repayAll to close the position instead of a partial repay near the minimum.

​
Action lifecycle

An action moves through CREATED, PROCESSING and then SUCCESS or FAILED. Each of its transactions moves through CREATED, BROADCASTED and then CONFIRMED or FAILED. A single action can need several transactions, for example an APPROVAL before a SUPPLY or REPAY. They all come back together in transactions[] on the first response, in signing order, and the approval is left out when the allowance already covers the amount. You do not call /step to get the next one: every current integration returns hasNextStep: false.
Submitting does not wait for earlier transactions in the same action. If you submit SUPPLY before its APPROVAL has confirmed on-chain, it reverts for insufficient allowance. Submit one transaction, poll GET /v1/actions/{id} until that transaction is CONFIRMED, then submit the next.
While you work through the list, the action goes back to CREATED each time a submitted transaction confirms and others remain: that is the signal that the next transaction is ready to sign. Poll every 2 to 5 seconds, backing off to about 10 seconds on slow chains; the API checks the chain about every 5 seconds, so polling faster gains nothing. A transaction that stays unconfirmed for more than 30 minutes marks the action STALE. See Action statuses and Transaction statuses.

​
Sizing a supply

A supply can be sized two ways:
  • By collateral: pass amount (or amountRaw), the gross amount to deposit.
  • By target borrow: pass borrowAmount with targetLtv, and the API works out the collateral needed to borrow that amount at that LTV, returned in metadata.effectiveCollateralAmount. targetLtv must be above zero and no higher than the market’s maxLtv.
borrow and repay can also carry a collateral leg, supplying collateral before a borrow or withdrawing it after a repay in the same action. See Collateral bundling.

​
Rates and risk parameters

  • Supply rate: what supplied assets earn, on pool markets. Collateral on isolated markets earns nothing.
  • Borrow rate: what the borrower pays on debt.
  • Rates move with utilization: higher utilization means higher borrow rates and higher supply yields. All rates are decimals, so "0.0567" is 5.67%.
  • Max LTV: the most a user can borrow as a share of collateral value.
  • Liquidation threshold: the LTV at which the position can be liquidated, set above max LTV as a buffer.
  • Liquidation penalty: the bonus liquidators receive from the seized collateral.

​
Next steps

Execute a Borrow action

Find a market, request an action, sign and submit, and check the position.

Coverage

The integrations, market types, and networks behind these markets.