Deposit (simulate)
POST/v1/actions/lending/deposit
Build calldata for depositing into a lending pool 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/lending/deposit
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
marketUid | query | string | yes | Market identifier (lender:chainId:address). The address encodes the underlying token (Aave/Morpho/CompoundV3), cToken (CompoundV2), or pool (Init Capital). |
amount | query | string | yes | Amount in wei |
mode | query | proxy, direct | no | Execution mode. Omit it (recommended) and the API picks the path per request: direct (a raw protocol call) when the protocol can serve the request as given, otherwise proxy (the 1delta composer) — e.g. a custom receiver the protocol call cannot express, or a payAsset that needs wrapping. A payAsset that needs a swap routes through a DEX aggregator. |
The transaction to is therefore NOT always the protocol contract: on the proxy path it is the composer, and the ERC-20 approval in actions.permissions targets the composer too. Send what the response returns.
Pass direct or proxy only to force a path; a forced path that cannot serve the request (for instance a custom receiver on a lender whose direct call has no recipient slot) is refused with 400 INVALID_PARAM, never built. |
| operator | query | string | yes | Wallet address that signs and sends the transaction (and pays, for deposit/repay). Not necessarily the position owner — see receiver. |
| receiver | query | string | no | Recipient of the lender position (deposit), of the underlying tokens (borrow/withdraw), or the account whose debt is repaid (repay).
Defaults to operator when omitted — so an on-behalf deposit MUST pass this parameter; there is no onBehalf / onBehalfOf alias, and an unknown parameter name is ignored.
Custom-receiver support is per-lender. The API auto-selects the execution path:
Direct path supported
- Aave V2/V3 —
supply/withdrawhonorto. - Aave V4 — deposit via GiverPM
supplyOnBehalfOf. Requires the GiverPM to be curated inaave-v4-peripherals.jsonwith a name containing "giver". - Compound V3 —
supplyTo/withdrawTo(a borrow is awithdrawToof the base asset). - Morpho Blue & Lista DAO ERC-20 markets — Morpho
onBehalf(repay included). - Euler V2 ERC-20 vaults — ERC-4626
deposit(receiver),repay(assets, receiver). Collateral auto-enable is dropped for non-sub-account receivers. - Exactly —
repay/repayAtMaturitytake theborrower. - Silo V2/V3 ERC-20 —
deposit(_, receiver, _). - Gearbox V3 passive-pool deposits — ERC-4626
deposit(_, receiver). - Fluid borrow & withdraw —
operate(..., to_)outflow slot. - Fluid deposit to an existing NFT when
accountIdis supplied — pure-depositoperate()calls bypass Fluid's owner auth gate, and the API folds a pre-flightVaultFactory.ownerOf(nftId) == receivercheck into the merged multicall (rejects with 400INVALID_PARAMon mismatch,VALIDATION_FAILEDif the RPC can't confirm ownership).
Routes to composer (proxy) path
- Compound V2 family — direct
mintismsg.sender-only. - Fluid fresh-open deposits — no
accountIdoraccountId=0. The composer mints the new position NFT to itself, then transfers it toreceivervia the encoder'snftReceiverslot. - Native-ETH vaults on Fluid (deposit / withdraw / repay) and the CompoundV2 family — the composer forwards
msg.valueto the vault's payable entrypoint. Other lenders' composer paths reject native asset and require wrapped-native aspayAsset.
Refused with a receiver (the on-chain call has no recipient)
- Gearbox V3 credit-side
addCollateral— CA bound to operator — and Gearbox V3 borrow (the funds stay in the credit account). - Liquity V2 family — Stability Pool deposit / withdrawal (
provideToSP/withdrawFromSP) and trove collateral withdrawal (withdrawCollpays the trove's own receiver). - Aave V4 native-gateway path —
supplyAsCollateralNativehas no recipient slot.
Unsupported in any single tx
- Init Capital — position NFT swept to operator.
- Euler V2 / Silo V2/V3 native deposit paths — router/orchestrator credits msg.sender.
- Fluid repay — on-chain primitive permits it, direct handler doesn't expose a receiver slot yet (routes to proxy as a conservative default).
Repay with a receiver settles the RECEIVER's debt with the operator's funds. On Euler V2, Morpho Blue / Lista and Exactly, isAll=true with a receiver is refused: the amount owed would be read from the operator, not the receiver — pass an explicit amount.
When the lender cannot honor a custom receiver on the direct path and mode is omitted, the API routes the request through the composer automatically — the response then targets the composer (see mode). Forcing mode=direct with a custom receiver the direct call cannot express (Compound V2, Init, a Fluid fresh open) is refused with 400 INVALID_PARAM, and a leg with no recipient (above) with 400 ACTION_FAILED; a receiver is never silently replaced by the operator.
The optional simulation preview is computed for the operator, not the receiver: with a custom receiver it shows the position change on the operator's account. Read the receiver's position from the user-positions endpoint after execution. |
| payAsset | query | string | no | Asset to pay with.
Use the zero address to pay with native ETH on lenders whose vault accepts native (e.g. Init Capital, Fluid native-ETH vaults, CompoundV2 cETH markets).
Proxy mode: defaults to market asset. Native is forwarded as msg.value only when the lender supports it (e.g. Fluid, CompoundV2); otherwise the composer rejects. |
| isShares | query | boolean | no | Amount is in shares (direct mode) |
| accountId | query | string | no | Per-position identifier. Lender-specific:
- Init Capital — account ID, required for borrow/withdraw/repay.
- Euler V2 — sub-account index (0..255), defaults to 0.
- Gearbox V3 — credit-account address (alias:
creditAccount). - Dolomite — margin account number (uint256,
0= the default cross-margin account), oriso:<marketId>:<n>for a position inside an isolation-mode VAULT (dGM, dsavETH, dGMX …). The vault, not the user, owns that DolomiteMargin account;nmust be >= 100 for a borrow position and0is the vault's supply-only balance. Position ids come back in this form from/v1/data/lending/positions. - Fluid — position NFT id. Omit or pass
0to mint a new position; supply an existing nftId to act on an existing position. Required for borrow/withdraw/repay; for deposit it unlocks the direct path with a customreceiver(deposit lands on the receiver-owned NFT after pre-flightownerOfvalidation). | |slippage| query | number | no | Slippage tolerance in basis points (50= 0.5%,100= 1%).
Required whenever the action has to price something:
- Aggregator swap — when
payAsset/receiveAssetdiffers from the market's underlying, the currency conversion is routed through a DEX aggregator and this bounds that swap. - Order-book take (Morpho Midnight) — bounds the worst execution price accepted while filling offers.
Ignored when neither applies (same-asset action on a pool lender). |
| simulate | query | boolean | no | When true, the API fetches the operator's on-chain balances and returns projected post-trade metrics in the simulation field. The projection is always of the operator's account: with a custom receiver it does not show the receiver's position. Default: false. |
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 | Simulation results including projected health factor and borrow capacity |
data.rateImpact | object[] | Projected interest-rate impact per market. Single-market actions produce 1 entry; loop actions produce 2. Null if IRM data is unavailable. |
data.rateImpact[].marketUid | string | Market identifier (format: lender:chainId:address) |
data.rateImpact[].utilization | object | A current/projected pair for a single rate metric. |
data.rateImpact[].utilization.current | number | Current value |
data.rateImpact[].utilization.projected | number | Projected value after the action |
data.rateImpact[].borrowRate | object | A current/projected pair for a single rate metric. |
data.rateImpact[].borrowRate.current | number | Current value |
data.rateImpact[].borrowRate.projected | number | Projected value after the action |
data.rateImpact[].depositRate | object | A current/projected pair for a single rate metric. |
data.rateImpact[].depositRate.current | number | Current value |
data.rateImpact[].depositRate.projected | number | Projected value after the action |
data.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.rateImpact[].depositRewardApr | number | Sum of reward-stream APRs (%) on the deposit side. Absent with intrinsicYield. |
data.rateImpact[].borrowRewardApr | number | Sum of reward-stream APRs (%) rebated on the borrow side. Absent with intrinsicYield. |
data.rateImpact[].effectiveDepositRate | object | A current/projected pair for a single rate metric. |
data.rateImpact[].effectiveDepositRate.current | number | Current value |
data.rateImpact[].effectiveDepositRate.projected | number | Projected value after the action |
data.rateImpact[].effectiveBorrowRate | object | A current/projected pair for a single rate metric. |
data.rateImpact[].effectiveBorrowRate.current | number | Current value |
data.rateImpact[].effectiveBorrowRate.projected | number | Projected value after the action |
data.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.simulation | object | Projected post-trade metrics for the operator's account, or null if simulation failed. With a custom receiver this does NOT show the receiver's position. |
data.simulation.pre | object | Portfolio state before the trade. |
data.simulation.pre.healthFactor | number | Health factor before the trade (null-safe: capped at 1e18 when no debt) |
data.simulation.pre.borrowCapacity | number | Borrow capacity (USD) before the trade |
data.simulation.post | object | Projected portfolio state after the trade. |
data.simulation.post.healthFactor | number | Projected health factor after the trade |
data.simulation.post.borrowCapacity | number | Projected borrow capacity (USD) after the trade |
data.simulation.post.balanceData | object | Aggregated balance data for a sub-account. |
data.simulation.post.aprData | object | APR breakdown for a sub-account. |
data.simulationError | string | Error message if simulation failed |
data.rateImpact | object[] | Projected interest-rate impact per market. Single-market actions produce 1 entry; loop actions produce 2. Null if IRM data is unavailable. |
data.rateImpact[].marketUid | string | Market identifier (format: lender:chainId:address) |
data.rateImpact[].utilization | object | A current/projected pair for a single rate metric. |
data.rateImpact[].utilization.current | number | Current value |
data.rateImpact[].utilization.projected | number | Projected value after the action |
data.rateImpact[].borrowRate | object | A current/projected pair for a single rate metric. |
data.rateImpact[].borrowRate.current | number | Current value |
Example response
{
"success": true,
"data": {
"rateImpact": [
{
"marketUid": "AAVE_V3:8453:0x4200000000000000000000000000000000000006",
"utilization": {
"current": 1.0,
"projected": 1.0
},
"borrowRate": {
"current": 1.0,
"projected": 1.0
},
"depositRate": {
"current": 1.0,
"projected": 1.0
},
"intrinsicYield": 10.37,
"depositRewardApr": 1.0,
"borrowRewardApr": 1.0,
"effectiveDepositRate": {
"current": 1.0,
"projected": 1.0
},
"effectiveBorrowRate": {
"current": 1.0,
"projected": 1.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"
},
"actions": {
"transactions": [
{
"chainType": "evm",
"to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
"data": "0x617ba037000000000000000000000000c02aaa39b2",
"value": "0",
"description": "string"
}
],
"alternatives": [
{
"chainType": "evm",
"to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
"data": "0x617ba037000000000000000000000000c02aaa39b2",
"value": "0",
"description": "string"
}
],
"permissions": [
{
"to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"data": "0x617ba037000000000000000000000000c02aaa39b2",
"value": "0",
"description": "string",
"spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"type": "ERC20"
}
],
"signatures": [
{
"permitId": "string",
"kind": "erc2612",
"typedData": {},
"replaces": "string",
"spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"description": "string",
"unscoped": true,
"deadline": "string"
}
],
"signs": [
{
"purpose": "authorize-action",
"format": "eip712",
"typedData": {},
"message": "string",
"signer": "string",
"deadline": "string",
"spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"description": "string",
"submit": {
"method": "GET",
"endpoint": "string",
"params": {},
"body": {},
"signatureField": "string"
}
}
],
"permitSkipped": [
{
"replaces": "string",
"reason": "string"
}
]
}
}
Request
Responses
- 200
- 400
- 429
- 500
- 502
Transaction calldata with post-trade 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.