Skip to content
YutaiDocs
GET /v1/statusGet API key

API reference / API reference

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.

View as .md

The call

POST/v1/claims/challengeCallable today

The key presents the claims.write scope.

The get started page shows how a platform gets a key.

The body

benefitId
Required. The benefit the challenge asks a claim for: the id the eligibility read named.
wallets
Required. The wallets the challenge covers, each once, up to the cap this field carries. It carries at least 1 and at most 20 items.

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.

  • message

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

  • nonce

    The one-time nonce to hand the holder's page beside the message: single use, and Yutai stores only its digest.

    Required. A string.

  • wallets

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

  • expiresAt

    The 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 three fields: message, the plain sentence that says what did not happen; code, the closed refusal code the call log records beside the call; and requestId, the id to quote when asking Yutai about the call. The message carries 1 to 512 characters, the code 1 to 64 characters, and the request id 1 to 64 characters. Every answer carries the same id on its X-Request-Id header.

The errors the call for POST /v1/claims/challenge answers
StatusWhat it answers
400The request body could not be read.
401The key is missing, malformed, unknown, revoked or expired.
403The 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.
429The key made too many calls this minute. The Retry-After header names the seconds until the next window opens. Nothing was read.
500The challenge was not issued, so nothing is ready to sign. Nothing was changed.

The errors and limits page carries every refusal status the document declares, each in its own words, beside the calls that answer it.