Skip to content
YutaiDocs
GET /v1/statusGet API key

API reference / API reference

Read the benefits one or more wallets reach

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

GET/v1/eligibilityCallable today

The key presents the eligibility.read scope.

The parameters

wallets
Required. The wallet addresses to read: one or more, at most 20 in one read, each an EVM 0x address or a Solana address. It sits in the query.

What it answers

The wallets the request named, each with its tokens and the benefits they reach. The claimed state is the one fact the answer carries at the holder level: a benefit the holder the wallet is linked to has claimed reads claimed on every wallet that carries it, so wallets that share it show one fact about their holder.

  • wallets

    Required. A list of objects with the fields below. It carries at least 1 and at most 20 items.

    • Each item

      Required. An object with the fields below.

      • wallet

        The wallet address the request named, in the spelling it sent.

        Required. A string.

      • read

        Whether Yutai read the wallet at all; false when the wallet could not be read.

        Required. True or false.

      • sourceMode

        The data mode the read answered in: SIMULATED, SANDBOX or LIVE.

        Required. A string that is one of the values below.

        • SIMULATED
        • SANDBOX
        • LIVE

      • tokens

        The tokens the wallet's own trail answers, each with the benefits it reaches; present when the wallet was read.

        Optional. A list of objects with the fields below. It carries at most 200 items.

        • Each item

          Required. An object with the fields below.

          • issuer

            The issuer that mints the token, or null when no issuer is recorded.

            Required. A string. It may also be null.

          • security

            The security the token's mapping names, with its name and its ISIN.

            Required. An object with the fields below.

            • name

              Required. A string. It carries at least 1 and at most 256 characters.

            • isin

              Required. A string.

          • wrapper

            The wrapper programme that carries the token.

            Required. A string. It carries at least 1 and at most 128 characters.

          • chain

            The chain the token trades on, as its CAIP-2 id.

            Required. A string.

          • shares

            The wallet's holding as a decimal string at the token's own decimals, never a JSON number.

            Required. A string.

          • daysHeld

            Whole days the wallet has held the security without selling; counts toward the tier.

            Required. A whole number, at least 0.

          • tier

            The programme tier the wallet's own trail answers, or null when no tier stands.

            Required. A string. It may also be null.

          • benefits

            The benefits the holding reaches, each with its state and its illustrative flag.

            Required. A list of objects with the fields below. It carries at most 500 items.

            • Each item

              Required. An object with the fields below.

              • benefitId

                Required. A string.

              • name

                Required. A string. It carries at least 1 and at most 128 characters.

              • type

                Required. A string that is one of the values below.

                • DISCOUNT_CODE
                • EXPERIENCE
                • POINTS
                • VOUCHER
                • ACCESS
                • DIGITAL_COLLECTIBLE
                • STOCK_REWARD

              • delivery

                Required. A string that is one of the values below.

                • CODE
                • POINTS_CREDIT
                • VENUE_REDEMPTION
                • CHAIN_MINT
                • TOKEN_TRANSFER

              • state

                Required. A string that is one of the values below.

                • eligible
                • locked
                • claimed
                • redeemed
                • unavailable

              • illustrative

                Required. True or false.

              • lockedReason

                Optional. A string. It carries at least 1 and at most 512 characters.

      • unreadReason

        Why the wallet could not be read; present only when read is false.

        Optional. A string. It carries at least 1 and at most 512 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 GET /v1/eligibility answers
StatusWhat it answers
400The query could not be read.
401The key is missing, malformed, unknown, revoked or expired.
403The key does not carry the scope, or the wallets name chains outside the distributor's scope. 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, or the platform has used today's live wallet reads; the Retry-After header names the seconds until the next window opens, or until the reads open again. Nothing was read.
500The read failed inside Yutai. Nothing was changed.
503The data source this read needs is not live yet, or the owners' blockchain switch does not allow the read, so the read is refused. Nothing was read.