Deposit and redeem RWAs

Discover an RWA yield, confirm eligibility, build and submit the enter action, then track the position through exit.

Deposit into a real-world-asset (RWA) yield and redeem out of it, from discovery through a settled exit. RWA issuers differ in how they gate entry and how they settle redemptions, so this guide builds one representative example end to end and points out where another issuer’s mechanics diverge.

One yield runs through every example: ethereum-usdc-nest-ntbill-vault, a Nest Treasury vault discovered by filtering GET /v1/yields for providers=nest. Swap in whatever id your own discovery step returns; see Discover yields.

This is Earn › RWAs. Tokenized equities and ETFs belong to Trade’s upcoming Tokenized Stocks product, not RWA yields.

Prerequisites

• A yield.xyz API key, sent as x-api-key on every request.
• An RWA yield enabled for your project, with status.enter (and, for exit, status.exit) true. See Discover yields.
• A wallet confirmed eligible for that yield. See Check RWA eligibility for the full decision: geo-blocking versus KYC, and what to do with a not_started or rejected status.
• A signer for the target chain. This guide uses a generic signAndBroadcast placeholder; see Transaction signing.

We construct. You sign. Every action returns unsigned transactions; yield.xyz never holds keys and never signs on your behalf.

Discover a vault and inspect its requirements

Nest runs the same vault contract family in parallel on Ethereum and Plume, so its yield IDs aren’t fixed the way a single-deployment yield’s is. Discover them instead of hardcoding one, and skip anything not currently open for entry:

cURL

curl --request GET \
  --url 'https://api.yield.xyz/v1/yields?types=real_world_asset&providers=nest&network=ethereum' \
  --header "x-api-key: $YIELD_API_KEY"

Response (excerpt, one result)

{
  "id": "ethereum-usdc-nest-ntbill-vault",
  "status": { "enter": true, "exit": true },
  "metadata": { "name": "Nest Treasury Vault", "deprecated": false },
  "mechanics": {
    "cooldownPeriod": { "seconds": 86400 },
    "requirements": { "kycRequired": true }
  }
}

Filter out any result with status.enter: false or metadata.deprecated: true before offering it. mechanics.requirements.kycRequired tells you whether this product gates entry behind off-chain verification at all; read mechanics.requirements.kyc for the rest. Don’t reproduce that decision here: see Check RWA eligibility for reading the eligibility metadata and calling GET /v1/yields/{yieldId}/kyc/status.

Confirm the wallet is eligible before building the enter action. A wallet that isn’t returns 412 Precondition Failed on some integrations, or (where the module runs no pre-flight check) fails only when the built transaction reverts on-chain. See Check RWA eligibility.

Build the enter arguments from the schema

Read mechanics.arguments.enter.fields from GET /v1/yields/{yieldId} before building the request, the same pattern as Enter and exit flows. A single-input-asset Nest vault like this one takes just amount:

Response (excerpt)

{
  "mechanics": {
    "arguments": {
      "enter": {
        "fields": [
          { "name": "amount", "type": "string", "required": true }
        ]
      }
    }
  }
}

A Nest vault that accepts more than one input asset (for example the BlackOpal LiquidStone II and BlackRock iShares AAA CLO Active ETF vaults on Ethereum, and every vault on Plume) adds a required inputToken field to enter and a required outputToken field to exit, to select which accepted asset you’re depositing or redeeming into. This single-asset Treasury vault has neither. Always build the request from the schema you read, not from this example’s field list.

Enter a position

cURL

curl --request POST \
  --url https://api.yield.xyz/v1/actions/enter \
  --header "x-api-key: $YIELD_API_KEY" \
  --header 'content-type: application/json' \
  --data '{
    "yieldId": "ethereum-usdc-nest-ntbill-vault",
    "address": "0xYOUR_WALLET_ADDRESS",
    "arguments": { "amount": "1000" }
  }'

Response (excerpt)

{
  "id": "action_123abc",
  "intent": "enter",
  "status": "CREATED",
  "executionPattern": "synchronous",
  "transactions": [
    { "id": "tx_123abc", "stepIndex": 0, "type": "APPROVAL", "status": "CREATED", "unsignedTransaction": "SERIALIZED_APPROVAL_TX" },
    { "id": "tx_456def", "stepIndex": 1, "type": "SUPPLY", "status": "CREATED", "unsignedTransaction": "SERIALIZED_SUPPLY_TX" }
  ]
}

Depositing USDC into a Nest vault needs an ERC-20 approval before the deposit call, so this action can return two transactions; a sufficient existing allowance returns the approval already SKIPPED. Sign and submit each transaction in stepIndex order, branching on executionPattern and choosing one of the two submit endpoints, exactly as in Enter and exit flows. This guide doesn’t re-teach that loop.

Verify the position

Once the last transaction confirms, read the resulting balance:

cURL

curl --request POST \
  --url https://api.yield.xyz/v1/yields/ethereum-usdc-nest-ntbill-vault/balances \
  --header "x-api-key: $YIELD_API_KEY" \
  --header 'content-type: application/json' \
  --data '{ "address": "0xYOUR_WALLET_ADDRESS" }'

Response (excerpt)

{
  "balances": [
    { "type": "active", "amount": "1000", "isEarning": true, "pendingActions": [] }
  ]
}

An active balance with no pendingActions means the deposit is fully settled. Yield accrues in the vault’s position token (nTBILL here) price per share, and reward claiming is automatic; there’s no separate claim step for accrued yield.

Exit and the redemption lifecycle

Exit follows the same request, sign, submit, poll loop as enter, through POST /v1/actions/exit and its own schema (mechanics.arguments.exit). A Nest vault’s exit schema takes amount, plus two optional booleans that pick the redemption path:

cURL

curl --request POST \
  --url https://api.yield.xyz/v1/actions/exit \
  --header "x-api-key: $YIELD_API_KEY" \
  --header 'content-type: application/json' \
  --data '{
    "yieldId": "ethereum-usdc-nest-ntbill-vault",
    "address": "0xYOUR_WALLET_ADDRESS",
    "arguments": { "amount": "1000", "useInstantExecution": true }
  }'

• useInstantExecution: true redeems immediately against the vault’s available on-chain liquidity, skipping the cooldown and any claim step. It only succeeds while the vault reports enough liquidity for your output asset; omit it, or set it false, for the standard path.
• Without useInstantExecution, the exit is a request, not an instant payout: it queues a redemption that settles after the vault’s own cooldown, then exposes a CLAIM_UNSTAKED pending action.
• useAutoClaim: true opts into a one-time operator authorization on this request, so the vault’s future redemptions no longer need a manual CLAIM_UNSTAKED step.

Read mechanics.cooldownPeriod on the yield you discovered rather than assuming a duration: Nest vaults set their own cooldown per vault, and it ranges from same-day to several months depending on the vault. Never hardcode a specific vault’s cooldown in your own code.

Sign and submit the exit’s transactions the same way as enter. During the cooldown, the balance reports as exiting:

Response (excerpt, during cooldown)

{
  "balances": [
    { "type": "exiting", "amount": "1000", "pendingActions": [] }
  ]
}

Once the cooldown ends, the same balance call returns withdrawable with a CLAIM_UNSTAKED pending action:

Response (excerpt, after cooldown)

{
  "balances": [
    {
      "type": "withdrawable",
      "amount": "1000",
      "pendingActions": [
        { "type": "CLAIM_UNSTAKED", "passthrough": "PASSTHROUGH_FROM_THE_BALANCE" }
      ]
    }
  ]
}

Run it with POST /v1/actions/manage, passing the pending action’s own type as action and its passthrough unchanged:

cURL

curl --request POST \
  --url https://api.yield.xyz/v1/actions/manage \
  --header "x-api-key: $YIELD_API_KEY" \
  --header 'content-type: application/json' \
  --data '{
    "yieldId": "ethereum-usdc-nest-ntbill-vault",
    "address": "0xYOUR_WALLET_ADDRESS",
    "action": "CLAIM_UNSTAKED",
    "passthrough": "PASSTHROUGH_FROM_THE_BALANCE"
  }'

Sign and submit the returned transaction like any other, then read balances again to confirm the funds have moved to your wallet. See Actions › Manage actions for the request shape and Tracking balances for surfacing and executing pending actions across a whole portfolio rather than one yield at a time.

Other RWA issuers settle redemption differently. Dinari queues an async redemption with no separate claim step: the payout lands directly in the receiver’s wallet once the operator fulfills it. Superstate and Midas standard redemption also settle without a CLAIM_UNSTAKED action, on the issuer’s own timeline. Check the issuer’s own page under Issuers rather than assuming this vault’s shape.

Next steps

Check RWA eligibility

Decide whether a wallet can enter or exit before you build the action.

Enter and exit flows

The full branch, sign, submit, and poll loop reused above.

Tracking balances

Build portfolio views and execute pending actions across every yield a wallet holds.

Issuers

Every RWA issuer’s product families, networks, and redemption mechanics.