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. The live list, with each integration’s networks and actions, comes from 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), 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.

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

Action types

action in Execute an action and the action filter in List actions. Declared in BorrowActionTypes; all seven are accepted by request validation, but each integration supports a subset (see 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. 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.

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

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. 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 and args is pre-filled input for POST /v1/actions.

Liquidations

LiquidationDto from 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.