# Record a claim a wallet's own signature or a distributor's signed statement stands behind

One call of the distributor API, read from the interface description Yutai publishes. Every sample answer on this page is simulated: no real holder's data stands behind it. The formats every value travels in are the [identifiers page](/docs/identifiers)'s.

## The call

POST `/v1/claims` Callable today

The key presents the `claims.write` scope.

## The body

`benefitId`: The wallet proof: the benefit the claim stands on, the wallet that signs the challenge, the challenge's one-time nonce and the signature over the challenge's own message. Required. The benefit the claim stands on: its id, the one the eligibility read named.

`wallet`: The wallet proof: the benefit the claim stands on, the wallet that signs the challenge, the challenge's one-time nonce and the signature over the challenge's own message. Required. The wallet that signs the claim: the one address the challenge named, EVM or Solana.

`nonce`: The wallet proof: the benefit the claim stands on, the wallet that signs the challenge, the challenge's one-time nonce and the signature over the challenge's own message. Required. The challenge's one-time nonce, the one the challenge call returned once.

`signature`: The wallet proof: the benefit the claim stands on, the wallet that signs the challenge, the challenge's one-time nonce and the signature over the challenge's own message. Required. The proof over the challenge's message, as the wallet signed it. Yutai re-reads every rule at claim time.

`benefitId`: The attested ask: a custodial distributor claims a benefit for its own customer by presenting the signed statement its own key signs. Yutai re-checks the statement and every rule at claim time, so the answer reflects the world as it stands. Required. The benefit the claim stands on: its id, the one the eligibility read named.

`subject`: The attested ask: a custodial distributor claims a benefit for its own customer by presenting the signed statement its own key signs. Yutai re-checks the statement and every rule at claim time, so the answer reflects the world as it stands. Required. The attested subject the claim is about: the one subject the eligibility read's request carries. The distributor's own key presents the statement its own system signed, with the id of the registered key that verified it, the instant the call was made, and the venue and the account the statement binds, each once; the request's own fields must name the statement's own venue and account, and Yutai re-checks the statement and every rule at claim time. The statement's own shapes stand in the contracts beside the wallet read's and on the sign a balance statement page, which documents the exact message the signature binds; this document names no balance.

## What it answers

The claim's answer: granted, with the claim's own facts - its id, the wallets that signed it, the instant it was recorded and the decision behind it - or refused, when the holder's own world refused the claim, with the reason beside the same decision. The granted answer carries the code the benefit delivers, when it delivers by code, and the holder's private redemption link, on the first grant only. A retry of the same challenge answers the one claim it already recorded, marked alreadyClaimed, and so does a statement whose account already stands for the claim.

The answer is one of 2 shapes: the fields each shape carries stand under it.

- `status` The granted answer's own word: always claimed. Required. It always carries the value below. `claimed`
- `claimId` The claim's own opaque id, the address the claim read answers at. Required. A string.
- `benefitId` The benefit the claim was granted for, by its own opaque id. Required. A string.
- `venueId` The venue that asked, by its own tenant id; no other venue's claim answers it. Required. A string.
- `subjectKeys` The wallets the claim's challenge named, the ones the venue itself saw; never the holder's other wallets. Required. A list of strings. It carries at most 64 items.
- `alreadyClaimed` True when this call replayed a claim already recorded and false on the first grant; the same call answers the same words twice. Required. True or false.
- `createdAt` The instant Yutai recorded the claim and its decision, as an ISO 8601 string. Required. An instant in the ISO 8601 form.
- `code` The code the holder redeems, present only when the benefit delivers by code; a replay answers the same code, never a second take. Optional. A string. It carries at least 1 and at most 128 characters.
- `link` The holder's private redemption link, present on the first grant only; a replay carries no link. Optional. A string. It carries at least 1 and at most 512 characters.
- `decision` The claim's own decision: whether the benefit's rules granted it, with only the notes the eligibility read and the challenge already answer a venue. Required. An object with the fields below. `eligible` Required. True or false. `tree` Required. A list of objects with the fields below. It carries at most 64 items. `Each item` Required. An object with the fields below. `kind` Required. A string that is one of the values below. `tenure` `holding` `country` `spend` `consent` `venue` `holds` `holds_any` `holds_all` `holds_count` `window` `stock` `authorisation_active` `not_paused` `recipient_evm` `not_already_claimed` `attestation_given` `jurisdiction` `recipient_rules` `met` Required. True or false. `note` Required. A string. It carries at least 1 and at most 512 characters. `simulatedInputs` Optional. A list of objects with the fields below. It carries at most 576 items. `Each item` Required. An object with the fields below. `kind` Required. A string that is one of the values below. `tenure` `position` `country` `spend` `consent` `venue` `holding` `price` `stock` `securityId` Optional. A string. It carries at least 1 and at most 256 characters. `children` Optional. A list of the same shapes the tree carries above. It carries at most 64 items. `simulatedInputs` Optional. A list of objects with the fields below. It carries at most 576 items. `Each item` Required. An object with the fields below. `kind` Required. A string that is one of the values below. `tenure` `position` `country` `spend` `consent` `venue` `holding` `price` `stock` `securityId` Optional. A string. It carries at least 1 and at most 256 characters.

- `status` The refused answer's own word: always refused. Required. It always carries the value below. `refused`
- `reason` Why the claim was refused, one of the closed list of plain reasons a venue branches on. Required. A string that is one of the values below. `unknown_challenge` `other_venue` `other_benefit` `not_consumed` `no_holder` `conflicting_holders` `unknown_benefit` `no_offer` `already_claimed` `not_eligible`
- `decision` The benefit's decision, present only when the world itself refused (the rulebook, the holdings trail or the country); an already claimed refusal carries none. Optional. An object with the fields below. `eligible` Required. True or false. `tree` Required. A list of objects with the fields below. It carries at most 64 items. `Each item` Required. An object with the fields below. `kind` Required. A string that is one of the values below. `tenure` `holding` `country` `spend` `consent` `venue` `holds` `holds_any` `holds_all` `holds_count` `window` `stock` `authorisation_active` `not_paused` `recipient_evm` `not_already_claimed` `attestation_given` `jurisdiction` `recipient_rules` `met` Required. True or false. `note` Required. A string. It carries at least 1 and at most 512 characters. `simulatedInputs` Optional. A list of objects with the fields below. It carries at most 576 items. `Each item` Required. An object with the fields below. `kind` Required. A string that is one of the values below. `tenure` `position` `country` `spend` `consent` `venue` `holding` `price` `stock` `securityId` Optional. A string. It carries at least 1 and at most 256 characters. `children` Optional. A list of the same shapes the tree carries above. It carries at most 64 items. `simulatedInputs` Optional. A list of objects with the fields below. It carries at most 576 items. `Each item` Required. An object with the fields below. `kind` Required. A string that is one of the values below. `tenure` `position` `country` `spend` `consent` `venue` `holding` `price` `stock` `securityId` Optional. A string. It carries at least 1 and at most 256 characters.

## The errors

Every refused call answers one object with one field, message: the plain sentence that says what did not happen. The sentence carries 1 to 512 characters, so a refusal never carries an id, a code or an exception's text.

| Status | What it answers |

| --- | --- |

| 400 | The request body could not be read. |

| 401 | The key is missing, malformed, unknown, revoked or expired. |

| 403 | The key does not carry the scope, or the claim itself was refused: the challenge was never verified, was issued for another distributor or another benefit, or the holder's own world refused the claim, and the attested subject's statement the same - unsigned or unverifiable, expired, naming an instrument the distributor does not list or the registry no longer keeps active, naming another tenant, or for a benefit the account's holder already claimed once. The call is also refused with 403, nothing read, when the distributor is paused, suspended or closed, when the key is paused, or when the key presents from an origin it does not allow. |

| 429 | The key made too many calls this minute. The Retry-After header names the seconds until the next window opens. Nothing was read. |

| 500 | The read failed inside Yutai. Nothing was changed. |