> ## Documentation Index
> Fetch the complete documentation index at: https://v3.docs.derive.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Request a withdrawal from a vault

> Submits a signed withdraw action that enqueues a request to burn a given number of vault shares and redeem the proceeds to the user's subaccount. Inputs are the vault subaccount and the share quantity to burn (decimal string). Returns an acknowledgement with the queued request; requires the user-withdraw permission.



## OpenAPI

````yaml /openapi.json post /private/request_vault_withdraw
openapi: 3.1.0
info:
  title: Derive v3 API
  version: 0.2.0
  description: JSON-RPC 2.0 methods, served over WebSocket and HTTP POST.
servers:
  - url: https://api.derive.xyz/v3
    description: Production (HTTP POST base)
  - url: https://testnet.api.derive.xyz/v3
    description: Testnet (HTTP POST base)
security: []
tags:
  - name: Subaccounts
    description: >-
      List, inspect, and label subaccounts, portfolios, positions, and
      collateral.
  - name: Session Keys
    description: Register, edit, and list delegated signing keys.
  - name: Account
    description: Wallet-level account information and settings.
  - name: Orderbook
    description: Place, replace, cancel, and query orders, trigger orders, and algos.
  - name: RFQ
    description: 'Request-for-quote: send RFQs, quote, and execute block trades.'
  - name: Vault Shareholders
    description: >-
      Deposit into and withdraw from vaults, and track shares, requests, and
      performance.
  - name: Vault Curators
    description: >-
      Create and operate curated vaults: settle deposit and withdrawal requests,
      and manage vault metadata.
  - name: History
    description: >-
      Per-account historical records: orders, trades, transfers, and
      settlements.
  - name: Market Maker Protection
    description: Configure, read, and reset market-maker protection.
  - name: Transfers & Withdrawals
    description: Move collateral between subaccounts, to other wallets, and on-chain.
  - name: System
    description: Rate limits and transaction lookups.
  - name: Market Data
    description: Instruments, currencies, tickers, and market-wide feeds.
  - name: Referrals
    description: Referral codes and program performance.
  - name: Other
    description: Uncategorized.
paths:
  /private/request_vault_withdraw:
    post:
      tags:
        - Vault Shareholders
      summary: Request a withdrawal from a vault
      description: >-
        Submits a signed withdraw action that enqueues a request to burn a given
        number of vault shares and redeem the proceeds to the user's subaccount.
        Inputs are the vault subaccount and the share quantity to burn (decimal
        string). Returns an acknowledgement with the queued request; requires
        the user-withdraw permission.
      operationId: private_request_vault_withdraw
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestVaultWithdrawRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultRequestAckResponse'
        default:
          description: JSON-RPC error (see Error Codes)
components:
  schemas:
    RequestVaultWithdrawRequest:
      description: >-
        Fields common to every signed vault action. They appear alongside each
        endpoint's action-specific parameters in the same request object.
      type: object
      required:
        - nonce
        - shares_to_burn
        - signature
        - signature_expiry_sec
        - signer
        - subaccount_id
        - vault_subaccount_id
      properties:
        nonce:
          type: integer
          format: uint64
          minimum: 0
        shares_to_burn:
          description: Number of vault shares to burn, as a decimal string.
          type: string
          format: decimal
        signature:
          description: 0x-prefixed hex of the 65-byte EOA signature.
          type: string
        signature_expiry_sec:
          type: integer
          format: uint64
          minimum: 0
        signer:
          $ref: '#/components/schemas/Address'
        subaccount_id:
          description: >-
            The subaccount the action is signed on; which subaccount applies
            depends on the specific method — see that method's reference.
          type: integer
          format: uint64
          minimum: 0
        vault_subaccount_id:
          type: integer
          format: uint64
          minimum: 0
    VaultRequestAckResponse:
      description: >-
        Returned by `request_vault_deposit` / `request_vault_withdraw`: the id
        the queued request was assigned (the user's handle for polling /
        cancelling).
      type: object
      required:
        - request_id
      properties:
        request_id:
          $ref: '#/components/schemas/VaultRequestId'
    Address:
      description: 20-byte Ethereum address as a 0x-prefixed lowercase hex string.
      type: string
      maxLength: 42
      minLength: 42
      pattern: ^0x[0-9a-fA-F]{40}$
    VaultRequestId:
      description: |-
        Composite vault request id: `(vault_subaccount_id, wallet, vault_nonce)`

        Useful as a stable dedup key across off-chain and on-chain vault events.
      type: object
      required:
        - vault_nonce
        - vault_subaccount_id
        - wallet
      properties:
        vault_nonce:
          type: string
        vault_subaccount_id:
          type: integer
          format: uint64
          minimum: 0
        wallet:
          $ref: '#/components/schemas/Address'

````

## Related topics

- [Page a vault's pending withdrawal requests](/api-reference/vault-curators/page-a-vaults-pending-withdrawal-requests.md)
- [Settle a queued vault withdrawal](/api-reference/vault-curators/settle-a-queued-vault-withdrawal.md)
- [Get a wallet's paginated vault request history](/api-reference/vault-shareholders/get-a-wallets-paginated-vault-request-history.md)