Claim a benefit

Ask for the message to sign

Send the benefit id and the wallets that will sign. The answer carries the exact message to sign and a one-time nonce. The message names the benefit and each wallet, and the nonce stands for one claim only, so a signature cannot be moved to another claim.

The wallet signs the message as it stands. Signing moves nothing and approves nothing.

{
  "benefitId": "bft_01K4V9QG000000000000000001",
  "wallets": [
    "0xabc0000000000000000000000000000000000001"
  ]
}

{
  "message": "Yutai claim challenge\nTenant: tnt_01K4V9QG000000000000000001\nVenue: Sample venue (tnt_01K4V9QG000000000000000002)\nBenefit: Sample lounge access (bft_01K4V9QG000000000000000001)\nWallet: 0xabc0000000000000000000000000000000000001\nNonce digest: 0xa1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4\nExpires: 2026-10-11T12:05:00.000Z\nSigning moves nothing and approves nothing.",
  "nonce": "9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "wallets": [
    "0xabc0000000000000000000000000000000000001"
  ],
  "expiresAt": "2026-10-11T12:05:00.000Z"
}

Make the claim

Sign the message with the wallet the challenge named, then send the benefit id, that wallet, the nonce and the signature. Yutai re-checks every rule at claim time, so an earlier eligibility answer never stands for one. A granted claim answers claimed with the claim's own id; a refused one answers refused with a reason.

The exchange example runs this part as working code: it asks for the challenge, has the example wallet sign, records the claim and reads the answer back. Follow it at Example exchange; this page never copies its code.

{
  "benefitId": "bft_01K4V9QG000000000000000001",
  "wallet": "0xabc0000000000000000000000000000000000001",
  "nonce": "9f8e7d6c5b4a39281706f5e4d3c2b1a0",
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}

{
  "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."
      }
    ]
  }
}

Refusal reasons

Every reason the claim call can refuse with, in the contract's own order. Each reason is one word a caller branches on, and the sentence beside it is the one the SDK draws for that reason.

The decision rides a refusal only when the world itself refused, as with not_eligible and the reasons the benefit's own rulebook, holdings trail or country give. An already_claimed refusal carries none. The errors and limits page carries every refusal status the calls answer, each in its own words.

Retry a claim

A claim is keyed by the challenge it carries, so one challenge can never mint a second claim. A retry of the same call answers the stored claim with alreadyClaimed true and the first grant's own createdAt, so the same call answers the same words twice.

A new challenge from the distributor that recorded the claim answers that claim again with alreadyClaimed true.

When another distributor holds the claim, the answer is the refusal already_claimed, with no decision beside it.

A granted answer carries the claim's own facts, and the holder's code or link when the benefit delivers one. Each field below carries the contract's own words:

alreadyClaimed

True when this call replayed a claim already recorded and false on the first grant; the same call answers the same words twice.

createdAt

The instant Yutai recorded the claim and its decision, as an ISO 8601 string.

code

The code the holder redeems, present only when the benefit delivers by code; a replay answers the same code, never a second take.

link

The holder's private redemption link, present on the first grant only; a replay carries no link.

A distributor that lost the link reissues one with the link call.

Read a claim and reissue its link

Read the claim by the id the claim answered, to see its state and its benefit in words. Reissue the link when the holder needs a fresh redemption link: only the last link issued opens the claim, so an earlier one stops working, and a rejected or taken back claim answers a refusal.

{
  "claimId": "clm_01K4V9QG000000000000000001",
  "benefitId": "bft_01K4V9QG000000000000000001",
  "benefitName": "Sample lounge access",
  "state": "granted",
  "createdAt": "2026-10-08T12:00:00.000Z"
}

{
  "claimId": "clm_01K4V9QG000000000000000001",
  "link": "https://app.yutai.com/r/clm_01K4V9QG000000000000000001?t=sample-redemption-token-0000000000000000000"
}

A reissue that fails inside Yutai answers in its own words: The redemption link was not reissued, so the previous link still stands. Nothing was changed.

Confirm a fulfilment

List the fulfilments that wait on your own word, then confirm one with your own reference for the credit. The confirm marks the fulfilment as credited; a second confirm answers that it was already confirmed, so a retry never credits twice.

{
  "fulfilments": [
    {
      "fulfilmentId": "ful_01K4V9QG000000000000000001",
      "claimId": "clm_01K4V9QG000000000000000001",
      "benefitId": "bft_01K4V9QG000000000000000001",
      "benefitName": "Sample lounge access",
      "state": "waiting on the venue",
      "createdAt": "2026-10-11T12:05:00.000Z"
    }
  ]
}

{
  "venueReference": "Lounge visit 2026-10-08, table 12"
}

{
  "fulfilmentId": "ful_01K4V9QG000000000000000001",
  "claimId": "clm_01K4V9QG000000000000000001",
  "benefitId": "bft_01K4V9QG000000000000000001",
  "benefitName": "Sample lounge access",
  "state": "waiting on the venue",
  "createdAt": "2026-10-11T12:05:00.000Z"
}