Skip to main content
Get claim status
curl --request GET \
  --url https://relayer.api.umbraprivacy.com/v1/claims/{request_id}
{
  "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"
}
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.
The wire path retains the legacy /v1/claims/{request_id} segment. In 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).

​
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.

Path Parameters

​
request_id
string<uuid>
required

UUID returned from POST /v1/claims.

Response

Claim status

​
request_id
string<uuid>
​
status
enum<string>
Available options:
received,
validating,
offsets_reserved,
building_tx,
tx_built,
submitting,
submitted,
awaiting_callback,
callback_received,
finalizing,
completed,
failed,
timed_out
​
variant
enum<string>
Available options:
encrypted_balance,
public_balance
​
resolved_variant
string | null

Specific on-chain instruction variant selected by preflight validator.

​
tx_signature
string | null

Solana transaction signature of the claim instruction.

​
callback_signature
string | null

Solana transaction signature of the Arcium MPC callback.

​
computation_account
string | null

Base58-encoded computation account address.

​
failure_reason
string | null

Error message if status is failed.

​
created_at
string<date-time>
​
updated_at
string<date-time>