Debt swap (simulate)
POST/v1/actions/loop/debt-swap
Swap debt between borrow positions and simulate post-trade state. Same parameters as GET. Optionally send a JSON body with current portfolio state (balanceData, aprData, positions) to receive projected post-trade metrics in the simulation field — if omitted, the API fetches balances on-chain automatically. Use the data returned by the user-positions endpoint directly — always include positions for accurate health-factor and borrow-capacity projections.
Plain-text reference — POST /v1/actions/loop/debt-swap
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
route | query | auto, bundler3, native, composer, proxy | no | Which assembly to use, for lenders that have more than one. Morpho Blue only today. |
- (omitted) —
auto: prefer the protocol’s own tooling and fall back to the composer for anything it cannot express (a cross-market pair, a margin paid in a foreign asset, anEXACT_OUTPUTclose, a chain with no bundler3 or no swap adapter). bundler3/native— force Morpho’s bundler3. A request it cannot serve becomes an ERROR instead of silently falling back, which is what makes the route testable.composer/proxy— force the 1delta composer.
The default matters: the bundler3 route asks for setAuthorization(GeneralAdapter1),
Morpho’s own audited adapter, where the composer route asks for a standing grant on ours. |
| marketUidIn | query | string | yes | Market identifier for input side (lender:chainId:address). |
| marketUidOut | query | string | yes | Market identifier for output side (lender:chainId:address). |
| slippage | query | number | yes | Slippage tolerance (basis points) |
| account | query | string | no | Account address. Include to build transaction, omit for quote-only. |
| amount | query | string | yes | Amount in wei |
| tradeType | query | 0, 1 | no | Trade type |
| irModeIn | query | 0, 1, 2 | no | Interest rate mode for repaid debt |
| irModeOut | query | 0, 1, 2 | no | Interest rate mode for new debt |
| usePendleMintRedeem | query | boolean | no | Use Pendle mint/redeem |
| isAll | query | boolean | no | Repay full debt |
| accountId | query | string | no | Account ID (Init Capital, Euler V2, Dolomite). Dolomite: a uint256 account number, or iso:<marketId>:<n> for a position inside an isolation-mode vault (dGM, dsavETH, dGMX …); borrow positions on those need n >= 100, account 0 is the supply-only vault balance. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
balanceData | object | yes | Aggregated balance data for a sub-account. |
balanceData.deposits | number | no | Total deposits in USD |
balanceData.debt | number | no | Total debt in USD |
balanceData.adjustedDebt | number | no | Debt adjusted for borrow factors |
balanceData.collateral | number | no | Collateral value in USD |
balanceData.collateralAllActive | number | no | Collateral if all assets were enabled |
balanceData.borrowDiscountedCollateral | number | no | Collateral discounted by borrow factors |
balanceData.borrowDiscountedCollateralAllActive | number | no | Discounted collateral if all enabled |
balanceData.nav | number | no | Net asset value (deposits - debt) |
balanceData.deposits24h | number | no | Deposits 24h ago (for change calculation) |
balanceData.debt24h | number | no | Debt 24h ago |
balanceData.nav24h | number | no | NAV 24h ago |
balanceData.rewards | object[] | no | Pending reward token claims. Each entry represents a single reward program. |
balanceData.rewards[].asset | string | no | Reward token contract address |
balanceData.rewards[].totalRewards | number | no | Total accumulated rewards (token units) |
balanceData.rewards[].claimableRewards | number | no | Immediately claimable rewards (token units) |
aprData | object | yes | APR breakdown for a sub-account. |
aprData.apr | number | no | Net APR (deposit - borrow) |
aprData.depositApr | number | no | Weighted deposit APR |
aprData.borrowApr | number | no | Weighted borrow APR |
aprData.rewardApr | number | no | Total reward APR |
aprData.rewardDepositApr | number | no | Reward APR on deposits |
aprData.rewardBorrowApr | number | no | Reward APR on borrows |
aprData.intrinsicApr | number | no | Intrinsic yield APR (e.g., stETH staking) |
aprData.intrinsicDepositApr | number | no | Intrinsic yield APR portion from deposits |
aprData.intrinsicBorrowApr | number | no | Intrinsic yield APR portion from borrows |
aprData.rewards | object | no | Per-reward-token APR breakdown. Keys are reward token addresses. |
modeId | string | no | Mode/config key from userConfig.selectedMode (defaults to "0") |
positions | object[] | no | Current lending positions from the matching sub-account's positions array. The full LendingPosition objects returned by user-positions are accepted — only the fields in SimulationPosition are used. Always include this for accurate health-factor and borrow-capacity projections. |
positions[].marketUid | string | yes | Unique market identifier (format: {lender}:{chainId}:{address}) |
positions[].depositsUSD | number | yes | Deposit amount in USD |
positions[].debtUSD | number | yes | Variable debt in USD |
positions[].debtStableUSD | number | yes | Stable debt in USD |
positions[].collateralEnabled | boolean | yes | Whether this asset is enabled as collateral |
Response 200
| Field | Type | Description |
|---|---|---|
success | True | |
data | object | Quotes and simulation results |
data.lender | string | Protocol identifier. See the LenderId schema. |
data.quotes | object[] | Candidate routes, best output first. Execute exactly one. |
data.quotes[].deltas | object | |
data.quotes[].deltas.aggregator | string | Aggregator source |
data.quotes[].deltas.tradeInput | number | Trade input amount |
data.quotes[].deltas.tradeOutput | number | Trade output amount |
data.quotes[].deltas.deltas | object | Balance deltas |
data.quotes[].rateImpact | object[] | Projected interest-rate impact per market for THIS quote (its own trade amounts). Omitted if IRM data is unavailable. |
data.quotes[].rateImpact[].marketUid | string | Market identifier (format: lender:chainId:address) |
data.quotes[].rateImpact[].utilization | object | A current/projected pair for a single rate metric. |
data.quotes[].rateImpact[].borrowRate | object | A current/projected pair for a single rate metric. |
data.quotes[].rateImpact[].depositRate | object | A current/projected pair for a single rate metric. |
data.quotes[].rateImpact[].intrinsicYield | number | The asset's own yield in percent (LST staking yield, RWA NAV growth, a Gearbox quota rate as a negative), size-invariant, ADDED to both sides: earned on a deposit, forgone on a borrow. Absent when the lender meta was not readable when the response was built — never defaulted to 0 in that case. |
data.quotes[].rateImpact[].depositRewardApr | number | Sum of reward-stream APRs (%) on the deposit side. Absent with intrinsicYield. |
data.quotes[].rateImpact[].borrowRewardApr | number | Sum of reward-stream APRs (%) rebated on the borrow side. Absent with intrinsicYield. |
data.quotes[].rateImpact[].effectiveDepositRate | object | A current/projected pair for a single rate metric. |
data.quotes[].rateImpact[].effectiveBorrowRate | object | A current/projected pair for a single rate metric. |
data.quotes[].rateImpact[].flat | boolean | True when the market has no utilization curve to shift (Morpho Blue collateral, a fixed-rate broker): current === projected, taken from the published rates, and utilization is NaN. Present so the leg is not silently missing from a position preview. |
data.quotes[].netApr | object | The trade's carry at post-trade rates — the position net APR. annualUsd is the change in yearly carry the trade causes (deposit/withdraw legs earn, borrow/repay legs cost); aprPct puts it on the net equity the trade moves (the margin on an open) and is null when that equity is not positive (a pure leverage step, a swap). The bare figures exclude rewards; *Total include them. |
data.quotes[].netApr.annualUsd | number | |
data.quotes[].netApr.annualUsdTotal | number | |
data.quotes[].netApr.equityUsd | number | |
data.quotes[].netApr.aprPct | number | |
data.quotes[].netApr.aprPctTotal | number | |
data.quotes[].netApr.legs | object[] | |
data.quotes[].economics | object | THIS route's trade economics — TradeEconomics on an open, CloseEconomics on a close. Always present once the route has deltas; every unavailable input is a null + a note. |
data.quotes[].economics.notionalUsd | object | The position this route creates, at the oracle. equity is the margin the user brings (0 on a pure leverage step). |
data.quotes[].economics.entryCostUsd | object | Day-0 cost of getting in. slippage = swap input at the oracle − swap output at the oracle (floored at 0; slippageBp keeps the sign). gas is null when it could not be priced. |
data.quotes[].economics.slippageBp | number | Signed swap-vs-oracle, BP of the swap input. Negative = the route costs money. |
data.quotes[].economics.entryCostBp | number | entryCostUsd.total over the DEBT notional, BP. |
data.quotes[].economics.fees | object[] | |
data.quotes[].economics.carryPerDayUsd | object | The trade's carry per day at PROJECTED rates — what it earns after its own borrow has moved the pool. total counts incentives, base does not. With an account, the repricing of the existing book is netted out. |
data.quotes[].economics.carryBasis | projected, sticker, none | |
data.quotes[].economics.breakEvenDays | object | entryCostUsd.total / carryPerDayUsd. Null when the carry is not positive (never pays for itself — see notes) or unknown. |
data.quotes[].economics.roundTripDays | object | (entry + exit cost) / carry. closeQuoted says whether the exit was PRICED (a real close quote) or ASSUMED symmetric to the entry (the default today). Null on a debt that cannot be repaid early (Midnight): the round trip is at maturity, not before. |
data.quotes[].economics.horizonDays | number | Days until the trade's clock runs out. Null = perpetual. |
data.quotes[].economics.horizon | object | |
data.quotes[].economics.breaksEvenBeforeHorizon | boolean |
Request
Responses
- 200
- 400
- 429
- 500
- 502
Quote or full build with simulation
Validation error
Rate limited. Unauthenticated callers share a per-IP budget; send an x-api-key header to lift it. Retry with exponential backoff.
Unexpected server error. Safe to retry with backoff.
An upstream data source or protocol origin failed (error.code is ORIGIN_FAILED). error.details carries the per-origin status. This is also what a missing or malformed required parameter currently returns, rather than a 400.