API reference / API reference

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's.

View as .md

The call

POST/v1/claimsCallable 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.

The errors the call for POST /v1/claims answers
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.

The call, as a reader copies it: the key it presents stands where your own key stands, and the values are the sample answer's own.

curl "https://api.yutai.com/v1/claims" \
  -X POST \
  -H "Authorization: Bearer ytk_your-key" \
  -H "Content-Type: application/json" \
  -d '{
  "benefitId": "bft_01K4V9QG000000000000000001",
  "wallet": "0xabc0000000000000000000000000000000000001",
  "nonce": "9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}'

The sample answer for POST /v1/claims

{
  "status": "claimed",
  "claimId": "clm_01K4V9QG000000000000000001",
  "benefitId": "bft_01K4V9QG000000000000000001",
  "venueId": "tnt_01K4V9QG000000000000000002",
  "subjectKeys": [
    "evm:0xabc0000000000000000000000000000000000001"
  ],
  "alreadyClaimed": false,
  "createdAt": "2026-10-11T12:05:00.000Z",
  "code": "SAMPLE-LOUNGE-0001",
  "link": "https://app.yutai.com/r/clm_01K4V9QG000000000000000001?t=sample-redemption-token-0000000000000000000",
  "decision": {
    "eligible": true,
    "tree": [
      {
        "kind": "tenure",
        "met": true,
        "note": "The wallet's own trail stands 452 days behind this ask."
      }
    ]
  }
}