Collateral swap (simulate)
POST/v1/actions/loop/collateral-swap
Swap collateral assets 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.
For isAll trades, include depositBalanceIn (raw underlying balance string) in the body so the withdrawal approval is sized to the actual position. This field is accepted alongside or independently of the simulation fields.
Plain-text reference — POST /v1/actions/loop/collateral-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 |
| usePendleMintRedeem | query | boolean | no | Use Pendle mint/redeem |
| isAll | query | boolean | no | Swap full collateral balance |
| 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 |
depositBalanceIn | string | no | Raw deposit balance of the input collateral asset in underlying units. Used for isAll to size the withdrawal approval correctly. |
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.