Savings-vault request-withdraw · claim · deposit · cancel

GET 
/v1/actions/vaults/savings

Build calldata for savings-vault exits — the cooldown / async-redeem mechanics that plain ERC-4626 withdraw can't express (Ethena sUSDe, erc7540 async vaults, instant erc4626 redeem, and Native Credit Pool wNLP) — plus the deposit leg for the one family that isn't ERC-4626. The protocol is resolved from the calldata-sdk savings registry by (chainId, shareToken), or forced with kind=ethena|erc7540|erc4626|native-wnlp.

ERC-4626 savings deposits go through /v1/actions/vaults/deposit. Native wNLP works on either route — /vaults/deposit auto-detects it from the registry and needs no underlying.

Actions

• request-withdraw (default) — start the exit:
  • Ethena → cooldownShares(amount) (or cooldownAssets when byAssets=true); escrows the assets for the cooldown window.
  • erc7540 → requestRedeem.
  • erc4626 → instant redeem (no cooldown).
  • native-wnlp → WithdrawQueue.requestWithdrawal(amount) — the free leg; the payout is snapshotted at request time and claimable after the queue window. Pass instant=true for instantRedeem instead: one transaction, no wait, but it costs the vault's withdrawFeeBps (100 bps by default) — deducted from the underlying paid out, never charged as a separate transfer — and is capped by its reported liquidity.
• claim — settle a matured exit:
  • Ethena → unstake(receiver).
  • erc7540 / erc4626 → redeem (pass shares).
  • native-wnlp → claimWithdrawalTo(receiver); no shares — the queue always pays the full request.
• deposit — native-wnlp only (depositAndWrap(receiver, amount)). Every other kind is a plain ERC-4626 mint and is rejected here with a pointer to /vaults/deposit.
• cancel — native-wnlp only; withdraw an open queued request and take the shares back. One request per address, so cancel is also how you resize one.

Track pending requests via /v1/data/vaults/withdrawals.

Plain-text reference — GET /v1/actions/vaults/savings

Parameters

Parameter	In	Type	Required	Description
chainId	query	string	yes	Chain ID See the ChainId schema for the full set of supported chains.
action	query	request-withdraw, claim, deposit, cancel	no	Operation to build. deposit and cancel are Native wNLP only.
shareToken	query	string	yes	Savings share-token address (e.g. sUSDe 0x9d39a5de30e57443bff2a8307a4256c8797a3497).
operator	query	string	yes	User wallet executing the action (share holder). receiver defaults to it.
receiver	query	string	no	Recipient of the claimed assets. Defaults to operator.
kind	query	ethena, erc7540, erc4626, native-wnlp	no	Protocol override. Otherwise resolved from (chainId, shareToken).
amount	query	string	no	request-withdraw: shares to cool down (or underlying assets when byAssets=true). deposit: underlying to wrap. Wei.
byAssets	query	boolean	no	request-withdraw, Ethena only — interpret amount as the underlying asset amount (cooldownAssets) instead of shares (cooldownShares).
instant	query	boolean	no	request-withdraw, native-wnlp only — take the immediate instantRedeem instead of the free queue. Costs the vault’s withdrawFeeBps (deducted from the underlying paid out) and is capped by its liquidity; check both on /v1/data/vaults first.
underlying	query	string	no	deposit, native-wnlp only — the asset to wrap, when the pool is too new to be in the registry. Otherwise resolved automatically.
shares	query	integer	no	claim: share amount to redeem (erc7540 / erc4626).
owner	query	string	no	request-withdraw: share owner, when not operator (erc4626 redeem).
controller	query	string	no	erc7540 controller, when not operator.

Response 200

Field	Type	Description
success	True
data	object	Informational data (quotes, simulation results, etc.)
actions	object	Transaction calldata and approvals. Null for quote-only responses (no account provided).
actions.transactions	object[]	Pre-trade setup transactions (e.g. e-mode switch, collateral enable). Execute these before the main swap. Empty when no setup is needed.
actions.transactions[].to	string	Target contract address
actions.transactions[].data	string	Encoded calldata
actions.transactions[].value	string	ETH value to send with the transaction
actions.transactions[].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").
actions.alternatives	object[]	DEX aggregator swap transactions sorted by best output (descending). Each entry's description is the aggregator name. The client should pick one to execute. Present on loop action endpoints.
actions.alternatives[].to	string	Target contract address
actions.alternatives[].data	string	Encoded calldata
actions.alternatives[].value	string	ETH value to send with the transaction
actions.alternatives[].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").
actions.permissions	object[]	Approval/delegation transactions that must execute before both transactions and alternatives. Includes ERC20 allowances (targeting the composer contract) and lender borrow/withdrawal delegations (targeting the lending protocol contract directly). Filtered against on-chain state so only missing approvals are returned. Null when no approvals are needed.
actions.permissions[].to	string	Target contract address
actions.permissions[].data	string	Encoded calldata
actions.permissions[].value	string	ETH value
actions.permissions[].description	string	Human-readable description of the approval (e.g. "Approve borrow for AAVE_V3", "Approve ERC20")
actions.permissions[].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.

Example response

{
  "success": true,
  "data": {},
  "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

Ordered transactions[] + ERC-20 permissions[] (run first). Each step carries its builder label as description.

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.