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

# Burn Status

> Poll the status of a submitted burn request. The wire path is /v1/claims/{request_id} (legacy).

The SDK polls this endpoint automatically with a 3-second interval and a 120-second timeout. You only need to call it directly if building a custom integration.

<Note>
  The wire path retains the legacy `/v1/claims/{request_id}` segment. In V18 SDK code you call it via the relayer client's `pollClaimStatus` method (or its `pollBurnStatus` alias when plugged into a burner factory's `relayer` dep).
</Note>

## Polling recommendations

* Poll every **3 seconds** (the SDK default).
* Stop polling when status reaches a terminal state: `completed`, `failed`, or `timed_out`.
* Maximum recommended polling duration: **120 seconds**.
* If status is `timed_out`, the MPC callback was not received within the expected block window — the callback may still arrive later. **Verify the nullifier on-chain before re-submitting.**
* If `failure_reason` contains `NullifierAlreadyBurnt`, treat the request as **idempotent success** — the SDK's burner factory does this automatically.

## Burn lifecycle

A burn request progresses through these statuses in order:

* `received` — accepted by the relayer API.
* `validating` — preflight checks running (Merkle root, nullifiers, account state).
* `offsets_reserved` — nullifier offsets reserved for deduplication.
* `building_tx` — transactions being constructed.
* `tx_built` — transactions ready.
* `submitting` — sending to Solana.
* `submitted` — confirmed on-chain.
* `awaiting_callback` — waiting for Arcium MPC callback.
* `callback_received` — MPC callback detected.
* `finalizing` — running cleanup transactions.
* `completed` — burn successful.
* `failed` — error occurred (see `failure_reason` field).
* `timed_out` — MPC callback deadline exceeded.


## OpenAPI

````yaml openapi-relayer.yaml GET /v1/claims/{request_id}
openapi: 3.0.3
info:
  title: Umbra Relayer API
  description: >
    The Umbra relayer submits claim transactions on your behalf so your wallet

    never appears as the fee payer on-chain, preserving privacy.


    ## Response Format


    All endpoints return JSON (`application/json`).


    ## Rate Limiting


    All endpoints are subject to rate limiting. Exceeded limits return `429 Too
    Many Requests`.


    ## Error Format


    All error responses use this structure:

    ```json

    {
      "error": {
        "code": "ERROR_CODE",
        "message": "Human-readable description"
      }
    }

    ```
  version: 0.1.0
  contact:
    name: Umbra Protocol
servers:
  - url: https://relayer.api.umbraprivacy.com
    description: Mainnet
  - url: https://relayer.api-devnet.umbraprivacy.com
    description: Devnet
security: []
tags:
  - name: relayer
    description: Relayer identity and configuration
  - name: claims
    description: Claim submission and status polling
  - name: health
    description: Service health checks
paths:
  /v1/claims/{request_id}:
    get:
      tags:
        - claims
      summary: Get claim status
      description: >
        Returns the current status of a previously submitted claim request.


        The SDK polls this endpoint automatically with a 3-second interval. You
        only

        need to call it directly if building a custom integration.


        **Terminal statuses:** `completed`, `failed`, `timed_out`
      operationId: getClaimStatus
      parameters:
        - name: request_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: UUID returned from `POST /v1/claims`.
      responses:
        '200':
          description: Claim status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimStatus'
              examples:
                in_progress:
                  summary: Claim in progress
                  value:
                    request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: awaiting_callback
                    variant: encrypted_balance
                    resolved_variant: claim_into_existing_shared_balance_v11
                    tx_signature: 5KtP...base58...
                    callback_signature: null
                    computation_account: Comp...base58...
                    failure_reason: null
                    created_at: '2026-03-31T12:00:00Z'
                    updated_at: '2026-03-31T12:00:15Z'
                completed:
                  summary: Claim completed
                  value:
                    request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: completed
                    variant: encrypted_balance
                    resolved_variant: claim_into_existing_shared_balance_v11
                    tx_signature: 5KtP...base58...
                    callback_signature: 7RmQ...base58...
                    computation_account: Comp...base58...
                    failure_reason: null
                    created_at: '2026-03-31T12:00:00Z'
                    updated_at: '2026-03-31T12:01:30Z'
        '404':
          description: Claim not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: 'claim not found: a1b2c3d4-e5f6-7890-abcd-ef1234567890'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ClaimStatus:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - received
            - validating
            - offsets_reserved
            - building_tx
            - tx_built
            - submitting
            - submitted
            - awaiting_callback
            - callback_received
            - finalizing
            - completed
            - failed
            - timed_out
        variant:
          type: string
          enum:
            - encrypted_balance
            - public_balance
        resolved_variant:
          type: string
          nullable: true
          description: >-
            Specific on-chain instruction variant selected by preflight
            validator.
        tx_signature:
          type: string
          nullable: true
          description: Solana transaction signature of the claim instruction.
        callback_signature:
          type: string
          nullable: true
          description: Solana transaction signature of the Arcium MPC callback.
        computation_account:
          type: string
          nullable: true
          description: Base58-encoded computation account address.
        failure_reason:
          type: string
          nullable: true
          description: Error message if status is failed.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable description.

````