RWAKit

Production-ready guide for integrating tokenized real-world asset yields (permissioned and permissionless) — through the Yield.xyz API.

Overview

Real-world asset (RWA) yields give wallets exposure to off-chain, regulated assets — U.S. Treasury bills, money-market funds, private credit pools, and structured carry strategies — through tokenized vaults that settle on-chain.

Yield.xyz exposes every RWA yield through the same lifecycle as any other yield on the platform (enter → accrue → exit). The only thing that varies is whether the underlying issuer requires KYC. That single distinction drives everything else: discovery, error handling, redemption mechanics, and the user-facing onboarding path.

Permissioned (KYC Required)

Issuer enforces an on-chain allowlist. Users complete KYC at the issuer’s portal before deposits or redemptions can settle. Examples: Superstate USTB / USCC, BlackRock BUIDL, Ondo OUSG.

Permissionless (No KYC)

Open ERC-4626-style vaults or issuance contracts. Any address can deposit. Examples: Maple Syrup USDC / USDT, Midas mTBILL, Frax sfrxUSD, Ondo USDY (secondary market).

All RWA yields share type: "real-world-asset" and the same enter / exit action contract. The permissioned vs permissionless split is surfaced through the requirements block on the yield metadata — covered in Identifying RWA Yields.

---

Why RWA Yields

RWA yields complement on-chain native yield in three ways that matter for institutional and treasury workflows:

Regulated backing

Returns sourced from U.S. Treasuries, money-market funds, and private credit — not protocol incentives or reflexive on-chain demand.

Stable yield profile

Lower volatility relative to crypto-native strategies. Yield tracks short-duration rates rather than DeFi cycles.

Composable on-chain

Tokenized vault shares plug into the same wallet, custody, and accounting infrastructure as any ERC-20 — no off-chain settlement on the integrator side.

---

The Integration Model

Every RWA yield — KYC-gated or not — follows the same three-phase lifecycle exposed by the Yield.xyz API.

1. Discover

   Call GET /v1/yields to enumerate enabled yields for your project. Filter on type === "real-world-asset" to isolate the RWA set.

2. Enter

   Call POST /v1/actions/enter with a yield ID, user address, and amount. Yield.xyz returns one or more fully constructed unsigned transactions (typically APPROVAL then DEPOSIT). Sign and submit in order.

3. Exit

   Call POST /v1/actions/exit. Depending on the issuer, redemption is either atomic (instant) or asynchronous (T+1 to T+10, surfaced as a pending balance until settlement).

The only structural difference for permissioned yields: the API performs an on-chain allowlist check before constructing transactions and returns a recoverable HTTP 412 if the address is not yet KYC’d. See KYC Precondition Errors.

---

Identifying RWA Yields

Every RWA yield is returned by GET /v1/yields (and the per-yield endpoints) with the canonical shape:

{
  "id": "ethereum-usdc-superstate-ustb-vault",
  "type": "real-world-asset",
  "requirements": {
    "kycRequired": true,
    "kycUrl": "https://superstate.com"
  }
}

Filter strategies

All RWA yields

const rwaYields = yields.filter(
  (y) => y.type === "real-world-asset"
);

When requirements.kycUrl is present, redirect users there before attempting the first enter call. The KYC URL is the issuer’s onboarding portal — completion adds the user’s address to the on-chain allowlist.

kycRequired is only set when the issuer enforces KYC. Lending markets that accept an RWA token as collateral (e.g. Kamino lending USDC against syrupUSDC) appear under their host protocol’s type (lending / vault), not as real-world-asset, and do not set kycRequired. See Indirect RWA Exposure.

---

Permissioned RWA Yields

Permissioned yields are restricted by the issuer to verified investors — typically U.S. Qualified Purchasers, accredited investors, or KYC’d entities under the issuer’s compliance program. Yield.xyz handles the on-chain allowlist check; the off-chain KYC happens on the issuer’s portal.

Issuer coverage

Issuer	Assets	Status
Superstate	USTB (T-Bills), USCC (crypto carry)	Live
Securitize / BlackRock	BUIDL (BlackRock USD Institutional Digital Liquidity Fund)	Upcoming
Ondo Finance	USDY, rUSDY, OUSG	Upcoming
Hashnote	USYC	Upcoming
Backed Finance	bIB01, bC3M	Upcoming
Franklin Templeton	BENJI	Upcoming
Mountain Protocol	USDM, wUSDM	Upcoming
Midas	mUSDC, mTBILL, mBASIS	Upcoming
Figure Markets	PRIME, CASH	Upcoming

Superstate (USTB, USCC) — Live

Superstate issues two tokenized funds, both restricted to U.S. Qualified Purchasers.

Yield ID	Underlying strategy	Reward token
ethereum-usdc-superstate-ustb-vault	Short-duration U.S. Treasuries	USTB
ethereum-usdc-superstate-uscc-vault	Crypto carry strategy	USCC

Onboarding. Before any enter / exit transaction is built, the API calls isAllowed(address) on the on-chain Superstate allowlist. If the address is not allowlisted, the API responds with HTTP 412 Precondition Failed and the issuer’s KYC URL. Treat this as a recoverable state — redirect the user, complete KYC, and retry.

Lifecycle.

Phase	Mechanism	Notes
Enter	subscribe(amountUSDC, USDC) on the Superstate token contract	Requires prior approve on USDC. Minimum 100,000 USDC.
Accrual	NAV/share updates daily via Chainlink oracle	getBalances returns USDC-equivalent value, not raw shares
Exit	offchainRedeem(shares)	Submits a redemption request. Settled T+1 via Superstate’s off-chain process.

Pending redemptions surface as BalanceTypes.Unstaking entries with an expectedSettlementAt date.

Pause behavior. Both funds expose paused(). When paused, getStatus returns { enter: false, exit: false } and the yield is hidden from discovery.

Securitize / BlackRock BUIDL — Upcoming

BlackRock USD Institutional Digital Liquidity Fund, distributed via Securitize. Backed by short-duration U.S. Treasuries, repos, and cash. Restricted to qualified institutional investors per Securitize’s onboarding requirements.

Integration target: same enter / exit contract; KYC handled via Securitize’s investor portal.

Ondo Finance (OUSG, rUSDY) — Upcoming

Tokenized exposure to short-term Treasuries via Ondo’s institutional product line. OUSG and rUSDY are KYC-gated for primary mint/redeem. Note: USDY is also covered but accessed via secondary market and is treated as permissionless from an integration standpoint — see Permissionless RWA Yields.

Other upcoming issuers

Hashnote (USYC), Backed Finance (bIB01, bC3M), Franklin Templeton (BENJI), Mountain Protocol (USDM, wUSDM), Midas (mUSDC, mTBILL, mBASIS), and Figure Markets (PRIME, CASH) are on the roadmap. Each will follow the same enter / exit lifecycle with issuer-specific KYC handoff.

KYC Precondition Errors

When a user attempts to interact with a permissioned yield from a non-allowlisted address, the API returns HTTP 412 Precondition Failed:

{
  "error": "PRECONDITION_FAILED",
  "message": "Address 0xabc… is not allowlisted for Superstate. Complete KYC at https://superstate.com",
  "details": {
    "address": "0xabc…",
    "protocol": "Superstate",
    "kycUrl": "https://superstate.com"
  }
}

This is intentionally HTTP 412, not 403 — the request is well-formed, but a precondition (allowlist membership) is unmet. Recommended UX:

1. Catch the 412 response.
2. Redirect the user to details.kycUrl.
3. After the issuer confirms allowlist inclusion (typically minutes to hours), retry the original request.

---

Permissionless RWA Yields

Permissionless RWA yields require no KYC and no allowlist — any address can deposit through the standard enter / exit flow. They expose users to the same off-chain assets (Treasuries, private credit, structured strategies) but route access through open vault contracts or DEX secondary markets.

requirements is not set on permissionless RWA yields. There are no preconditions beyond holding the input token.

At a glance

Asset	Protocol	TVL	Indicative APY	Backing	Redemption
Syrup USDC / USDT	Maple	—	Variable	Private-credit pools	Per pool terms
mTBILL	Midas	~$36.8M	~3.3%	U.S. Treasuries (BUIDL-linked)	Instant or T+1–3
sfrxUSD	Frax	~$25M	~5.2%	Mixed: stablecoins, RWA, AMOs	Instant
USDY	Ondo	~$680M	~3.6%	Short-dated U.S. Treasuries + cash	DEX secondary
sUSDe	Ethena	~$3.46B	~4.2%	Delta-hedged crypto + stables	7-day cooldown
stUSDT	JustLend / Tron	~$63M	~3.8%	T-bills + cash equivalents	Up to ~3 days
Nest Credit (vaults)	Nest	~$37M	~6.1%–14.0%	Vault-specific RWA mix	1–10 days

TVL and APY are point-in-time snapshots. Always source live values from the GET /v1/yields/{id} metadata endpoint before surfacing numbers in client UI.

Protocol details

Maple (Syrup)

Open ERC-4626-style vaults backed by Maple’s private-credit pools. No KYC, no allowlist, no minimum.

Yield ID	Input	Vault token
ethereum-usdc-syrupusdc-…-4626-vault	USDC	syrupUSDC
ethereum-usdt-syrupusdt-…-4626-vault	USDT	syrupUSDT

Lifecycle. Standard ERC-4626 deposit / redeem. requirements is not set.

Midas (mTBILL)

Direct on-chain mint via Midas’s Issuance Vault. Backed by U.S. Treasury exposure through a BUIDL-linked structure.

Detail	Value
Permissionless	Yes
Accepted input	USDC
Chains	Ethereum, Base
Mint	Atomic via depositInstant(...) on the Issuance Vault
Redemption	Two modes — Instant (atomic, ~0.07% fee, subject to liquidity) or Standard (T+1–3 business days)

Contracts (Ethereum mainnet).

Contract	Address
Issuance Vault	0x99361435420711723aF805F08187c9E6bF796683
mTBILL token	0xDD629E5241CbC5919847783e6C96B2De4754e438

See the mTBILL walkthrough below for the full step-by-step.

Frax (sfrxUSD)

Yield-bearing ERC-4626 wrapper on top of frxUSD. Yield is sourced from Frax’s Benchmark Yield Strategy — a managed rotation across DeFi AMOs, RWA allocations, and short-dated T-bills.

Detail	Value
Permissionless	Yes
Cooldown	None — instant stake / unstake
Entry	deposit(uint256 assets, address receiver)
Exit	redeem(uint256 shares, address receiver, address owner) — no fees

Contracts (Ethereum mainnet).

Contract	Address
sfrxUSD vault	0xcf62F905562626CfcDD2261162a51fd02Fc9c5b6
frxUSD token	0xCAcd6fd266aF91b8AeD52aCCc382b4e165586E29

sfrxUSD is not a pure T-bill product — it’s a managed yield strategy. Surface this clearly to end users when comparing against single-asset RWA exposure like mTBILL or USDY.

Ondo (USDY)

USDY is KYC-gated for primary mint/redeem (40–50 day lockup, $500 minimum, fiat-only redemption). Practical permissionless access is via secondary market DEX swap.

Detail	Value
Primary mint	KYC + allowlist
Secondary access	DEX swap routed via cross chain providers
Networks	Ethereum, Arbitrum, Solana
Redemption (secondary)	Instant via DEX

Yield accrues via increasing redemption value (accumulating token mechanics) — the token price increases over time rather than rebasing.

Ethena (sUSDe)

sUSDe is the staked form of Ethena’s USDe. Yield comes from a delta-hedged synthetic dollar strategy — funding/basis on short perpetual positions plus staking yield on the ETH leg.

sUSDe is not Treasury-backed. It introduces market structure and funding rate risk. Currently the largest yield primitive in the broader RWA-adjacent set, but the risk profile differs materially from Treasury-backed products.

Detail	Value
Cooldown	7 days (admin-configurable, max 90)
Entry	deposit(uint256 assets, address receiver)
Exit	cooldownAssets(...) → wait 7 days → unstake(address)
Alternative exit	DEX swap via LiFi (instant, slippage vs NAV)

Contracts (Ethereum mainnet).

Contract	Address
StakedUSDe vault	0x9D39A5DE30e57443BfF2A8307A4256c8797A3497
USDe token	0x4c9EDD5852cd905f086C759E8383e09bff1e68b3
USDeSilo (cooldown escrow)	0x7FC7c91D556B400AFa565013E3F32055a0713425

stUSDT

Rebasing receipt token providing T-bill / cash-equivalent exposure. Primary deployment is on Tron; an Ethereum deployment exists with thinner liquidity.

Independent risk research notes that stUSDT discloses no formal mandate on portfolio composition, and reserves/custodians are not clearly disclosed. Surface this transparency caveat to institutional clients.

Detail	Value
Token model	Rebasing (wstUSDT non-rebasing wrapper available)
Chains	Tron (primary), Ethereum
Native redeem	Up to ~3 days
Alt exit	DEX swap (significant slippage on Ethereum)

Nest Credit

Vault network with differentiated risk/return profiles. Compliance gating: a Predicate Message (AML check) is required for native deposits, but no individual KYC.

Vault	Token	Strategy	Target APY	Liquidity window
Nest Treasuries	nTBILL	Short-term U.S. Treasuries	5.50%	1–3 days
Nest Basis	nBASIS	Delta-neutral + treasury derivatives	8.00%	3–5 days
Nest ETF	nETF	Institutional ETFs + secured debt	8.80%	3–5 days
Nest Alpha	nALPHA	Diversified credit / ETFs / commodities	11.50%	3–5 days
Nest PayFi	nPAYFI	Fintech lending, stablecoin receivables	14.00%	5–10 days

Architecture: Boring Vault (Teller + Accountant + Manager + Predicate Proxy). Redemptions route through an Atomic Queue.

---

Indirect RWA Exposure

Several non-RWA integrations let users gain RWA exposure without KYC by lending against an RWA token as collateral. These appear under their host protocol’s type (lending / vault) — never as real-world-asset — and do not set kycRequired.

Yield ID	Wraps	Surface type
solana-kamino-maple-syrupusdc-…-lending	Maple syrupUSDC market on Kamino	lending
solana-kamino-maple-pyusd-…-lending	Maple PYUSD market on Kamino	lending
solana-kamino-superstate-opening-bell-usdc-…-lending	Superstate Opening Bell market on Kamino	lending
ethereum-syrupusdc-esyrupusdc-…-4626-vault	Euler Yield over syrupUSDC	vault
plasma-syrupusdt-aave-v3-lending	Aave v3 lending of syrupUSDT on Plasma	lending

Risk profile is different. Users take on (1) the wrapping protocol’s smart-contract risk, (2) the underlying RWA’s credit risk, and (3) any peg/oracle risk on the collateral asset. Surface this distinction in any UI that groups these alongside direct RWA yields.

---

Integration Walkthrough — Syrup USDC

The Yield.xyz API contract is identical for every RWA yield. We use Maple’s syrupUSDC below as the concrete example as it represents the most common permissionless RWA pattern: a standard ERC-4626 vault with asynchronous withdrawals (similar to EIP-7540). Most permissionless RWA integrations on the platform follow this same shape.

1. Dashboard setup & API key

   1. Log in to dashboard.yield.xyz.
   2. Navigate to Projects → Create Project.
   3. Inside the project: API Keys → Create API Key.

   Each project is isolated. Use separate projects for separate clients or environments.

   Reference: Creating an API Key
2. Enable RWA yields

   By default, no yields are enabled in a new project. You must explicitly enable each one.

   1. In your project, scroll to the Yields section.
   2. Open the RWA category.
   3. Search for and select the yields you want enabled (e.g. syrupUSDC on Ethereum).
   4. Click Save.

   Only enabled yields will be returned by GET /v1/yields for this project’s API key.

3. Discover yields and fetch metadata

   List enabled yields

       curl --request GET \
         --url 'https://api.yield.xyz/v1/yields?offset=0&limit=20' \
         --header 'accept: application/json' \
         --header 'x-api-key: <YOUR_API_KEY>'
   

   Metadata includes:

   apy · number

   Current annualized yield, sourced from the underlying Maple private credit pool.

   tvl · number

   Total value locked in the yield.

   status · object

   { enter: boolean, exit: boolean } — current action availability.

   arguments · object

   Required fields per action. The amount field is denominated in USDC (the input asset), not in syrupUSDC shares.

   chain · string

   Network identifier. Ethereum mainnet is the primary deployment. Cross-chain mint/redeem on Base and Arbitrum via CCIP is on the roadmap.

4. Deposit (Enter)

   Deposit USDC and receive syrupUSDC — an ERC-4626 vault share token. No KYC, no allowlist, no minimum.

       curl --request POST \
         --url https://api.yield.xyz/v1/actions/enter \
         --header 'content-type: application/json' \
         --header 'x-api-key: <YOUR_API_KEY>' \
         --data '{
           "yieldId": "<SYRUPUSDC_YIELD_ID>",
           "address": "<USER_WALLET_ADDRESS>",
           "arguments": { "amount": "10000" }
         }'
   

   The response contains one or more fully constructed unsigned transactions, in order:

   Step	Transaction	What happens
   0	APPROVAL	Approve the Maple vault to spend USDC
   1	DEPOSIT	Deposit USDC into the ERC-4626 vault; syrupUSDC shares are minted to the user wallet

   No client-side calldata construction is required. Sign and submit each transaction in order via your custody infrastructure.

   Deposit behavior. Single atomic flow — shares mint in the same transaction as the deposit.

5. Redeem (Exit)

   Maple’s withdrawal flow is asynchronous — modeled on ERC-4626 with async withdrawal handling (similar to EIP-7540). The same /exit endpoint covers two paths:

       curl --request POST \
         --url https://api.yield.xyz/v1/actions/exit \
         --header 'content-type: application/json' \
         --header 'x-api-key: <YOUR_API_KEY>' \
         --data '{
           "yieldId": "<SYRUPUSDC_YIELD_ID>",
           "address": "<USER_WALLET_ADDRESS>",
           "arguments": { "amount": "10000" }
         }'
   

   Standard async withdrawal

   • Flow: submit redemption request → pool processes → USDC returned to user
   • Settlement: typically near-instant when pool liquidity is available
   • Worst case: up to 30 days, depending on underlying pool liquidity
   • Fee: none beyond standard pool economics

   Secondary market swap

   • Flow: swap syrupUSDC → USDC on a DEX
   • Settlement: atomic
   • Tradeoff: subject to price impact and slippage vs vault NAV
   • When to use: users needing immediate exit when the async queue is congested

   Syrup has a single withdrawal flow (async by default), with the DEX swap as an independent alternative — there is no instant/standard mode toggle on the redemption itself. Surface both options in client UI when settlement timing matters to the user.

6. Track balances and lifecycle

       curl --request POST \
         --url 'https://api.yield.xyz/v1/yields/<SYRUPUSDC_YIELD_ID>/balances' \
         --header 'content-type: application/json' \
         --header 'x-api-key: <YOUR_API_KEY>' \
         --data '{ "address": "<USER_WALLET_ADDRESS>" }'
   

   Response surfaces:

   active · object

   syrupUSDC shares held and earning yield. Includes both share-denominated and USD-equivalent values.

   pending · object

   Shares submitted for async redemption, awaiting pool processing. Includes an expectedSettlementAt estimate.

   Unit-of-account nuance. The API takes amount in USDC (the input asset) on enter / exit, but the on-chain balance is denominated in syrupUSDC shares. The share-to-USDC ratio drifts upward over time as yield accrues. When surfacing balances in client UI:

   • Display the USD-equivalent as the primary value the user sees.
   • Treat the share count as a secondary detail (or hide it entirely for non-technical users).
   • This avoids the most common UX confusion: a user depositing 10,000 USDC and seeing “9,847 syrupUSDC” in their balance.

   For multi-yield, multi-address portfolio views, use the batch endpoint POST /v1/yields/balances.

   Reference: Balances

---

Position Lifecycle & Balance States

The Yield.xyz balance model normalizes every RWA position into one of four states, regardless of issuer:

State	Meaning	When it surfaces
Active	Tokens held, accruing yield	After successful enter
Unstaking / Pending	Redemption submitted, awaiting settlement	T+1 (Superstate), 1–3 days (Midas standard), 1–10 days (Nest), 7 days (Ethena)
Claimable	Settled, awaiting user claim	After cooldown elapses for protocols requiring a separate claim transaction (e.g. Ethena unstake)
Pause / Hidden	Issuer-paused or temporarily unavailable	Surfaced via getStatus returning { enter: false, exit: false }

For institutional portfolio reporting, treat Pending and Claimable as still allocated to the strategy — they are off-chain settling cash flows, not realized exits.

---

Error Handling Reference

412 Precondition Failed — KYC required

Returned for permissioned yields when the user address is not on the issuer’s allowlist. Recoverable.

{
  "error": "PRECONDITION_FAILED",
  "message": "Address 0xabc… is not allowlisted for <issuer>",
  "details": {
    "address": "0xabc…",
    "protocol": "<issuer>",
    "kycUrl": "https://<issuer>.com"
  }
}

Action: redirect to details.kycUrl, retry after allowlist confirmation.

409 Conflict — issuer paused

Returned when an enter or exit is attempted on a yield whose underlying contract has been paused by the issuer (e.g. Superstate paused() returns true).

Action: poll GET /v1/yields/{id} until status.enter or status.exit returns to true. There is no manual override.

422 Unprocessable Entity — minimum not met

Returned when the requested amount is below the issuer’s minimum (e.g. Superstate’s 100,000 USDC floor).

Action: surface the minimum to the user from the yield metadata arguments.amount.min field before request submission.

503 Service Unavailable — instant liquidity exhausted

Returned for Midas Instant Redemption when the instant pool liquidity is insufficient to cover the request.

Action: offer the user the standard redemption path (1–3 business days) or reduce the amount to fit available liquidity.

---

Comparison Reference

For product reviewers comparing options across the integrated set:

Asset	Backing	KYC	Redemption window	DEX exit available
USTB / USCC (Superstate)	T-Bills / crypto carry	Required	T+1	No
mTBILL (Midas)	T-Bills (BUIDL-linked)	None	Instant or T+1–3	Limited
Syrup USDC / USDT (Maple)	Private credit	None	Per pool terms	Yes
sfrxUSD (Frax)	Mixed yield strategy	None	Instant	Yes
USDY (Ondo)	T-Bills + cash	None (secondary)	Instant via DEX	Yes
sUSDe (Ethena)	Delta-hedged synthetic	None	7-day cooldown	Yes
stUSDT	T-Bills + cash (limited disclosure)	None	Up to ~3 days	Yes (Tron)
Nest vaults	Vault-specific RWA mix	Predicate AML check	1–10 days	No

Backing transparency varies. Treasury-backed exposure (USTB, mTBILL, USDY) is well-attested. Strategy products (sfrxUSD, sUSDe) and limited-disclosure products (stUSDT) require additional review. Surface backing composition prominently when presenting these to end users or institutional reviewers.

---

Resources

API Reference

Full Yield.xyz API specification — endpoints, schemas, response shapes.

Yield Metadata

Detailed reference for the /yields discovery endpoint and metadata fields.

Balances

Balance lifecycle states and the per-yield / batch balance endpoints.

Creating an API Key

Project setup and API key creation in the Yield.xyz dashboard.