# 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](/docs/identifiers)'s.

## The call

GET `/v1/eligibility` Callable today

The key presents the `eligibility.read` scope.

The get started page shows [how a platform gets a key](/docs/get-started#key-heading).

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

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

| 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 inside Yutai. 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](/docs/errors#statuses-heading), each in its own words, beside the calls that answer it.