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

# burnToken

> Burn tokens held by the signing wallet.

Prepares unsigned transactions for burning tokens from the signer's balance. Use `POST /prepare-transactions` with `method=burnToken`.

Burning reduces the token's current `totalSupply`. It does not reduce the configured maximum supply.

## The signer's balance is what burns

The prepared transaction calls `burn(amount)`, which burns the caller's own tokens. The API checks
the balance of `signerAddress` and returns `Insufficient token balance` when it is short.

> [!WARNING]
>
> `investorEmail` is required, but it only attributes the burn in Brickken's records. It does **not**
> select whose tokens are burned, and there is no `investorAddress` selector on this method.
>
> A tokenizer wallet that holds none of the token therefore gets `Insufficient token balance` even
> when the investor named in the request holds plenty.

## Burning tokens an investor holds

The API does not expose a delegated burn. Two supported routes:

* **The investor signs.** Use the investor's wallet as `signerAddress`, so the burn comes out of the balance that actually holds the tokens.
* **Recover, then burn.** Have the investor `approve` the company wallet, use [`transferFrom`](https://docs.brickken.com/api-reference/endpoint/prepare-transferFrom) to move the tokens to it, then burn from the company wallet.

If your application only ever acts for the issuer and can never obtain an investor signature, only the second route is available.

## Next step

Preparing does not touch the chain. The response gives you `txId` and an array of unsigned `transactions` — you still have to sign and submit them.

**1. Sign every returned transaction**

Sign each entry locally with the wallet that sends the transaction — `signerAddress`, or `investorAddress` for `newInvest` and `claimTokens`. It must be whitelisted by Brickken, and it needs native gas on the target chain.

**2. Submit the signed payloads**

`POST` them to [`/send-transactions`](https://docs.brickken.com/api-reference/endpoint/send) as `{ txId, signedTransactions }` and Brickken broadcasts for you.

If you would rather broadcast yourself, prepare with `executionMode: "client-broadcast"` and confirm afterwards with `{ txId, txHash }` instead.

**3. Poll until it confirms**

Call [`GET /get-transaction-status`](https://docs.brickken.com/api-reference/endpoint/get-transaction-status) with the `txId`. A `pending` status means it is broadcast but not yet mined — do not resubmit.

Full walkthrough: [Tokenize an asset and run an STO](https://docs.brickken.com/api-reference/guides/tokenize-and-run-an-sto.md).


## OpenAPI

````yaml api-reference/prepare/burnToken.json POST /prepare-transactions
openapi: 3.1.0
info:
  title: Brickken API V2 - prepare burnToken
  description: >-
    Method-scoped view of `POST /prepare-transactions` for `method=burnToken`.
    The full endpoint, with every supported method and the common request body
    parameters, is documented in `api-reference/openapi.json`.
  version: 2.0.0
servers:
  - url: https://api.sandbox.brickken.com
    description: Sandbox Environment
  - url: https://api.brickken.com
    description: Production Environment
security: []
paths:
  /prepare-transactions:
    post:
      summary: Prepare a token burn
      description: >-
        Prepares the unsigned transaction that burns tokens from the signer
        balance.
      operationId: prepare_burnToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - method
                - chainId
                - signerAddress
                - tokenSymbol
                - amount
                - investorEmail
              properties:
                method:
                  type: string
                  example: burnToken
                  enum:
                    - burnToken
                  description: >-
                    Required. Operation to prepare. Must be `burnToken` for this
                    endpoint.
                  default: burnToken
                chainId:
                  type: string
                  description: >-
                    Required. Blockchain network identifier. Hex format is
                    recommended, for example Sepolia `aa36a7`.
                  example: aa36a7
                signerAddress:
                  type: string
                  description: >-
                    Required. Wallet whose tokens are burned. It also signs the
                    transaction and must hold at least `amount`.
                  example: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                tokenSymbol:
                  type: string
                  description: >-
                    Required. Symbol of the token to burn. Must be 2 to 5
                    uppercase letters or numbers.
                  example: EXMPL
                amount:
                  type: string
                  description: Required. Amount of tokens to burn.
                  example: '100'
                investorEmail:
                  type: string
                  description: >-
                    Required. Email used to attribute the burn in the Brickken
                    records.
                  example: investor@example.com
                  format: email
              example:
                method: burnToken
                chainId: aa36a7
                signerAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
                tokenSymbol: EXMPL
                amount: '100'
                investorEmail: investor@example.com
            example:
              method: burnToken
              chainId: aa36a7
              signerAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
              tokenSymbol: EXMPL
              amount: '100'
              investorEmail: investor@example.com
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactions:
                    type: array
                    description: Array of unsigned transaction objects ready for signing
                    items:
                      type: object
                      properties:
                        from:
                          type: string
                          description: Sender address
                          example: '0x1234567890abcdef1234567890abcdef12345678'
                        to:
                          type: string
                          description: Recipient address
                          example: '0xabcdef1234567890abcdef1234567890abcdef12'
                        value:
                          type: string
                          description: Transaction value in hex
                          example: '0x00'
                        nonce:
                          type: integer
                          description: Transaction nonce
                          example: 3792
                        chainId:
                          type: integer
                          description: Blockchain network chain ID
                          example: 11155111
                        data:
                          type: string
                          description: Transaction data payload
                          example: >-
                            0xd362e8a70000000000000000000000000000000000000000000000000000000000000040...
                        type:
                          type: integer
                          description: Transaction type (EIP-1559)
                          example: 2
                        maxPriorityFeePerGas:
                          type: string
                          description: Maximum priority fee per gas
                          example: '1150000'
                        maxFeePerGas:
                          type: string
                          description: Maximum fee per gas
                          example: '1156037'
                        gasLimit:
                          type: string
                          description: Gas limit in hex
                          example: '0xccef'
                  info:
                    type: object
                    description: Metadata about the operation
                    properties:
                      tokenizerEmail:
                        type: string
                        description: Email of the tokenizer
                        example: tokenizer@example.com
                      tokenSymbol:
                        type: string
                        description: Symbol of the token
                        example: EXMPL
                      investorEmail:
                        type: string
                        description: Email of the investor (when applicable)
                        example: investor@example.com
                  txId:
                    type: string
                    description: >-
                      Unique identifier for this transaction batch (required for
                      /send-transactions). This is NOT a blockchain transaction
                      hash.
                    example: >-
                      0x46adea7bdf49c576a760102e0d6bc9ecd650b3998588cd3d7f576a7973426aad
                required:
                  - transactions
                  - txId
      security:
        - apiKeyAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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