Withdraw (simulate)

POST 
/v1/actions/lending/withdraw

Build calldata for withdrawing from 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/withdraw

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. proxy = 1delta composer, direct = raw protocol
operator	query	string	no	Wallet address of the user executing the action
receiver	query	string	no	Recipient of the lender position (deposit) or underlying tokens (borrow/withdraw).
Defaults to operator when omitted.

Custom-receiver support is per-lender. The API auto-selects the execution path:

Direct path supported

• Aave V2/V3 — supply / withdraw honor to.
• Aave V4 — deposit via GiverPM supplyOnBehalfOf. Requires the GiverPM to be curated in aave-v4-peripherals.json with a name containing "giver".
• Compound V3 — supplyTo / withdrawTo.
• Morpho Blue & Lista DAO ERC-20 markets — Morpho onBehalf.
• Euler V2 ERC-20 vaults — ERC-4626 deposit(receiver). Collateral auto-enable is dropped for non-sub-account receivers.
• 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 accountId is supplied — pure-deposit operate() calls bypass Fluid's owner auth gate, and the API folds a pre-flight VaultFactory.ownerOf(nftId) == receiver check into the merged multicall (rejects with 400 INVALID_PARAM on mismatch, VALIDATION_FAILED if the RPC can't confirm ownership).

Routes to composer (proxy) path

• Compound V2 family — direct mint is msg.sender-only.
• Fluid fresh-open deposits — no accountId or accountId=0. The composer mints the new position NFT to itself, then transfers it to receiver via the encoder's nftReceiver slot.
• Native-ETH vaults on Fluid (deposit / withdraw / repay) and the CompoundV2 family — the composer forwards msg.value to the vault's payable entrypoint. Other lenders' composer paths reject native asset and require wrapped-native as payAsset.

Direct-only branches that throw

• Gearbox V3 credit-side addCollateral — CA bound to operator.
• Aave V4 native-gateway path — supplyAsCollateralNative has 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).

When the lender cannot honor a custom receiver on the direct path, getTarget falls back to proxy automatically. Forcing mode=direct on an unsupported path either throws (Gearbox credit-side, Aave V4 spoke, the explicit Silo router check) or silently credits the operator instead (Compound V2, Init, and Fluid fresh-open). | | isAll | query | boolean | no | Withdraw/repay full balance.

When on-chain position data is available, the API compares amount against the actual balance to decide the effective mode:

• If amount covers the full position the action is treated as "withdraw/repay all" regardless of this flag.
• If isAll is true but amount is less than the position, the API falls back to a partial action with the provided amount to avoid on-chain reverts.

Without on-chain data, the flag is trusted as-is. | | receiveAsset | query | string | no | Asset to receive.

Use the zero address to receive native ETH on lenders whose vault returns native (e.g. Init Capital, Fluid native-ETH vaults, CompoundV2 cETH markets).

Proxy mode: defaults to market asset. Native delivery is supported only when the lender does so on-chain (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).
• Fluid — position NFT id. Omit or pass 0 to 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 custom receiver (deposit lands on the receiver-owned NFT after pre-flight ownerOf validation). | | 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 / receiveAsset differs 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 user's on-chain balances and returns projected post-trade metrics in the simulation field. 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.transaction	object	An EVM transaction ready to sign and broadcast. Send to, data and value as-is; do not re-encode them.
data.transaction.to	string	Target contract address
data.transaction.data	string	Encoded calldata
data.transaction.value	string	ETH value to send with the transaction
data.transaction.description	string	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").
data.permissionTxns	object[]	Approvals needed for this specific quote. Most integrators should use the deduplicated envelope-level actions.permissions instead.
data.permissionTxns[].to	string	Target contract address
data.permissionTxns[].data	string	Encoded calldata
data.permissionTxns[].value	string	ETH value
data.permissionTxns[].description	string	Human-readable description of the approval (e.g. "Approve borrow for AAVE_V3", "Approve ERC20")
data.permissionTxns[].spender	string	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.
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.simulation	object	Projected post-trade metrics, or null if simulation failed
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.transaction	object	An EVM transaction ready to sign and broadcast. Send to, data and value as-is; do not re-encode them.
data.transaction.to	string	Target contract address
data.transaction.data	string	Encoded calldata
data.transaction.value	string	ETH value to send with the transaction
data.transaction.description	string	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").
data.permissionTxns	object[]	Approvals needed for this specific quote. Most integrators should use the deduplicated envelope-level actions.permissions instead.

Example response

{
  "success": true,
  "data": {
    "transaction": {
      "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
      "data": "0x617ba037000000000000000000000000c02aaa39b2",
      "value": "0",
      "description": "string"
    },
    "permissionTxns": [
      {
        "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      }
    ],
    "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
        }
      }
    ],
    "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": [
      {
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "alternatives": [
      {
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "permissions": [
      {
        "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      }
    ]
  }
}

Request

Responses

200

Transaction calldata with post-trade simulation

400

Validation error

429

Rate limited. Unauthenticated callers share a per-IP budget; send an x-api-key header to lift it. Retry with exponential backoff.

500

Unexpected server error. Safe to retry with backoff.

502

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.