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

# Objects and enums

> Exact serialized values for Borrow integrations, market models, actions, arguments, statuses, transactions, positions and liquidations.

This page is the single reference for Borrow enums and shared objects. Endpoint pages link here. Values are shown exactly as the Borrow API serializes them. Base URL is `https://borrow.yield.xyz`; every route except `/health` needs the `x-api-key` header.

## Integrations

| `integrationId` | Protocol | Market model |
| - | - | - |
| `aave-borrow` | Aave V3 | `pool` |
| `sparklend-borrow` | SparkLend | `pool` |
| `morpho-blue-borrow` | Morpho Blue | `isolated` |
| `lista-borrow` | Lista Lending | `isolated` |

Networks per integration are in [Coverage](/documentation/borrow/coverage). The live list, with each integration's `networks` and `actions`, comes from [List integrations](/api-reference/borrow/integrations/list-integrations); do not hard-code it. The list is not filtered by project, so it can include integrations that exist only on a test network. Those are not part of mainnet support.

`IntegrationDto` fields: `id`, `providerId`, `name`, `networks[]`, `metadata` (`description`, `externalLink`, `logoURI`) and `actions[]`. Each `actions[]` entry has `id` (an [action type](#action-types)), `label` and `schema`, a JSON Schema of the `args` that action accepts on that integration.

## Market models

`MarketDto.type` is one of two values.

| `type` | Meaning | `collateralTokens[]` | Integrations |
| - | - | - | - |
| `pool` | Shared pool. Every eligible asset in the pool can be collateral. | All eligible collateral assets | `aave-borrow`, `sparklend-borrow` |
| `isolated` | One collateral asset paired with one loan asset. Risk is scoped to the market. | Exactly one entry | `morpho-blue-borrow`, `lista-borrow` |

`MarketDto` fields:

| Field | Notes |
| - | - |
| `id`, `integrationId`, `network`, `type`, `poolAddress` | `id` is the `marketId` you pass to actions. |
| `loanToken` | `TokenDto`: `address` (optional), `symbol`, `name`, `decimals`, `logoURI` (optional). |
| `collateralTokens[]` | Each entry: `token`, `priceUsd`, `maxLtv`, `liquidationThreshold`, `liquidationPenalty`, `supplyRate`. |
| `borrowRate`, `utilizationRate`, `loanTokenPriceUsd` | Decimal strings. `"0.0567"` is 5.67%. |
| `totalSupply`, `totalBorrow`, `availableLiquidity` | Human-readable token units. Each has a `...Raw` twin in raw token units. |
| `isBorrowEnabled` | Boolean. |
| `minLoan` | Minimum outstanding debt in human-readable loan-token units, or `null` when the market enforces none. Set on Lista markets; `null` on the other integrations. |
| `supplyCollateralFeeBps`, `feeWrapperAddress`, `originationFeeBps`, `originationFeeWrapperAddress`, `blueBundleOriginationFeeBps` | Project-scoped fee metadata. The `...FeeBps` market fields are decimal strings; the wrapper addresses and `blueBundleOriginationFeeBps` are `null` when not configured. See [Monetization](/documentation/borrow/monetization). |

All rates, LTVs and penalties are decimal strings, not percentages.

## Action types

`action` in [Execute an action](/api-reference/borrow/actions/execute-action) and the `action` filter in [List actions](/api-reference/borrow/actions/list-actions). Declared in `BorrowActionTypes`; all seven are accepted by request validation, but each integration supports a subset (see [Availability by integration](#availability-by-integration)).

| Value | Effect |
| - | - |
| `supply` | Supply collateral. On pool markets this also earns `supplyRate`. |
| `borrow` | Borrow the loan token. Can bundle a collateral supply in the same action. |
| `repay` | Repay debt, in part or in full (`repayAll`). Can bundle a collateral withdrawal. |
| `withdraw` | Withdraw supplied collateral. |
| `enableCollateral` | Count a supplied asset toward borrowing power. Pool markets only. |
| `disableCollateral` | Stop counting a supplied asset toward borrowing power. Pool markets only. |
| `supplyAndBorrow` | Supply collateral and borrow in one bundled action. Morpho Blue only, and only when configured for the project. |

## Action arguments

`args` on `POST /v1/actions` is one flat object (`ArgumentsDto`). Only `marketId` is required by the schema; each action validates the rest. `R` means required, `O` optional, blank means not used. "Pool" is `aave-borrow` and `sparklend-borrow`; "isolated" is `morpho-blue-borrow` and `lista-borrow`.

| Action | Arguments |
| - | - |
| `supply` | `marketId` R. Collateral amount: `amount` or `amountRaw` R, or instead `borrowAmount` with `targetLtv`. `tokenAddress` R on pool markets (a collateral token of the market); not needed on isolated markets. |
| `borrow` | `marketId` R, `amount` or `amountRaw` R. `tokenAddress` O (if sent, must be the market loan token). `collateralAmount` or `collateralAmountRaw` O, with `collateralTokenAddress` R on pool markets when a collateral amount is sent. |
| `repay` | `marketId` R, one of `amount`, `amountRaw` or `repayAll: true` R. `tokenAddress` O (if sent, must be the market loan token). `collateralAmount` or `collateralAmountRaw` O, with `collateralTokenAddress` R on pool markets when a collateral amount is sent. |
| `withdraw` | `marketId` R, `amount` or `amountRaw` R. `tokenAddress` R on pool markets (a collateral token of the market); not needed on isolated markets. |
| `enableCollateral` | `marketId` R, `tokenAddress` R (a collateral token of the market). Pool markets only. |
| `disableCollateral` | `marketId` R, `tokenAddress` R (a collateral token of the market). Pool markets only. |
| `supplyAndBorrow` | `marketId` R, borrow amount `amount` or `amountRaw` R, collateral amount `collateralAmount` or `collateralAmountRaw` R. Morpho Blue only. |

Formats: `amount`, `collateralAmount` and `borrowAmount` are decimal strings in human-readable token units (`"1.5"`); `amountRaw` and `collateralAmountRaw` are integer strings in raw token units (`"1500000"`); `targetLtv` is a decimal string (`"0.1"` is 10%); addresses are `0x` plus 40 hex characters. Amounts are limited to 50 characters and must be greater than zero.

### Validation rules

All failures return `400`.

| Rule | Message |
| - | - |
| `amount` and `amountRaw` are mutually exclusive | `Provide either amount or amountRaw, not both` |
| `collateralAmount` and `collateralAmountRaw` are mutually exclusive | `Provide either collateralAmount or collateralAmountRaw, not both` |
| `repayAll` is only valid on `repay` | `repayAll is only supported for repay actions` |
| `repayAll` cannot be combined with `amount` or `amountRaw` | `Provide repayAll or amount/amountRaw, not both` |
| `repay` needs an amount or `repayAll` | `Either repayAll or amount/amountRaw must be provided` |
| `borrowAmount` and `targetLtv` only on `supply`, and only together | `borrowAmount and targetLtv are only supported for supply actions`, `borrowAmount and targetLtv must be provided together` |
| `borrowAmount`/`targetLtv` cannot be combined with `amount` or `amountRaw` | `Provide either a collateral amount (amount/amountRaw) or (borrowAmount + targetLtv), not both` |
| Amounts must be positive | `amount must be greater than zero`, and the same for `amountRaw`, `collateralAmount`, `collateralAmountRaw`, `borrowAmount`, `targetLtv` |
| `tokenAddress` must fit the action | `tokenAddress is not a valid collateral token for this market` (supply, withdraw, enable, disable) or `tokenAddress does not match market loan token` (borrow, repay) |
| `collateralTokenAddress` must be a market collateral token | `collateralTokenAddress is not a valid collateral token for this market` |
| Pool markets: a collateral amount needs its token | `collateralTokenAddress is required when collateralAmount or collateralAmountRaw is provided` |
| Unknown `integrationId` | `Integration ... not found or not supported` |
| Unknown `marketId` | `404` `Market not found` |

### Collateral bundling

Bundling is optional and applies only to `borrow` and `repay`. It adds a collateral leg to the same action instead of requiring a separate `supply` or `withdraw` call. The extra transactions come back in the same `transactions[]`, in signing order.

| Action | With `collateralAmount` or `collateralAmountRaw` | Without |
| - | - | - |
| `borrow` | Supplies that collateral first, then borrows. Pool markets return an `APPROVAL` when the allowance is short, then `SUPPLY`, then `BORROW`. | Borrow only. Assumes collateral is already supplied. |
| `repay` | Repays, then withdraws that collateral. Pool markets return `APPROVAL` when needed, `REPAY`, then `WITHDRAW`. | Repay only. Collateral stays in place. |

* **Pool markets** (`aave-borrow`, `sparklend-borrow`): `collateralTokenAddress` is required whenever a collateral amount is sent. The amount is converted using that token's decimals.
* **Isolated markets** (`morpho-blue-borrow`, `lista-borrow`): the collateral token is the market's single collateral asset, so `collateralTokenAddress` is not needed. If you send it, it must match that token.
* `withdraw`, `supply`, `enableCollateral` and `disableCollateral` do not use the collateral fields. Use `supplyAndBorrow` for a supply-and-borrow bundle.
* `borrow` and `repay` with a collateral amount are not the same as `supplyAndBorrow`. `supplyAndBorrow` is a separate action that is only listed for a project when it is configured.

### Supply by target LTV

Instead of a collateral amount, `supply` accepts `borrowAmount` (in loan-token units) with `targetLtv`. The API derives the collateral needed to borrow that amount at that LTV and supplies it. `targetLtv` must not exceed the market's max LTV, otherwise the call returns `400`. The derived collateral is returned in [`metadata.effectiveCollateralAmount`](#action-metadata). This is a preview aid: it does not borrow anything.

### `supplyAndBorrow` gating

`supplyAndBorrow` is implemented only by `morpho-blue-borrow`. It appears in that integration's `actions[]` only when the requesting project has the bundled supply-and-borrow fee configuration, which yield.xyz sets up per project. Calling it anyway returns `400`:

| Condition | Message |
| - | - |
| Any other integration | `Unknown action: supplyAndBorrow` (Aave, SparkLend) or `Unsupported Lista Lending action: supplyAndBorrow` (Lista) |
| Morpho Blue, project not configured | `BlueBundle fee configuration is required for supplyAndBorrow` |
| Morpho Blue, network not Ethereum or Base | `Morpho BlueBundlesV1 is not configured for network <network>` |
| No collateral amount | `collateralAmount or collateralAmountRaw is required for supplyAndBorrow` |
| No borrow amount | `Either amount or amountRaw must be provided for this action` |

`amount` or `amountRaw` is the net amount you receive. Where a fee applies, the debt recorded on chain is higher; the difference is reported in [action metadata](#action-metadata).

## Availability by integration

The matrix below is derived from each integration's action list and action builder. `GET /v1/integrations` remains authoritative for a given project.

| Action | `aave-borrow` | `sparklend-borrow` | `morpho-blue-borrow` | `lista-borrow` |
| - | - | - | - | - |
| `supply` | yes | yes | yes | yes |
| `borrow` | yes | yes | yes | yes |
| `repay` (`repayAll` supported) | yes | yes | yes | yes |
| `withdraw` | yes | yes | yes | yes |
| `enableCollateral` | yes | yes | no | no |
| `disableCollateral` | yes | yes | no | no |
| `supplyAndBorrow` | no | no | project-configured; Ethereum and Base only | no |

Calling an unsupported action returns `400`. Lista also enforces `minLoan`: a `borrow` that would leave debt below it, or a partial `repay` that would leave debt above zero but below it, returns `400`. Use `repayAll` to close a Lista position.

## Action metadata

`ActionDto.metadata` previews the position after the action. All values are strings unless noted.

| Field | Notes |
| - | - |
| `currentHealthFactor` | `null` when there is no debt. |
| `predictedHealthFactor` | `null` when predicted debt is zero. |
| `currentLtv`, `predictedLtv` | Decimals. |
| `liquidationThreshold` | Decimal. |
| `predictedTotalSupplyUsd`, `predictedTotalDebtUsd` | USD strings. |
| `originationFeeBps` (number), `originationFeeAmount`, `effectivePrincipalAmount` | Present only when a borrow fee wrapper applies. |
| `feeAmount`, `feeBps` (number) | Present on `supply`, and on `borrow` with a collateral leg, when a supply fee wrapper applies. `"0"` and `0` when its rate is zero. |
| `effectiveCollateralAmount` | Present only on `supply` by target LTV. |

`metadata` is optional on the object, so handle its absence. `ActionDto.rawArguments` echoes the `args` you sent.

## Action statuses

`ActionDto.status` and the `status` and `statuses` filters on [List actions](/api-reference/borrow/actions/list-actions). `statuses` accepts up to 7 values as a CSV or repeated parameter; when it is set, `status` is ignored.

| Value | Meaning |
| - | - |
| `CREATED` | Returned by `POST /v1/actions`. No transaction has been submitted yet, or the remaining transactions of the step are still unsubmitted. |
| `PROCESSING` | At least one transaction was submitted. |
| `WAITING_FOR_NEXT` | Declared for a multi-step action between steps. Current actions are single-step, so it is not returned today. |
| `SUCCESS` | Every transaction is `CONFIRMED` or `SKIPPED`. Final. |
| `FAILED` | A transaction failed on chain or the broadcast failed. Final. |
| `STALE` | A submitted transaction stayed unconfirmed for over 30 minutes. |
| `CANCELED` | Declared and final. The Borrow API does not set it today. |

Poll [Get an action](/api-reference/borrow/actions/get-action) after submission. A partly signed action returns to `CREATED` when its submitted transactions confirm and others remain.

## Transaction types

`TransactionDto.type`, in signing order within `transactions[]`.

| Value | Emitted for |
| - | - |
| `APPROVAL` | ERC-20 allowance ahead of a supply, repay or bundle. Only when the allowance is short. |
| `SUPPLY` | `supply`, and the collateral leg of `borrow`. |
| `BORROW` | `borrow`. |
| `REPAY` | `repay`. |
| `WITHDRAW` | `withdraw`, and the collateral leg of `repay`. |
| `ENABLE_COLLATERAL` | `enableCollateral`. |
| `DISABLE_COLLATERAL` | `disableCollateral`. |
| `AUTHORIZE` | Morpho Blue authorization of an operator, added ahead of a borrow that routes through one. |
| `DEAUTHORIZE` | Morpho Blue revocation of such an authorization, added when the flow or a position closure calls for it. |
| `BUNDLE` | Morpho Blue bundled transaction, used by `supplyAndBorrow` and by `borrow` where bundling applies. |
| `WRAP` | Morpho Blue wrapping of the native token before supplying it. |

Sign every returned transaction, in order, including ones you did not request. `signingFormat` is `EVM_TRANSACTION` for Borrow; the enum also declares `EIP712_TYPED_DATA`, `SOLANA_TRANSACTION` and `COSMOS_TRANSACTION`, which Borrow does not emit. For an EVM transaction `signablePayload` is a JSON string with `from`, `to`, `data`, `gasLimit` and `value`. Sign it as returned.

`hasNextStep`, `currentStep` and `totalSteps` are on `ActionDto`. Every current integration returns `hasNextStep: false` and `totalSteps: 1`. See [Step an action](/api-reference/borrow/actions/step-action).

## Transaction statuses

`TransactionDto.status` and `SubmitTransactionResponseDto.status`. The enum is shared with the other APIs; the Borrow API uses these values:

| Value | Meaning |
| - | - |
| `CREATED` | Built, not yet submitted. The only status from which a transaction can be submitted. |
| `BROADCASTED` | Submitted, either broadcast by yield.xyz or reported by you with a hash. The submit response always returns this on success. |
| `CONFIRMED` | Confirmed on chain. |
| `FAILED` | Broadcast or on-chain execution failed. |

The enum also declares `NOT_FOUND`, `BLOCKED`, `WAITING_FOR_SIGNATURE`, `SIGNED`, `PENDING` and `SKIPPED`. A Borrow transaction moves through the four values above; `SKIPPED` counts as done when deciding an action's `SUCCESS`.

## Position fields and nullability

`PositionDto` from [Get positions](/api-reference/borrow/positions/get-positions). Amounts are strings.

| Field | Level | Nullable | Notes |
| - | - | - | - |
| `totalSuppliedUsd`, `totalCollateralUsd`, `totalBorrowedUsd`, `netWorthUsd`, `currentLtv`, `netApy` | Account | No | `totalCollateralUsd` counts only assets enabled as collateral. |
| `healthFactor` | Account | Yes | `null` when there is no debt, and always `null` on isolated integrations. Above 1 is safe; below 1 is liquidatable. |
| `availableToBorrowUsd` | Account | Yes | `null` on isolated integrations, where headroom is per market. |
| `supplyBalances[]` | Market | No | `marketId`, `tokenAddress`, `tokenSymbol`, `balance`, `balanceRaw`, `balanceUsd`, `apy`, `isCollateral`, `positionState`, `pendingActions[]`. |
| `supplyBalances[].positionState` | Market | Absent on pool integrations | Present on isolated integrations. Fields: `currentLtv`, `liquidationThreshold`, `healthFactor` (`null` when the market has no debt), `availableToBorrowUsd`. |
| `debtBalances[]` | Market | No | `marketId`, `tokenAddress`, `tokenSymbol`, `balance`, `balanceRaw`, `balanceUsd`, `apy`, `pendingActions[]`. |

Read the account-level fields for `aave-borrow` and `sparklend-borrow`, and `positionState` on each supply balance for `morpho-blue-borrow` and `lista-borrow`. `pendingActions[]` entries are `{ type, label, args }`; `type` is an [action type](#action-types) and `args` is pre-filled input for `POST /v1/actions`.

## Liquidations

`LiquidationDto` from [Get liquidations](/api-reference/borrow/positions/get-liquidations). Available for `morpho-blue-borrow` only.

| Field | Notes |
| - | - |
| `id`, `integrationId`, `network`, `address`, `marketId` | `address` is the liquidated borrower. |
| `type` | `partial` or `full`, or `null` when closure could not be determined. `full` means no borrow shares remained afterwards. |
| `realizedBadDebt` | Boolean. Independent of `type`. |
| `occurredAt`, `blockNumber`, `transactionHash`, `transactionLink`, `liquidator` | Event identifiers. `occurredAt` is ISO 8601. |
| `repaidDebt` | `tokenAddress`, `tokenSymbol`, `amount`, `amountRaw`, `amountUsd` (nullable), `shares`. |
| `seizedCollateral` | `tokenAddress`, `tokenSymbol`, `amount`, `amountRaw`, `amountUsd` (nullable). |
| `badDebt` | `amount`, `amountRaw`, `amountUsd` (nullable), `shares`. Non-zero only when bad debt was realized. |
| `lif` | The market's liquidation incentive factor. |

`amountUsd` values are priced at the liquidation block and are `null` when no historical price exists.


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