---
title: "Submit a claim request"
method: POST
path: "/v1/claims"
tags: ["claims"]
---

# Submit a claim request

`POST /v1/claims`

Submits a UTXO claim request to the relayer for asynchronous processing. The relayer
validates the request, builds the on-chain transactions, and submits them.

Returns immediately with a `request_id` for polling via `GET /v1/claims/{request_id}`.

**Note:** This endpoint is designed to be called by the SDK, not directly. The request
body contains cryptographic proof data that must be generated by the SDK's claim functions.

## Request body

- ClaimRequest
  - `variant` 'encrypted_balance' | 'public_balance', required — Claim target — encrypted token account or public ATA.
  - `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, required — Index of the stealth pool containing the UTXOs.
  - `max_utxo_capacity` integer, required — Maximum number of UTXOs in this claim batch.
  - `optional_data` string, required — Base64-encoded 32-byte metadata field.
  - `proof_account_data` ProofAccountData, required — Cryptographic proof data for the claim.
    - `rescue_encryption_public_key` string — Base64-encoded 32-byte X25519 public key.
    - `encryption_nonce` string — Decimal-encoded u128 Rescue cipher nonce.
    - `merkle_root` string — Base64-encoded 32-byte Poseidon Merkle root.
    - `tvk_timestamp` integer — Temporal viewing key timestamp.
    - `groth16_proof_a` string — Base64-encoded 64-byte Groth16 proof element A.
    - `groth16_proof_b` string — Base64-encoded 128-byte Groth16 proof element B.
    - `groth16_proof_c` string — Base64-encoded 64-byte Groth16 proof element C.
    - `rescue_encryption_commitment` string — Base64-encoded 32-byte encryption commitment.
    - `encryption_validation_polynomial` string — Base64-encoded 32-byte polynomial.
    - `rescue_encrypted_master_viewing_key_low` string — Base64-encoded encrypted MVK low half.
    - `rescue_encrypted_master_viewing_key_high` string — Base64-encoded encrypted MVK high half.
    - `rescue_encrypted_blinding_factor_low` string — Base64-encoded encrypted blinding factor low half.
    - `rescue_encrypted_blinding_factor_high` string — Base64-encoded encrypted blinding factor high half.
    - `rescue_encrypted_total_amount` string — Base64-encoded 32-byte encrypted amount (encrypted_balance only).
    - `rescue_encrypted_relayer_commission_fee` string — Base64-encoded encrypted relayer fee (encrypted_balance only).
    - `rescue_encrypted_protocol_commission_fee` string — Base64-encoded encrypted protocol fee (encrypted_balance only).
    - `total_relayer_fees` integer — Total relayer fees in token base units (encrypted_balance only).
  - `utxo_slot_data` UtxoSlotData[], required — Array of UTXO slots to claim.
    - `slot_index` integer — Position of this UTXO in the batch.
    - `nullifier` string — Base64-encoded 32-byte nullifier. Must be unique within the request.
    - `linker_encryptions` string[] — Base64-encoded Poseidon linker encryptions (6 for encrypted_balance, 5 for public_balance).
    - `linker_key_commitments` string[] — Base64-encoded Poseidon key commitments (6 for encrypted_balance, 5 for public_balance).
  - `fee_proof_data` FeeProofData — Fee Merkle proof data. Required for public_balance variant only.
    - `amount` string — Claim amount.
    - `relayer_fixed_sol_fees` string — SOL fees in lamports.
    - `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` integer
    - `protocol_fees_merkle_path` string[] — Four sibling hashes for fee schedule proof.
    - `protocol_fees_leaf_index` integer
    - `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` integer
    - `relayer_fees_merkle_path` string[] — Four sibling hashes for relayer fee schedule proof.
    - `relayer_fees_leaf_index` integer

## Response `202`

Claim accepted and queued for processing

- object
  - `request_id` string, uuid — UUID for polling the claim status.
  - `status` 'received' — Always "received".

## Other responses

- `400` — Invalid request
- `409` — Duplicate nullifier
- `500` — Internal server error

---

[API](https://skmtc.net/umbra-defi/apis/umbra-relayer-api.md) · [All operations](https://skmtc.net/umbra-defi/apis/umbra-relayer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/umbra-defi/umbra-relayer-api/revisions/d973e56013e5/schema)