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. Kinds whose on-chain calls act on msg.sender only (wren, bitway) reject a value that differs from operator with a 400.
kind	query	ethena, erc7540, erc4626, native-wnlp, susd3, strata, … (14 values)	no	Protocol override. Otherwise resolved from (chainId, shareToken).
queueId	query	string	no	claim / cancel, Bitway only — the claim-queue id returned by requestClaim (also in its RequestClaim event).
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[].chainType	evm	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.
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[].chainType	evm	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.
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.
actions.permissions[].type	ERC20, Lender	What kind of grant this is. A signatures[] offer names the type it replaces via its replaces field.
actions.signatures	object[]	EIP-712 payloads the user can sign INSTEAD of sending the corresponding permissions entry. Only present when the caller opted in with permit=auto|required and a permit path exists. Sign with eth_signTypedData_v4, then POST the same endpoint with {permits: [{permitId, signature}]} (plus builds where the response issued buildIds) — the permit executes inside the main transaction.
actions.signatures[].permitId	string	Opaque, self-describing handle for this permit. Round-trip it verbatim: POST {permits: [{permitId, signature}]} back to the same endpoint.
actions.signatures[].kind	erc2612, dai, permit2, aaveCredit, morphoAuth, cometAuth	Permit flavour
actions.signatures[].typedData	object	Ready for eth_signTypedData_v4 (domain, types incl. EIP712Domain, primaryType, message). All numeric fields are decimal strings.
actions.signatures[].replaces	string	Which permissions entry this signature replaces (ERC20 | Lender)
actions.signatures[].spender	string	Who the signature authorises. Match against the permission / quote (approvalTarget) it replaces — on multi-spender responses (x-chain) only routes whose approvalTarget equals this spender are covered by the signature.
actions.signatures[].description	string	Human-readable label for this entry.
actions.signatures[].unscoped	boolean	True when the grant is NOT amount-scoped (full position control until revoked) — surface this to the user.
actions.signatures[].deadline	string	Unix seconds after which the signature is worthless (default: 30 minutes).
actions.permitSkipped	object[]	Why a permit was NOT offered for a permission, when one was asked for (permit=auto|required). The corresponding approve transaction stands.
actions.permitSkipped[].replaces	string	Which permission kind stays a transaction (ERC20 | Lender)
actions.permitSkipped[].reason	string

Example response

{
  "success": true,
  "data": {},
  "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"
      }
    ],
    "permitSkipped": [
      {
        "replaces": "string",
        "reason": "string"
      }
    ]
  }
}

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.