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

# Withdraw by burning specific amount of vault shares

> **User Experience Function**: Allows users to withdraw from a vault by specifying the exact number of vault shares to burn.



## OpenAPI

````yaml POST /vault/{address}/withdraw-shares
openapi: 3.0.0
info:
  title: DeFindex API
  description: >-
    Yield infrastructure for neobanks, fintechs and wallets.


    **Base URL:** `https://api.defindex.io`. Every route takes
    `?network=mainnet` (the default) or `?network=testnet`.


    **Auth:** send your API key as `Authorization: Bearer sk_...` (the console
    uses the JWT access token from `POST /login` the same way). Each operation's
    `security` says whether it needs one; `security: []` means it is public.

    - `401`: no credential, or an invalid API key. The body has a `code`
    (`MISSING_CREDENTIAL` or `INVALID_API_KEY`) and a `registerUrl` where you
    get a key, and `WWW-Authenticate` is set.

    - `403`: an expired or invalid JWT, or a valid credential without the
    required role.


    **Rate limits:** a token bucket per account (requests without a key are
    tracked by IP). Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`
    and `X-RateLimit-Reset` (seconds until the bucket is full). A `429` also
    carries `Retry-After` and `retryAfter` in the body.


    | Tier | Burst | Sustained |

    |---|---|---|

    | FREE | 5 | 1/s |

    | STARTER | 20 | 10/s |

    | PROFESSIONAL | 100 | 50/s |

    | BUSINESS | 200 | 100/s |


    **Units:**

    - Amounts are integers in the asset's smallest unit (7 decimals for every
    asset DeFindex lists today: 1 USDC = `10000000`). Responses send them as
    strings; request bodies take JSON integers.

    - Vault shares (dfTokens) are not underlying: `GET /vault/{address}/balance`
    returns both. The share price rises, so the underlying value of a position
    is not what was deposited.

    - Multi-asset vaults take one amount per vault asset, in the order of
    `assets` in `GET /vault/{address}`.

    - Vault `apy` is a percentage (`8.75` = 8.75%). `/strategies`
    `apy7d`/`apy30d`/`apyAllTime` are fractions (`0.0641` = 6.41%).

    - Fees are basis points (`10000` = 100%).


    **Writes never move funds by themselves.** Each write returns an unsigned
    transaction (`xdr`) for the `caller`. Sign it and submit it with `POST
    /send` (or your own RPC). `POST /send` is idempotent: resubmitting the same
    signed XDR returns the original result.
  version: 1.0.0
  contact: {}
  x-logo:
    url: https://links.paltalabs.io/defindex-full.svg
    backgroundColor: '#0e0e0e'
    altText: DeFindex Logo
    href: https://defindex.io
servers: []
security: []
tags: []
paths:
  /vault/{address}/withdraw-shares:
    post:
      tags:
        - Vault
      summary: Withdraw by burning specific amount of vault shares
      description: >-
        **User Experience Function**: Allows users to withdraw from a vault by
        specifying the exact number of vault shares to burn.


        The way to exit a position completely: pass the full `dfTokens` from
        `GET /vault/{address}/balance`.
      operationId: VaultController_withdrawShares
      parameters:
        - name: address
          required: true
          in: path
          description: Stellar address of the vault contract
          schema:
            example: CBNKCU3HGFKHFOF7JTGXQCNKE3G3DXS5RDBQUKQMIIECYKXPIOUGB2S3
            type: string
        - name: network
          required: false
          in: query
          description: Stellar network (testnet or mainnet). Defaults to mainnet.
          schema:
            enum:
              - testnet
              - mainnet
            type: string
      requestBody:
        required: true
        description: 'Share withdrawal parameters. Optional: slippageBps (defaults to 0)'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawSharesDto'
      responses:
        '201':
          description: >-
            Unsigned transaction built for `caller`. Nothing moves until it is
            signed and submitted (`POST /send`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  xdr:
                    type: string
                    nullable: true
                    description: >-
                      Base64 transaction envelope ready for the caller to sign.
                      `null` when the caller is a smart wallet (C address):
                      build your own transaction around `operationXDR`.
                  simulationResponse:
                    description: Amounts returned per asset (integer strings).
                  functionName:
                    type: string
                    description: Contract function the transaction calls
                  operationXDR:
                    type: string
                    description: >-
                      Base64 of the single invokeHostFunction operation, for
                      smart wallets and custom transactions
                  isSmartWallet:
                    type: boolean
                    description: Whether `caller` is a contract (C) address
                  params:
                    description: >-
                      Arguments the contract function was called with, as the
                      API resolved them
                example:
                  xdr: AAAAAgAAAABZnC+hqWmzwW2L...
                  simulationResponse:
                    - '995584'
                  functionName: withdraw
                  operationXDR: AAAAAAAAABgAAAAAAAAAAVqh...
                  isSmartWallet: false
                  params:
                    - 1000000
                    - - 990606
                    - GBMZYL5BVFU3HQLNRM4AC4GTRP553KL2THIZDEZ4RCOIHJH7CK4JKY5M
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            x-correlation-id:
              $ref: '#/components/headers/x-correlation-id'
        '400':
          description: Bad request - invalid parameters
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            x-correlation-id:
              $ref: '#/components/headers/x-correlation-id'
        '401':
          description: >-
            No credential, an invalid API key, or a valid JWT of a disabled
            account. Except for the disabled account, the answer carries
            `WWW-Authenticate` and a `registerUrl`.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            x-correlation-id:
              $ref: '#/components/headers/x-correlation-id'
        '403':
          description: Forbidden - caller is not authorized for this operation
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            x-correlation-id:
              $ref: '#/components/headers/x-correlation-id'
        '429':
          description: >-
            Rate limit exceeded for your tier. Wait `Retry-After` seconds and
            retry.
          headers:
            Retry-After:
              description: Seconds until the next request is allowed.
              schema:
                type: integer
                example: 1
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            x-correlation-id:
              $ref: '#/components/headers/x-correlation-id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 429
                  message:
                    type: string
                    example: Rate limit exceeded
                  error:
                    type: string
                    example: Too Many Requests
                  retryAfter:
                    type: integer
                    example: 1
              example:
                statusCode: 429
                message: Rate limit exceeded
                error: Too Many Requests
                retryAfter: 1
      security:
        - bearer: []
components:
  schemas:
    WithdrawSharesDto:
      type: object
      properties:
        shares:
          type: number
          description: >-
            Vault shares (dfTokens, 7 decimals) to burn, as a JSON integer. Pass
            the full `dfTokens` from GET /vault/{address}/balance to exit
            completely.
          example: 1000000
          minimum: 0
        caller:
          type: string
          description: >-
            Stellar address of the user withdrawing shares. Must be a valid
            Stellar public key.
          example: GB7NTQG4EXB7NZEA5GNFHIHEQVTGQTZ6OWKWUD535FBEHNSEVCKZULIY
        slippageBps:
          type: number
          example: 100
          description: >-
            Slippage tolerance in basis points (bps). 10000 = 100%, 100 = 1%, 50
            = 0.5%. Default is 0 bps (0%)
          minimum: 0
          maximum: 10000
          default: 0
      required:
        - shares
        - caller
  headers:
    X-RateLimit-Limit:
      description: 'Bucket size for your tier: the most requests you can burst.'
      schema:
        type: integer
        example: 5
    X-RateLimit-Remaining:
      description: Requests left in the bucket right now.
      schema:
        type: integer
        example: 4
    X-RateLimit-Reset:
      description: >-
        Seconds (not a timestamp) until the bucket is full again. On a 429,
        seconds until the next request is allowed.
      schema:
        type: integer
        example: 1
    x-correlation-id:
      description: >-
        Request ID. Send your own `x-correlation-id` to have it echoed back;
        quote it when you report a problem.
      schema:
        type: string
        example: 454a42d5-0166-40fe-a4ad-32e77aa44962
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.