Ask for the challenge a wallet signs to claim a benefit
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.
The call
/v1/claims/challenge
The key presents the claims.write scope.
The body
benefitId- Required. The benefit the claim stands on: its id, the one the eligibility read named.
wallets- Required. The wallets the challenge binds the proof to: one or more, at most 20 in one ask.
What it answers
The challenge: the exact message the holder signs, the one-time nonce to hand the page beside it, the wallets the proof binds to, and the instant the window closes, 300 seconds after the call. The signature proves the wallet owns the address; it moves nothing and approves nothing.
messageThe exact text the holder's wallet signs. Signing moves nothing and approves nothing.
Required. A string. It carries at least 1 and at most 2048 characters.
nonceThe one-time nonce to hand the holder's page beside the message: single use, and Yutai stores only its digest.
Required. A string.
walletsThe wallets the proof binds to, each once, the same list the request named.
Required. A list of strings. It carries at least 1 and at most 20 items.
expiresAtThe instant the challenge stops being accepted, counted from the moment the door issued it.
Required. An instant in the ISO 8601 form.
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 challenge itself was refused: the venue is paused or not a self-custody venue, the benefit is not a claimable offer, or a wallet sits on a chain the venue does not serve. 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. |