Skip to main content

MarginBuildResponse

Full build response (account provided). Includes transaction calldata.

lenderstringrequired

Protocol identifier

quotes object[]required

Candidate routes, best output first. Execute exactly one.

  • Array [
  • deltas object
    aggregatorstring

    Aggregator source

    tradeInputnumber

    Trade input amount

    tradeOutputnumber

    Trade output amount

    deltas object

    Balance deltas

    property name*any

    Balance deltas

    tx object

    An EVM transaction ready to sign and broadcast. Send to, data and value as-is; do not re-encode them.

    chainTypestring

    Which VM executes this step. ABSENT means evm, which is the only value any endpoint returns today — every EVM response is unchanged. A non-EVM chain would return a different shape (a serialized, PERISHABLE transaction rather than to/data/value) carrying its own chainType, so a client that wants to stay forward-compatible should branch on this field rather than assume to is present.

    Possible values: [evm]

    tostringrequired

    Target contract address

    Example: 0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2
    datastringrequired

    Encoded calldata

    Example: 0x617ba037000000000000000000000000c02aaa39b2
    valuestringrequired

    ETH value to send with the transaction

    Example: 0
    descriptionstring

    Human-readable label. For alternatives, this is the aggregator name (e.g. "Paraswap"). For transactions, describes the setup action (e.g. "Switch e-mode to 1").

    rateImpact object[]

    Projected interest-rate impact per market for THIS quote (its own trade amounts). Omitted if IRM data is unavailable.

  • Array [
  • marketUidstringrequired

    Market identifier (format: lender:chainId:address)

    Example: AAVE_V3:8453:0x4200000000000000000000000000000000000006
    utilization objectrequired

    Utilization ratio (0–1)

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    borrowRate objectrequired

    Borrow APR (%)

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    depositRate objectrequired

    Deposit/supply APR (%) paid by the POOL. On a market whose return is the asset itself (an LST, an RWA share such as nOPAL on Morpho Blue) this is 0 — read effectiveDepositRate.

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    intrinsicYieldnumber

    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.

    Example: 10.37
    depositRewardAprnumber

    Sum of reward-stream APRs (%) on the deposit side. Absent with intrinsicYield.

    borrowRewardAprnumber

    Sum of reward-stream APRs (%) rebated on the borrow side. Absent with intrinsicYield.

    effectiveDepositRate object

    depositRate + intrinsicYield (%), rewards EXCLUDED — what a deposit on this market actually earns, and the figure the pair book publishes as the effective supply APR. Absent with intrinsicYield.

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    effectiveBorrowRate object

    borrowRate + intrinsicYield (%), rewards EXCLUDED — what a borrow on this market actually costs. Absent with intrinsicYield.

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    flatboolean

    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.

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

    annualUsdnumberrequired
    annualUsdTotalnumberrequired
    equityUsdnumberrequired
    aprPctnumbernullablerequired
    aprPctTotalnumbernullablerequired
    legs object[]required
  • Array [
  • marketUidstringrequired

    Market identifier, formatted lender:chainId:address.

    sidestringrequired

    Possible values: [deposit, borrow, withdraw, repay]

    usdnumberrequired

    Absolute USD size of the leg.

    ratePctnumberrequired

    Effective PROJECTED rate (IRM + intrinsic, %) the leg is priced at; the bare IRM rate where the overlay was unavailable.

    ratePctTotalnumberrequired

    ratePct with rewards folded in (+ on an earning leg, − on a paying leg).

  • ]
  • economics object

    THIS route's trade economics — TradeEconomics on an open, CloseEconomics on a close. See the schema for the discipline.

    oneOf
    notionalUsd objectrequired

    The position this route creates, at the oracle. equity is the margin the user brings (0 on a pure leverage step).

    equitynumber
    collateralnumber
    debtnumber
    entryCostUsd objectrequired

    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.

    slippagenumber
    feesnumber
    gasnumbernullable
    totalnumber
    slippageBpnumbernullablerequired

    Signed swap-vs-oracle, BP of the swap input. Negative = the route costs money.

    entryCostBpnumbernullablerequired

    entryCostUsd.total over the DEBT notional, BP.

    fees object[]required
  • Array [
  • idstringrequired

    The term sheet's FeeTerm.id (origination, early-repay-penalty, …) or flash for the flash-loan fee.

    labelstringrequired
    whenstringrequired

    entry items sum to entryCostUsd.fees; exit items are in the round-trip exit cost.

    Possible values: [entry, exit]

    usdnumberrequired

    Priced on the notional the fee is charged on. Negative = a rebate.

    valuenumberrequired

    The published rate (read with unit).

    unitstringrequired

    percent | bps | …

    basisstringrequired

    principal | face-value | collateral | …

    mutableboolean

    Governance-mutable snapshot — re-verify before quoting it as a term.

  • ]
  • carryPerDayUsd objectnullablerequired

    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.

    totalnumber
    basenumber
    carryBasisstringrequired

    Possible values: [projected, sticker, none]

    breakEvenDays objectrequired

    entryCostUsd.total / carryPerDayUsd. Null when the carry is not positive (never pays for itself — see notes) or unknown.

    totalnumbernullable
    basenumbernullable
    roundTripDays objectrequired

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

    totalnumbernullable
    basenumbernullable
    closeQuotedboolean
    exitCostUsdnumbernullable
    horizonDaysnumbernullablerequired

    Days until the trade's clock runs out. Null = perpetual.

    horizon objectrequired
    kindstring

    Possible values: [perpetual, to-expiry, to-maturity, rolling]

    endsAtinteger

    Unix seconds.

    sourcestring
    breaksEvenBeforeHorizonbooleannullablerequired
    gas objectnullablerequired
    oneOf
    unitsnumberrequired

    Gas units over the whole bundle — outstanding permissions + main transaction.

    txCountintegerrequired
    estimatedbooleanrequired

    true when every transaction was eth_estimateGas-ed from the account; false when at least one used the typical-size table (the notes say which — the main transaction usually reverts under estimation until its permissions are granted).

    gasPriceGweinumberrequired
    nativePriceUsdnumberrequired
    usdnumberrequired
    existingExposure object

    The marginal view — what this trade does to the account it lands in. The new borrow moves the pool rate, and the debt the account ALREADY holds in that market reprices with it: an ongoing cost the one-off slippage never shows. Same on the deposit side with the opposite sign.

    debtUsdSameMarketnumberrequired

    Debt already held in the DEBT market, USD.

    depositUsdSameMarketnumberrequired

    Deposits already held in the COLLATERAL market, USD.

    rateDeltaBpnumbernullable

    Projected − current borrow rate on the debt market, BP.

    depositRateDeltaBpnumbernullable

    Projected − current deposit rate on the collateral market, BP.

    repriceCostPerDayUsdnumbernullable

    Repricing of the existing book per day (debt repriced up minus deposits repriced up). Positive = a cost. Already netted out of carryPerDayUsd.

    accountAprPrenumbernullable

    Account net APR before the trade, percent, rewards included.

    accountAprPostnumbernullable

    Account net APR after the trade at PROJECTED rates, percent.

    accountNavUsdnumbernullable
    accountNavUsdPostnumbernullable
    notesstring[]required

    Every assumption and every input that was missing, in words. Read them before showing a number.

  • ]
  • permissionTxns object[]required

    Approvals needed for this specific quote. Most integrators should use the deduplicated envelope-level actions.permissions instead.

  • Array [
  • tostringrequired

    Target contract address

    datastringrequired

    Encoded calldata

    valuestringrequired

    ETH value

    Example: 0
    descriptionstring

    Human-readable description of the approval (e.g. "Approve borrow for AAVE_V3", "Approve ERC20")

    spenderstring

    ERC-20 approve spender (x-chain permissions). Match it against the selected quote's approvalTarget — several bridges can share one spender, so do not match by description.

    typestring

    What kind of grant this is. A signatures[] offer names the type it replaces via its replaces field.

    Possible values: [ERC20, Lender]

  • ]
  • rateImpact object[]nullable

    Projected interest-rate impact per market. Single-market actions produce 1 entry; loop actions produce 2. Null if IRM data is unavailable.

  • Array [
  • marketUidstringrequired

    Market identifier (format: lender:chainId:address)

    Example: AAVE_V3:8453:0x4200000000000000000000000000000000000006
    utilization objectrequired

    Utilization ratio (0–1)

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    borrowRate objectrequired

    Borrow APR (%)

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    depositRate objectrequired

    Deposit/supply APR (%) paid by the POOL. On a market whose return is the asset itself (an LST, an RWA share such as nOPAL on Morpho Blue) this is 0 — read effectiveDepositRate.

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    intrinsicYieldnumber

    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.

    Example: 10.37
    depositRewardAprnumber

    Sum of reward-stream APRs (%) on the deposit side. Absent with intrinsicYield.

    borrowRewardAprnumber

    Sum of reward-stream APRs (%) rebated on the borrow side. Absent with intrinsicYield.

    effectiveDepositRate object

    depositRate + intrinsicYield (%), rewards EXCLUDED — what a deposit on this market actually earns, and the figure the pair book publishes as the effective supply APR. Absent with intrinsicYield.

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    effectiveBorrowRate object

    borrowRate + intrinsicYield (%), rewards EXCLUDED — what a borrow on this market actually costs. Absent with intrinsicYield.

    currentnumberrequired

    Current value

    projectednumberrequired

    Projected value after the action

    flatboolean

    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.

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

    annualUsdnumberrequired
    annualUsdTotalnumberrequired
    equityUsdnumberrequired
    aprPctnumbernullablerequired
    aprPctTotalnumbernullablerequired
    legs object[]required
  • Array [
  • marketUidstringrequired

    Market identifier, formatted lender:chainId:address.

    sidestringrequired

    Possible values: [deposit, borrow, withdraw, repay]

    usdnumberrequired

    Absolute USD size of the leg.

    ratePctnumberrequired

    Effective PROJECTED rate (IRM + intrinsic, %) the leg is priced at; the bare IRM rate where the overlay was unavailable.

    ratePctTotalnumberrequired

    ratePct with rewards folded in (+ on an earning leg, − on a paying leg).

  • ]
  • economics object

    The first (best) quote's economics, mirrored.

    oneOf
    notionalUsd objectrequired

    The position this route creates, at the oracle. equity is the margin the user brings (0 on a pure leverage step).

    equitynumber
    collateralnumber
    debtnumber
    entryCostUsd objectrequired

    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.

    slippagenumber
    feesnumber
    gasnumbernullable
    totalnumber
    slippageBpnumbernullablerequired

    Signed swap-vs-oracle, BP of the swap input. Negative = the route costs money.

    entryCostBpnumbernullablerequired

    entryCostUsd.total over the DEBT notional, BP.

    fees object[]required
  • Array [
  • idstringrequired

    The term sheet's FeeTerm.id (origination, early-repay-penalty, …) or flash for the flash-loan fee.

    labelstringrequired
    whenstringrequired

    entry items sum to entryCostUsd.fees; exit items are in the round-trip exit cost.

    Possible values: [entry, exit]

    usdnumberrequired

    Priced on the notional the fee is charged on. Negative = a rebate.

    valuenumberrequired

    The published rate (read with unit).

    unitstringrequired

    percent | bps | …

    basisstringrequired

    principal | face-value | collateral | …

    mutableboolean

    Governance-mutable snapshot — re-verify before quoting it as a term.

  • ]
  • carryPerDayUsd objectnullablerequired

    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.

    totalnumber
    basenumber
    carryBasisstringrequired

    Possible values: [projected, sticker, none]

    breakEvenDays objectrequired

    entryCostUsd.total / carryPerDayUsd. Null when the carry is not positive (never pays for itself — see notes) or unknown.

    totalnumbernullable
    basenumbernullable
    roundTripDays objectrequired

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

    totalnumbernullable
    basenumbernullable
    closeQuotedboolean
    exitCostUsdnumbernullable
    horizonDaysnumbernullablerequired

    Days until the trade's clock runs out. Null = perpetual.

    horizon objectrequired
    kindstring

    Possible values: [perpetual, to-expiry, to-maturity, rolling]

    endsAtinteger

    Unix seconds.

    sourcestring
    breaksEvenBeforeHorizonbooleannullablerequired
    gas objectnullablerequired
    oneOf
    unitsnumberrequired

    Gas units over the whole bundle — outstanding permissions + main transaction.

    txCountintegerrequired
    estimatedbooleanrequired

    true when every transaction was eth_estimateGas-ed from the account; false when at least one used the typical-size table (the notes say which — the main transaction usually reverts under estimation until its permissions are granted).

    gasPriceGweinumberrequired
    nativePriceUsdnumberrequired
    usdnumberrequired
    existingExposure object

    The marginal view — what this trade does to the account it lands in. The new borrow moves the pool rate, and the debt the account ALREADY holds in that market reprices with it: an ongoing cost the one-off slippage never shows. Same on the deposit side with the opposite sign.

    debtUsdSameMarketnumberrequired

    Debt already held in the DEBT market, USD.

    depositUsdSameMarketnumberrequired

    Deposits already held in the COLLATERAL market, USD.

    rateDeltaBpnumbernullable

    Projected − current borrow rate on the debt market, BP.

    depositRateDeltaBpnumbernullable

    Projected − current deposit rate on the collateral market, BP.

    repriceCostPerDayUsdnumbernullable

    Repricing of the existing book per day (debt repriced up minus deposits repriced up). Positive = a cost. Already netted out of carryPerDayUsd.

    accountAprPrenumbernullable

    Account net APR before the trade, percent, rewards included.

    accountAprPostnumbernullable

    Account net APR after the trade at PROJECTED rates, percent.

    accountNavUsdnumbernullable
    accountNavUsdPostnumbernullable
    notesstring[]required

    Every assumption and every input that was missing, in words. Read them before showing a number.

    flashFeeBpsnumber

    Fee of the flash source the bundle uses, BPS — priced in economics.fees as flash. Absent when no flash is used.

    MarginBuildResponse
    {
    "lender": "string",
    "quotes": [
    {
    "deltas": {
    "aggregator": "string",
    "tradeInput": 0,
    "tradeOutput": 0,
    "deltas": {}
    },
    "tx": {
    "chainType": "evm",
    "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
    "data": "0x617ba037000000000000000000000000c02aaa39b2",
    "value": "0",
    "description": "string"
    },
    "rateImpact": [
    {
    "marketUid": "AAVE_V3:8453:0x4200000000000000000000000000000000000006",
    "utilization": {
    "current": 0.85,
    "projected": 0.83
    },
    "borrowRate": {
    "current": 3.2,
    "projected": 3
    },
    "depositRate": {
    "current": 2.1,
    "projected": 1.9
    },
    "intrinsicYield": 10.37,
    "depositRewardApr": 0,
    "borrowRewardApr": 0,
    "effectiveDepositRate": {
    "current": 10.37,
    "projected": 10.37
    },
    "effectiveBorrowRate": {
    "current": 0,
    "projected": 0
    },
    "flat": true
    }
    ],
    "netApr": {
    "annualUsd": 0,
    "annualUsdTotal": 0,
    "equityUsd": 0,
    "aprPct": 0,
    "aprPctTotal": 0,
    "legs": [
    {
    "marketUid": "string",
    "side": "deposit",
    "usd": 0,
    "ratePct": 0,
    "ratePctTotal": 0
    }
    ]
    },
    "economics": {
    "notionalUsd": {
    "equity": 0,
    "collateral": 0,
    "debt": 0
    },
    "entryCostUsd": {
    "slippage": 0,
    "fees": 0,
    "gas": 0,
    "total": 0
    },
    "slippageBp": 0,
    "entryCostBp": 0,
    "fees": [
    {
    "id": "string",
    "label": "string",
    "when": "entry",
    "usd": 0,
    "value": 0,
    "unit": "string",
    "basis": "string",
    "mutable": true
    }
    ],
    "carryPerDayUsd": {
    "total": 0,
    "base": 0
    },
    "carryBasis": "projected",
    "breakEvenDays": {
    "total": 0,
    "base": 0
    },
    "roundTripDays": {
    "total": 0,
    "base": 0,
    "closeQuoted": true,
    "exitCostUsd": 0
    },
    "horizonDays": 0,
    "horizon": {
    "kind": "perpetual",
    "endsAt": 0,
    "source": "string"
    },
    "breaksEvenBeforeHorizon": true,
    "gas": {
    "units": 0,
    "txCount": 0,
    "estimated": true,
    "gasPriceGwei": 0,
    "nativePriceUsd": 0,
    "usd": 0
    },
    "existingExposure": {
    "debtUsdSameMarket": 0,
    "depositUsdSameMarket": 0,
    "rateDeltaBp": 0,
    "depositRateDeltaBp": 0,
    "repriceCostPerDayUsd": 0,
    "accountAprPre": 0,
    "accountAprPost": 0,
    "accountNavUsd": 0,
    "accountNavUsdPost": 0
    },
    "notes": [
    "string"
    ]
    }
    }
    ],
    "permissionTxns": [
    {
    "to": "string",
    "data": "string",
    "value": "0",
    "description": "string",
    "spender": "string",
    "type": "ERC20"
    }
    ],
    "rateImpact": [
    {
    "marketUid": "AAVE_V3:8453:0x4200000000000000000000000000000000000006",
    "utilization": {
    "current": 0.85,
    "projected": 0.83
    },
    "borrowRate": {
    "current": 3.2,
    "projected": 3
    },
    "depositRate": {
    "current": 2.1,
    "projected": 1.9
    },
    "intrinsicYield": 10.37,
    "depositRewardApr": 0,
    "borrowRewardApr": 0,
    "effectiveDepositRate": {
    "current": 10.37,
    "projected": 10.37
    },
    "effectiveBorrowRate": {
    "current": 0,
    "projected": 0
    },
    "flat": true
    }
    ],
    "netApr": {
    "annualUsd": 0,
    "annualUsdTotal": 0,
    "equityUsd": 0,
    "aprPct": 0,
    "aprPctTotal": 0,
    "legs": [
    {
    "marketUid": "string",
    "side": "deposit",
    "usd": 0,
    "ratePct": 0,
    "ratePctTotal": 0
    }
    ]
    },
    "economics": {
    "notionalUsd": {
    "equity": 0,
    "collateral": 0,
    "debt": 0
    },
    "entryCostUsd": {
    "slippage": 0,
    "fees": 0,
    "gas": 0,
    "total": 0
    },
    "slippageBp": 0,
    "entryCostBp": 0,
    "fees": [
    {
    "id": "string",
    "label": "string",
    "when": "entry",
    "usd": 0,
    "value": 0,
    "unit": "string",
    "basis": "string",
    "mutable": true
    }
    ],
    "carryPerDayUsd": {
    "total": 0,
    "base": 0
    },
    "carryBasis": "projected",
    "breakEvenDays": {
    "total": 0,
    "base": 0
    },
    "roundTripDays": {
    "total": 0,
    "base": 0,
    "closeQuoted": true,
    "exitCostUsd": 0
    },
    "horizonDays": 0,
    "horizon": {
    "kind": "perpetual",
    "endsAt": 0,
    "source": "string"
    },
    "breaksEvenBeforeHorizon": true,
    "gas": {
    "units": 0,
    "txCount": 0,
    "estimated": true,
    "gasPriceGwei": 0,
    "nativePriceUsd": 0,
    "usd": 0
    },
    "existingExposure": {
    "debtUsdSameMarket": 0,
    "depositUsdSameMarket": 0,
    "rateDeltaBp": 0,
    "depositRateDeltaBp": 0,
    "repriceCostPerDayUsd": 0,
    "accountAprPre": 0,
    "accountAprPost": 0,
    "accountNavUsd": 0,
    "accountNavUsdPost": 0
    },
    "notes": [
    "string"
    ]
    },
    "flashFeeBps": 0
    }