Check RWA eligibility

Decide whether a wallet can enter or exit a real-world-asset yield before you build the action.

Decide whether a specific wallet can enter, or exit, a specific real-world-asset (RWA) yield before you call POST /v1/actions/enter or /exit, so your UI shows the right state instead of relying on a failed action request. An RWA yield’s eligibility rules are set by its issuer, per product, and are enforced at two independent layers: the caller’s location and the wallet’s own compliance status.

This guide covers deciding eligibility. To build and submit the enter or exit action once a wallet is eligible, see Deposit and redeem RWAs.

Prerequisites

• A yield.xyz API key, sent as x-api-key on every request.
• An RWA yield enabled for your project. See Discover yields.
• The wallet address you’re checking eligibility for.

1. Discover the yield and read its requirements

   Query GET /v1/yields?types=real_world_asset for the RWA yields enabled for your project, project-scoped like every yield endpoint, then read the yield’s mechanics.requirements block:

   cURL

   curl --request GET \
     --url https://api.yield.xyz/v1/yields/ethereum-usdc-nest-ntbill-vault \
     --header "x-api-key: $YIELD_API_KEY"
   

   Response (excerpt)

   {
     "id": "ethereum-usdc-nest-ntbill-vault",
     "status": { "enter": true, "exit": true },
     "mechanics": {
       "requirements": {
         "kycRequired": true,
         "kyc": {
           "kycMode": "external_redirect",
           "authorizeUrl": "https://app.nest.credit",
           "eligibility": {
             "defaultPolicy": "allow",
             "blockedCountries": ["US", "CU", "IR", "KP", "RU", "SY"],
             "usPersonAllowed": false,
             "geoBlockingEnforced": true,
             "investorEligibility": [],
             "subjectTypes": ["KYC", "KYB"]
           }
         }
       }
     }
   }
   

   mechanics.requirements.kycRequired tells you whether this product gates entry behind off-chain verification at all. When it’s true, mechanics.requirements.kyc carries the rest: kycMode (how the issuer’s flow is delivered), authorizeUrl (where to send the user), and eligibility (defaultPolicy, the country and subdivision lists, usPersonAllowed, geoBlockingEnforced, investorEligibility tiers, and accepted subjectTypes). See KYC for what every field in this block means; the blocked-country list above is Nest’s own, not a fixed rule.

2. Check the wallet's KYC status

   Call GET /v1/yields/{yieldId}/kyc/status with the wallet’s address as a query parameter. It returns a status for every RWA yield, including ones that don’t require KYC:

   cURL

   curl --request GET \
     --url 'https://api.yield.xyz/v1/yields/ethereum-usdc-nest-ntbill-vault/kyc/status?address=0xYOUR_WALLET_ADDRESS' \
     --header "x-api-key: $YIELD_API_KEY"
   

   Response (excerpt)

   {
     "kycStatus": "not_started",
     "authorizeUrl": "https://app.nest.credit"
   }
   

   kycStatus is one of not_required, not_started, pending, approved, or rejected; see KYC for what each one means. pending is declared but no current issuer returns it. authorizeUrl is optional: it is present only when the issuer provides an onboarding page, typically with not_started or rejected.

3. Route the wallet on the result

   • not_required or approved: the wallet can proceed. Move on to building the enter action.
   • not_started: send the wallet to authorizeUrl, if present, to complete the issuer’s onboarding, then poll this endpoint again before retrying the action. Treat pending the same way if you handle it, although no current issuer returns it.
   • rejected: the issuer has declined the wallet, or (for a yield with kycRequired: false) its module screened the address against an on-chain deny-list. Don’t offer an enter or exit button. authorizeUrl is present for some issuers and absent for others, so check for it before linking.

Distinguish a geo-block from a KYC rejection

Both failures reach you as an error on the action call itself, but they mean different things and carry different HTTP status codes:

Cause	Enforced by	Response	What it means
Caller’s IP is in a banned region (yield.xyz’s mandatory list, your project’s own list, or the yield’s own blockedCountries when geoBlockingEnforced is true)	The geolocation guard on enter, exit, manage, and the enter and exit simulate routes	403 Forbidden, {"message": "Access denied from <country>", "error": "Forbidden", "statusCode": 403}	A location control, independent of wallet identity. See Geo-blocking
Wallet isn’t allowlisted by the issuer	A pre-flight compliance check some integrations run before building a transaction	412 Precondition Failed, error details carry address, protocol (the issuer’s name), and authorizeUrl when the issuer has an onboarding flow	Investor eligibility, checked against the wallet, not the request’s origin

If you call the Yield API from your own backend rather than directly from the end user’s device, forward the end user’s IP in X-Forwarded-For. Otherwise geo-blocking evaluates your server’s location instead of theirs. See Geo-blocking.

Not every issuer’s pre-flight rejection looks the same:

• Most KYC-gated issuers (Midas, Nest, Ondo, Securitize, Superstate) return a 412 whose details carry an authorizeUrl, so you can route the user straight to onboarding.
• Dinari’s USD+ has kycRequired: false; there’s no onboarding flow at all. Instead, yield.xyz checks the address against USD+‘s on-chain deny-list before building a transaction, and a restricted address gets a 412 with address and protocol but no authorizeUrl. There’s nowhere to send that wallet.
• Not every RWA module runs a pre-flight check at all. Where one doesn’t, an ineligible wallet only finds out when the built transaction reverts on-chain, not from a 412 on the action request. Read mechanics.requirements.kyc before assuming an issuer’s absence from this list means the yield is unconditionally open.

These two error shapes aren’t a documented API contract you should pattern-match on: treat the HTTP status (403 vs 412) as the reliable signal, and use /kyc/status ahead of time so you show the right state instead of parsing a rejection.

A permissionless yield can still reject a wallet

kycRequired: false means there’s no off-chain verification step, not that every wallet can transact. Midas sets kycRequired: false on mTBILL and mROX, but still checks every wallet against that product’s on-chain greenlist (where the issuer has one enabled), blacklist, and sanctions list before building a transaction; a blocked wallet gets the same 412 shape as a KYC-gated Midas product, without a URL to send it to. Nest’s own KYC metadata describes its flow as “permissionless for eligible users”: there’s no manual review queue, but every wallet is still screened on-chain by Plume’s AML and Predicate policy before Nest builds a transaction. In both cases, the issuer’s own metadata lists what’s blocked, and that policy is set by the issuer, not by yield.xyz.

Next steps

Deposit and redeem RWAs

Build the enter action once the wallet is eligible, then track the position through exit.

KYC

The full eligibility model: every field in the kyc metadata block and what it describes.

Geo-blocking

Configure your project’s own region restrictions on top of yield.xyz’s mandatory list.

Issuers

Which issuers require KYC per product, and which don’t.