Skip to main content

Migrate position (cross-lender)

GET 

/v1/actions/loop/migrate

Move a whole debt + collateral position from one lender to another in a single flash-loan transaction, optionally converting ONE leg (collateral OR debt) via an aggregator swap.

Flow (no conversion): flash the debt → repay the source → withdraw the source collateral → deposit it to the target → borrow the debt from the target → repay the flash. Same-lender / different-market moves (e.g. Morpho market A→B, Aave V4 reserve→reserve) are supported.

Supported sources & targets: Aave V2/V3, Aave V4, Compound V3, Morpho Blue / Lista, Fluid (an existing position via NFT-custody, OR a brand-new position — see below), Gearbox V3 (existing credit account as source; a fresh credit account is opened in-callback as target), Euler V2 (accountId 0; collateral-share transfer through the call forwarder). Not supported: Dolomite (either side), Euler as a TARGET, non-Venus Compound V2 as a target, both legs converting at once, Fluid↔Fluid.

Fluid target — existing vs fresh: pass the position's NFT id in accountId to migrate INTO an existing Fluid position (delivered via the VaultFactory NFT-custody flow). Omit it (or pass 0) to open a brand-new Fluid position: the migrate emits a single dual-axis Fluid operate that supplies the withdrawn collateral, borrows the debt, and mints the new position NFT straight to you — no NFT custody, no target-side consent, and the transaction targets the composer (deltaCompose) normally.

Native ↔ wrapped-native (wrap conversion): a native debt — e.g. a Venus vBNB borrow — migrates into a target lender's wrapped-native debt market (WBNB). On-behalf borrowing cannot be delegated for the native asset, so the target MUST be the wrapped form; a native TARGET debt is rejected. The builder flashes the wrapped form, unwraps it to repay the native source, and borrows the wrapped form on the target — no aggregator needed. Compound V2 / Venus can be a migration source but never a target (no borrow delegation). The collateral leg wraps BOTH ways — a native source collateral (e.g. Fluid's ETH slot) is wrapped to WETH before the target deposit, and a wrapped source collateral is unwrapped for a native-collateral target — again with no aggregator. Native collateral is only reachable as such a wrap pair; native → an unrelated ERC20 target is rejected.

Lista DAO markets: two per-market extras decide the shape. A brokered market (non-zero broker) routes its debt leg through the fixed-term broker — pass loanId when it is the SOURCE (which loan to repay) and termId when it is the TARGET (which term to open); the target has no default because the broker's flexible borrow has no on-behalf variant. A market with a collateralProvider (e.g. the slisBNB markets) routes its collateral leg through that provider, which exposes no position() getter — so a provider-gated SOURCE cannot use the withdraw-all sentinel and is sized from your live collateral balance instead (read server-side; pass collateralAmount to override).

Asset conversion (swap leg): ONE leg may change asset via an aggregator swap — either the collateral (marketUidTargetCollateral uses a different underlying) or the debt (marketUidTargetDebt), not both. The route fetches the aggregator quote server-side and bakes the trade into the flash callback. A collateral swap is EXACT_INPUT of the withdrawn collateral → provide a concrete collateralAmount (or collateralAmountHint) so the swap input lines up. A debt swap is EXACT_OUTPUT (buy exactly the source debt to repay, selling the flashed target debt). Tune the swap tolerance with slippage. Euler as a source still needs an off-chain eVault share-balance read via the prepareMigrate SDK.

Omit account for quote-only (returns data.quotes with price deltas). Include account to build full transaction calldata (populates actions with alternatives, transactions, and permissions).

Setup transactions (actions.permissions): returned only for the consents actually missing, to be executed BEFORE the migrate. These vary by lender pair — e.g. the source collateral withdrawal approval; Aave V4 Giver/Taker/Config Position-Manager authorizations + per-reserve borrow allowance + collateral-enable grant; Morpho setAuthorization; a Gearbox V3 SOURCE's setBotPermissions grant on the credit account; Euler collateral eVault share approval to the composer. Fluid legs need no separate permission (NFT custody — or, for a fresh open, the composer opening on your behalf — IS the authorization).

Delivery: the migrate transaction targets the composer (deltaCompose) normally, OR the Fluid VaultFactory.safeTransferFrom when a Fluid leg requires NFT custody — actions.transactions[0].to reflects this.

data.result (resulting position): a summary for the UI — from/to lenders with their collateral + debt assets (address/symbol/decimals/logo), the new position amounts (to.collateral.amount/amountUsd, to.debt.amount/amountUsd), netUsd, leverage, apr: { deposit, borrow, net } and healthFactor. The rates, liquidation threshold, decimals and prices behind those are resolved server-side from the target markets — the corresponding query params are overrides only. USD/symbol fields are best-effort (omitted when price/token metadata is unavailable). to.collateral.amount is present when the withdraw was sized server-side (Aave source) or passed explicitly.

data.result.economics (does the move pay for itself?): a MigrateEconomics block — the day-0 cost of the move (entryCostUsd: the converted leg's slippage vs the oracle, the target's origination fee off its term sheet, gas over the permissions + migrate bundle) against carryPerDayUsd.delta, the position's carry on the target minus its carry on the source at both venues' sticker rates, and breakEvenDays = cost over that difference (null when the move does not improve the carry). Every input that could not be read is a null with a line in notes, never a zero.

Finding a target: GET /v1/actions/loop/migrate/targets returns the ranked destinations this endpoint accepts for a given position — support matrix, native ⇄ wrapped equivalence, un-openable fixed-term books and borrow liquidity all applied server-side.

Plain-text reference — GET /v1/actions/loop/migrate

Parameters

ParameterInTypeRequiredDescription
routequeryauto, bundler3, native, composer, proxynoWhich 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, an EXACT_OUTPUT close, 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. | | marketUidSourceCollateral | query | string | yes | Source collateral market (lender:chainId:address). The position being moved FROM. | | marketUidSourceDebt | query | string | yes | Source debt market (lender:chainId:address). | | marketUidTargetCollateral | query | string | yes | Target collateral market (lender:chainId:address). The position being moved TO. May be a different lender and/or a different asset (collateral conversion). | | marketUidTargetDebt | query | string | yes | Target debt market (lender:chainId:address). May be a different lender and/or a different asset (debt conversion). | | debtAmount | query | string | yes | Live debt to migrate, in the debt asset’s wei. For a debt conversion this is the NEW-debt (flash/borrow) amount instead. The flash is sized a small buffer above this so the source repay clears in full (a residual would make the full collateral withdrawal revert). | | account | query | string | no | Account address. Include to build the transaction + permission setup; omit for a quote-only response. | | isMaxIn | query | boolean | no | Withdraw the full collateral balance from the source (default true for a same-asset move). Set false + collateralAmount for an exact-amount conversion so the swap input lines up. | | collateralAmount | query | string | no | Exact source collateral to withdraw, in wei. Required (with isMaxIn=false) for a collateral conversion so the withdrawn amount matches the swap input. | | accountId | query | string | no | Per-position id where the lender needs one: an existing Fluid NFT id (omit or 0 opens a BRAND-NEW Fluid position), Euler sub-account index (must be 0 — sub-accounts unsupported). Defaults to 0. | | loanId | query | string | no | Lista fixed-term broker SOURCE only: the loan posId to repay, or type(uint128).max for the flex/dynamic position. Required when the source debt market is brokered; ignored otherwise. The target borrow is keyed by term, not loanId. | | termId | query | integer | no | Lista fixed-term broker TARGET only: which term the migrated debt opens at. REQUIRED when the target debt market is brokered — the broker exposes no on-behalf flexible borrow, so there is no default; ignored otherwise. Mirrors the termId on /v1/actions/loop/open. | | irModeFrom | query | 0, 1, 2 | no | Aave interest mode of the source debt (repay). 2 = variable. | | irModeTo | query | 0, 1, 2 | no | Aave interest mode of the target debt (borrow). 2 = variable. | | slippage | query | string | no | Swap-leg slippage tolerance as a FRACTION (0.005 = 0.5%). Only used when a leg is converted via an aggregator swap; ignored for same-asset / wrap moves. Defaults to 0.5%.

⚠ This endpoint is the exception. Every other slippage in this API is in BASIS POINTS (50 = 0.5%) — migrate takes a fraction, which is 100× smaller for the same tolerance. Sending 50 here would ask for 5000% slippage. | | eModeTo | query | string | no | Risk-config category to read the TARGET collateral's liquidation threshold from (Aave-style e-modes publish one config per category). Defaults to 0 (no e-mode). Display only — it does not change the built transaction. | | collateralDecimals | query | integer | no | Override. Target collateral decimals. Resolved server-side; pass only to overrule the published metadata (e.g. a market whose token-list decimals are known-wrong, which would mis-scale the data.result USD values). Never affects the on-chain amounts. | | debtDecimals | query | integer | no | Override. TARGET debt decimals — the swap target’s when the debt converts, else the source’s. Resolved server-side; see collateralDecimals. | | sourceDebtDecimals | query | integer | no | Override. SOURCE debt decimals, for the from-leg display when the debt is converted. Resolved server-side; defaults to debtDecimals. | | depositApr | query | string | no | Override. Target collateral deposit APR as a FRACTION (0.05 = 5%), intrinsic yield folded in. Resolved server-side and reported as data.result.apr.deposit. | | borrowApr | query | string | no | Override. Target debt borrow APR as a FRACTION (0.05 = 5%), intrinsic yield folded in — for a fixed-term target this is the term rate, not the 0% variable rate. Resolved server-side. | | liqThreshold | query | string | no | Override. Target collateral liquidation threshold as a FRACTION (0.85 = 85%), driving data.result.healthFactor (= collateralUsd · liqThreshold / debtUsd; < 1 ⇒ liquidatable). Resolved server-side from the target market’s risk config — see eModeTo. | | collateralPriceUsd | query | string | no | Override. USD price of the TARGET collateral for the display conversion. Resolved server-side, preferring the market’s own ORACLE price (what the lender liquidates against). | | debtPriceUsd | query | string | no | Override. USD price of the TARGET debt for the display conversion. Resolved server-side; see collateralPriceUsd. |

Response 200

FieldTypeDescription
successTrue
dataobjectInformational data (quotes, simulation results, etc.)
data.lenderstringProtocol identifier
data.quotesobject[]Candidate routes, best output first. Execute exactly one.
data.quotes[].deltasobject
data.quotes[].deltas.aggregatorstringAggregator source
data.quotes[].deltas.tradeInputnumberTrade input amount
data.quotes[].deltas.tradeOutputnumberTrade output amount
data.quotes[].deltas.deltasobjectBalance deltas
data.quotes[].rateImpactobject[]Projected interest-rate impact per market for THIS quote (its own trade amounts). Omitted if IRM data is unavailable.
data.quotes[].rateImpact[].marketUidstringMarket identifier (format: lender:chainId:address)
data.quotes[].rateImpact[].utilizationobjectA current/projected pair for a single rate metric.
data.quotes[].rateImpact[].borrowRateobjectA current/projected pair for a single rate metric.
data.quotes[].rateImpact[].depositRateobjectA current/projected pair for a single rate metric.
data.quotes[].rateImpact[].intrinsicYieldnumberThe 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[].depositRewardAprnumberSum of reward-stream APRs (%) on the deposit side. Absent with intrinsicYield.
data.quotes[].rateImpact[].borrowRewardAprnumberSum of reward-stream APRs (%) rebated on the borrow side. Absent with intrinsicYield.
data.quotes[].rateImpact[].effectiveDepositRateobjectA current/projected pair for a single rate metric.
data.quotes[].rateImpact[].effectiveBorrowRateobjectA current/projected pair for a single rate metric.
data.quotes[].rateImpact[].flatbooleanTrue 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[].netAprobjectThe 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.annualUsdnumber
data.quotes[].netApr.annualUsdTotalnumber
data.quotes[].netApr.equityUsdnumber
data.quotes[].netApr.aprPctnumber
data.quotes[].netApr.aprPctTotalnumber
data.quotes[].netApr.legsobject[]
data.quotes[].economicsobjectTHIS route's trade economics — TradeEconomics on an open, CloseEconomics on a close. See the schema for the discipline.
data.quotes[].economics.notionalUsdobjectThe position this route creates, at the oracle. equity is the margin the user brings (0 on a pure leverage step).
data.quotes[].economics.entryCostUsdobjectDay-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.slippageBpnumberSigned swap-vs-oracle, BP of the swap input. Negative = the route costs money.
data.quotes[].economics.entryCostBpnumberentryCostUsd.total over the DEBT notional, BP.
data.quotes[].economics.feesobject[]
data.quotes[].economics.carryPerDayUsdobjectThe 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.carryBasisprojected, sticker, none
data.quotes[].economics.breakEvenDaysobjectentryCostUsd.total / carryPerDayUsd. Null when the carry is not positive (never pays for itself — see notes) or unknown.
data.quotes[].economics.roundTripDaysobject(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.horizonDaysnumberDays until the trade's clock runs out. Null = perpetual.
data.quotes[].economics.horizonobject
data.quotes[].economics.breaksEvenBeforeHorizonboolean

Request​

Responses​

Quote or full build response