Skip to main content
Submit a claim request
curl --request POST \
  --url https://relayer.api.umbraprivacy.com/v1/claims \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_pubkey": "<string>",
  "mint": "<string>",
  "stealth_pool_index": 123,
  "max_utxo_capacity": 2,
  "optional_data": "<string>",
  "proof_account_data": {
    "rescue_encryption_public_key": "<string>",
    "encryption_nonce": "<string>",
    "merkle_root": "<string>",
    "tvk_timestamp": 123,
    "groth16_proof_a": "<string>",
    "groth16_proof_b": "<string>",
    "groth16_proof_c": "<string>",
    "rescue_encryption_commitment": "<string>",
    "encryption_validation_polynomial": "<string>",
    "rescue_encrypted_master_viewing_key_low": "<string>",
    "rescue_encrypted_master_viewing_key_high": "<string>",
    "rescue_encrypted_blinding_factor_low": "<string>",
    "rescue_encrypted_blinding_factor_high": "<string>",
    "rescue_encrypted_total_amount": "<string>",
    "rescue_encrypted_relayer_commission_fee": "<string>",
    "rescue_encrypted_protocol_commission_fee": "<string>",
    "total_relayer_fees": 123
  },
  "utxo_slot_data": [
    {
      "slot_index": 123,
      "nullifier": "<string>",
      "linker_encryptions": [
        "<string>"
      ],
      "linker_key_commitments": [
        "<string>"
      ]
    }
  ],
  "fee_proof_data": {
    "amount": "<string>",
    "relayer_fixed_sol_fees": "<string>",
    "protocol_fees_amount_lower_bound": "<string>",
    "protocol_fees_amount_upper_bound": "<string>",
    "protocol_fees_base_fees_in_spl": "<string>",
    "protocol_fees_commission_fee_in_spl": 123,
    "protocol_fees_merkle_path": [
      "<string>"
    ],
    "protocol_fees_leaf_index": 123,
    "relayer_fees_amount_lower_bound": "<string>",
    "relayer_fees_amount_upper_bound": "<string>",
    "relayer_fees_base_fees_in_spl": "<string>",
    "relayer_fees_commission_fee_in_spl": 123,
    "relayer_fees_merkle_path": [
      "<string>"
    ],
    "relayer_fees_leaf_index": 123
  }
}
'
{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "received"
}
This endpoint is designed to be called by the SDK’s burner factories, not directly. The request body contains cryptographic proof data that must be generated correctly by the ZK prover. Use getSelfBurnableStealthPoolNoteIntoETABurnerFunction, getReceiverBurnableStealthPoolNoteIntoETABurnerFunction, or getSelfBurnableStealthPoolNoteIntoATABurnerFunction from @umbra-privacy/sdk/burn instead.
The relayer validates the request, builds the on-chain transactions, and submits them asynchronously. Poll GET /v1/claims/{request_id} with the returned UUID to track progress.
The wire path retains the legacy /v1/claims segment. In SDK code you call it via the relayer client’s submitClaim method (or its submitBurn alias when plugged into a burner factory’s relayer dep).

​
Burn variants

  • encrypted_balance — burn into an EncryptedTokenAccount. Requires additional Rescue-encrypted fee fields in proof_account_data. Each note slot has 6 linker encryptions and 6 key commitments.
  • public_balance — burn into a AssociatedTokenAccount. Requires fee_proof_data with the client’s expected basis-points rates (protocol_fee_basis_points, relayer_fee_basis_points) and allowed-address PDA slots — the relayer verifies these against the on-chain FeeSchedule / RelayerFeeSchedule PDAs before submission, catching stale client config without wasting a transaction. Each note slot has 5 linker encryptions and 5 key commitments.

​
Validation rules

  • All base58 pubkeys must decode to exactly 32 bytes.
  • All nullifiers within a request must be unique (duplicates return 409 DUPLICATE_OFFSET).
  • max_utxo_capacity must be greater than 0.
  • fee_proof_data is required for public_balance variant only.

​
Idempotency / DUPLICATE_OFFSET

If a burn callback drops and you re-submit with the same request_id while the nullifier is still reserved upstream, the relayer returns HTTP 409 with code DUPLICATE_OFFSET. Wait, re-check on-chain that the nullifier has not landed, and retry only if still unspent. The SDK’s burner factories handle this internally.

Body

application/json
​
variant
enum<string>
required

Claim target — encrypted token account or public ATA.

Available options:
encrypted_balance,
public_balance
​
user_pubkey
string
required

Base58-encoded Solana public key of the claiming user.

​
mint
string
required

Base58-encoded token mint address.

​
stealth_pool_index
integer<int64>
required

Index of the stealth pool containing the UTXOs.

​
max_utxo_capacity
integer
required

Maximum number of UTXOs in this claim batch.

Required range: x >= 1
​
optional_data
string
required

Base64-encoded 32-byte metadata field.

​
proof_account_data
object
required

Cryptographic proof data for the claim.

​
utxo_slot_data
object[]
required

Array of UTXO slots to claim.

Minimum array length: 1
​
fee_proof_data
object

Fee Merkle proof data. Required for public_balance variant only.

Response

Claim accepted and queued for processing

​
request_id
string<uuid>

UUID for polling the claim status.

​
status
enum<string>

Always "received".

Available options:
received