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 get started page shows how a platform gets a key.

The parameters

wallets: Required. The wallet addresses to read: one or more, at most 20 in one read, each an EVM 0x address, a Solana address or a TRON 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
  - asOf
    The instant of the newest price quote behind the wallet's tokens, in the ISO 8601 form, present only when the read priced a held security. It carries the quote's instant, never the price.
    Optional. An instant in the ISO 8601 form.
  - 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, its ISIN and its ticker.
        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.
        ticker
        The security's ticker as the registry records it, or null when it records none.
        Required. A string. It carries at least 1 and at most 16 characters. It may also be null.
      - symbol
        The token's own symbol, like NVDAon.
        Required. A string. It carries at least 1 and at most 16 characters.
      - chainName
        The chain's own name from the platform's one chain-name table, never its CAIP-2 id.
        Required. A string. It carries at least 1 and at most 128 characters.
      - 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.
      - credentialTier
        The credential tier the answered programme tier bound at create, or null when it carries no binding.
        Required. A string that is one of the values below. It may also be null.
        Tier 1
        Tier 2
        Tier 3
      - progress
        The tier clock's progress toward the next rung, through the one resolver and the one progress derivation; absent when no true days bar stands.
        Optional. An object with the fields below.
        nextTier
        The tier the clock is moving toward, or null at the top of the ladder.
        Required. A string that is one of the values below. It may also be null.
        Tier 1
        Tier 2
        Tier 3
        daysHeld
        Whole days the next rung's own clock has run.
        Required. A whole number, at least 0.
        progressPercent
        The share of the next rung's days already held, in whole percents rounded down.
        Required. A whole number, from 0 to 100.
      - 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
        REWARD_FULFILMENT
        state
        Required. A string that is one of the values below.
        eligible
        locked
        claimed
        redeemed
        unavailable
        illustrative
        Required. True or false.
        scope
        Who the offer is shown to: base for every distributor, distributor for the distributors it names.
        Required. A string that is one of the values below.
        base
        distributor
        funder
        Who funds the offer: Yutai, its issuer, a distributor or a brand.
        Required. A string that is one of the values below.
        YUTAI
        ISSUER
        DISTRIBUTOR
        BRAND
        plus
        The Yutai Plus facts, present only on a distributor-scoped offer the calling key's own distributor may see; absent on every base offer and on every other distributor's answer.
        Optional. An object with the fields below.
        distributorName
        The distributor's own name from Yutai's member record, the name the Plus offer stands under.
        Required. A string. It carries at least 1 and at most 128 characters.
        progress
        The wallet's streak toward the tier that asks days; present only on an eligibility answer and only when that tier asks days.
        Optional. An object with the fields below.
        streakDays
        Whole days the wallet has held the security, the one clock the tier reads.
        Required. A whole number, at least 0.
        requiredDays
        The whole days the tier asks for.
        Required. A whole number.
        rewardTiers
        The programme's reward tiers in ladder order, each with the one short requirement sentence.
        Required. A list of objects with the fields below. It carries at most 64 items.
        Each item
        Required. An object with the fields below.
        name
        The tier's name as the programme carries it.
        Required. A string. It carries at least 1 and at most 128 characters.
        requirement
        The one short sentence the tier's holding and days read as.
        Required. A string. It carries at least 1 and at most 512 characters.
        lockedReason
        Optional. A string. It carries at least 1 and at most 512 characters.
      - source
        The lending protocol whose positions the token carries, as its source word: defi:kamino, defi:jupiter, defi:morpho or defi:euler; present exactly when positions stands.
        Optional. A string that is one of the values below.
        defi:kamino
        defi:jupiter
        defi:morpho
        defi:euler
      - positions
        Where the token's units sit when a lending protocol carries some of them, each location once in the closed order; absent when the whole holding sits in the wallet.
        Optional. A list of objects with the fields below. It carries at most 13 items.
        Each item
        Required. An object with the fields below.
        location
        Where the units sit: the wallet itself, a lending protocol's supplied units, its obligation collateral, or its borrowed units.
        Required. A string that is one of the values below.
        wallet
        kamino_supplied
        kamino_collateral
        kamino_borrowed
        jupiter_supplied
        jupiter_collateral
        jupiter_borrowed
        morpho_supplied
        morpho_collateral
        morpho_borrowed
        euler_supplied
        euler_collateral
        euler_borrowed
        units
        The units at this location as an exact decimal string at the token's own decimals; borrowed units are negative.
        Required. A string.
        countsForEligibility
        Whether the units count towards the holding: true for the wallet and both lent locations, false for borrowed units.
        Required. True or false.
      - breakdown
        One plain sentence saying where the units sit, built from the same positions; absent when the whole holding sits in the wallet.
        Optional. A string. It carries at least 1 and at most 512 characters.
  - skippedChains
    The chains the wallet's stored trail shows it has held on that this distributor does not serve, as CAIP-2 ids, each once and sorted; present only when the stored trail names one, and never on an unread wallet.
    Optional. A list of strings. It carries at least 1 and at most 64 items.
  - 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 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 GET /v1/eligibility answers
Status	What it answers
400	The query could not be read.
401	The key is missing, malformed, unknown, revoked or expired.
403	The key does not carry the scope, or the wallets name no chain the distributor serves. 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, 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.
500	The read failed. Nothing was changed.
503	The 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.

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

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/eligibility?wallets=0xabc0000000000000000000000000000000000001" \
  -H "Authorization: Bearer ytk_your-key"

The sample answer for GET /v1/eligibility

{
  "wallets": [
    {
      "wallet": "0xabc0000000000000000000000000000000000001",
      "read": true,
      "sourceMode": "SIMULATED",
      "asOf": "2026-10-08T12:00:00.000Z",
      "tokens": [
        {
          "issuer": null,
          "security": {
            "name": "Sample Global Holdings",
            "isin": "US0000000009",
            "ticker": "SGH"
          },
          "symbol": "SGHon",
          "chainName": "chiliz-testnet",
          "wrapper": "Sample token programme",
          "chain": "eip155:88880",
          "shares": "15",
          "daysHeld": 452,
          "tier": "Tier 2",
          "credentialTier": "Tier 2",
          "progress": {
            "nextTier": "Tier 3",
            "daysHeld": 452,
            "progressPercent": 11
          },
          "source": "defi:kamino",
          "positions": [
            {
              "location": "wallet",
              "units": "10",
              "countsForEligibility": true
            },
            {
              "location": "kamino_supplied",
              "units": "2",
              "countsForEligibility": true
            },
            {
              "location": "kamino_collateral",
              "units": "4",
              "countsForEligibility": true
            },
            {
              "location": "kamino_borrowed",
              "units": "-1",
              "countsForEligibility": false
            }
          ],
          "breakdown": "In wallet 10, lent on Kamino 6, borrowed 1.",
          "benefits": [
            {
              "benefitId": "bft_01K4V9QG000000000000000001",
              "name": "Sample lounge access",
              "type": "ACCESS",
              "delivery": "VENUE_REDEMPTION",
              "state": "eligible",
              "illustrative": true,
              "scope": "base",
              "funder": "YUTAI"
            }
          ]
        }
      ]
    },
    {
      "wallet": "0xdef0000000000000000000000000000000000002",
      "read": false,
      "sourceMode": "SIMULATED",
      "unreadReason": "Yutai has not read this wallet yet."
    }
  ]
}