> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yield.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

> Markets, positions, actions and the action lifecycle: the model behind every Borrow integration.

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](/documentation/borrow/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.

<Warning>
  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.
</Warning>

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:

| Action | Pool (Aave, SparkLend) | Isolated (Morpho Blue, Lista) |
| - | - | - |
| `supply` | Supplies an asset to the pool; earns `supplyRate`; can be enabled as collateral | Supplies the market's collateral asset; no supply yield |
| `borrow` | Borrows against supplied collateral | Borrows against supplied collateral |
| `repay` | Full or partial; `repayAll: true` closes the debt | Full or partial; `repayAll: true` closes the debt |
| `withdraw` | Withdraws a supplied asset | Withdraws supplied collateral |
| `enableCollateral` / `disableCollateral` | Toggles whether a supplied asset counts as collateral | Not applicable |
| `supplyAndBorrow` | Not applicable | Morpho Blue only, and only when the project has a BlueBundle fee configuration |

`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.

<Note>
  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.
</Note>

## 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`.

<Warning>
  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.
</Warning>

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](/api-reference/borrow/objects#action-statuses) and [Transaction statuses](/api-reference/borrow/objects#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](/api-reference/borrow/objects#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

<Columns cols={2}>
  <Card title="Execute a Borrow action" icon="arrow-right-to-bracket" href="/documentation/get-started/quickstart#borrow-api">
    Find a market, request an action, sign and submit, and check the position.
  </Card>

  <Card title="Coverage" icon="table" href="/documentation/borrow/coverage">
    The integrations, market types, and networks behind these markets.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.