MarginSimulationBuildResponse

Full build loop response enriched with post-trade simulation (POST only).

lenderstringrequired

Protocol identifier. See the LenderId schema.

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.

]

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

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

]

simulation objectnullable

Projected post-trade metrics, or null if simulation failed

oneOf

LoopPostTradeMetrics

pre object

Portfolio state before the trade.

healthFactornumber

Health factor before the trade (null-safe: capped at 1e18 when no debt)

Example: 1.85

borrowCapacitynumber

Borrow capacity (USD) before the trade

Example: 3000

post object

Projected portfolio state after the trade.

healthFactornumber

Projected health factor after the trade

Example: 2.1

borrowCapacitynumber

Projected borrow capacity (USD) after the trade

Example: 3500

balanceData object

Aggregated balance data for a sub-account.

depositsnumber

Total deposits in USD

Example: 10000.5

debtnumber

Total debt in USD

Example: 5000.25

adjustedDebtnumber

Debt adjusted for borrow factors

Example: 5500

collateralnumber

Collateral value in USD

Example: 9000

collateralAllActivenumber

Collateral if all assets were enabled

Example: 10000.5

borrowDiscountedCollateralnumber

Collateral discounted by borrow factors

Example: 8000

borrowDiscountedCollateralAllActivenumber

Discounted collateral if all enabled

Example: 9000

navnumber

Net asset value (deposits - debt)

Example: 5000.25

deposits24hnumber

Deposits 24h ago (for change calculation)

Example: 9800

debt24hnumber

Debt 24h ago

Example: 4900

nav24hnumber

NAV 24h ago

Example: 4900

rewards object[]nullable

Pending reward token claims. Each entry represents a single reward program.

Array [

assetstring

Reward token contract address

Example: 0xc00e94Cb662C3520282E6f5717214004A7f26888

totalRewardsnumber

Total accumulated rewards (token units)

Example: 12.5

claimableRewardsnumber

Immediately claimable rewards (token units)

Example: 12.5

]

aprData object

APR breakdown for a sub-account.

aprnumber

Net APR (deposit - borrow)

Example: 2.5

depositAprnumber

Weighted deposit APR

Example: 3.5

borrowAprnumber

Weighted borrow APR

Example: 5.2

rewardAprnumber

Total reward APR

Example: 1.2

rewardDepositAprnumber

Reward APR on deposits

Example: 0.8

rewardBorrowAprnumber

Reward APR on borrows

Example: 0.4

intrinsicAprnumber

Intrinsic yield APR (e.g., stETH staking)

Example: 0

intrinsicDepositAprnumber

Intrinsic yield APR portion from deposits

Example: 0

intrinsicBorrowAprnumber

Intrinsic yield APR portion from borrows

Example: 0

rewards object

Per-reward-token APR breakdown. Keys are reward token addresses.

property name* RewardAprBreakdown

APR breakdown for a single reward token.

aprnumber

Net reward APR (normalized to NAV)

Example: 0.045

borrowAprnumber

Reward APR on borrows

Example: 0.012

depositAprnumber

Reward APR on deposits

Example: 0.078

simulationErrorstring

Error message if simulation failed

MarginSimulationBuildResponse
{
  "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
        }
      ]
    }
  ],
  "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
    }
  ],
  "simulation": {
    "pre": {
      "healthFactor": 1.85,
      "borrowCapacity": 3000
    },
    "post": {
      "healthFactor": 2.1,
      "borrowCapacity": 3500,
      "balanceData": {
        "deposits": 10000.5,
        "debt": 5000.25,
        "adjustedDebt": 5500,
        "collateral": 9000,
        "collateralAllActive": 10000.5,
        "borrowDiscountedCollateral": 8000,
        "borrowDiscountedCollateralAllActive": 9000,
        "nav": 5000.25,
        "deposits24h": 9800,
        "debt24h": 4900,
        "nav24h": 4900,
        "rewards": [
          {
            "asset": "0xc00e94Cb662C3520282E6f5717214004A7f26888",
            "totalRewards": 12.5,
            "claimableRewards": 12.5
          }
        ]
      },
      "aprData": {
        "apr": 2.5,
        "depositApr": 3.5,
        "borrowApr": 5.2,
        "rewardApr": 1.2,
        "rewardDepositApr": 0.8,
        "rewardBorrowApr": 0.4,
        "intrinsicApr": 0,
        "intrinsicDepositApr": 0,
        "intrinsicBorrowApr": 0,
        "rewards": {}
      }
    }
  },
  "simulationError": "string"
}