Sequence and Trails

Discover, enter, track and exit yields with Sequence embedded wallets batching each step, and power Trails Earn cross-chain deposits with yield.xyz.

This guide builds a Next.js flow where users discover a yield across DeFi, staking and tokenized real-world assets, enter it, track the position and exit, signing with the Sequence embedded wallet. Sequence wallets are smart wallets, so every step of an action, such as an approval and a deposit, can go out as one atomic transaction with a single confirmation, and gas can be sponsored.

The second part covers Trails, Sequence’s intent-based cross-chain rails, and how yield.xyz supplies the discovery, transaction building and position tracking behind Trails Earn.

Resources

• Sequence embedded wallet
• Trails quickstart
• Enter and exit flows and EVM signing

Prerequisites

• A yield.xyz API key. See Projects & API keys.
• A Sequence project access key and WaaS config key from Sequence Builder.

Getting started with Sequence

Install the SDK and sign the user in. Social login, email and guest sign-in are supported, with no seed phrase.

pnpm install @0xsequence/waas

import { SequenceWaaS } from "@0xsequence/waas";

const sequence = new SequenceWaaS({
  projectAccessKey: process.env.NEXT_PUBLIC_SEQUENCE_PROJECT_ACCESS_KEY!,
  waasConfigKey: process.env.NEXT_PUBLIC_SEQUENCE_WAAS_CONFIG_KEY!,
  network: "base",
});

await sequence.signIn({ idToken }, "Yield session");
const address = await sequence.getAddress();

A Sequence wallet address is the same across every app on the same Sequence project.

How yield.xyz fits

yield.xyz gives you one API across 4,000+ yields on 85+ networks:

• Discover: GET /v1/yields returns yields with their metadata.
• Act: POST /v1/actions/enter, /exit and /manage return an ordered list of unsigned transactions.
• Track: POST /v1/yields/{yieldId}/balances and POST /v1/yields/balances return lifecycle-aware balances.

yield.xyz builds transactions and never signs or holds funds. Sequence signs them in the user’s wallet. This guide uses EVM networks.

Keep the API key on your server

Keep your yield.xyz API key on your server. The snippets in this guide call a small proxy route that adds the key, for example a Next.js route handler:

// app/api/yield/[...path]/route.ts
export async function handler(req: Request, { params }: { params: { path: string[] } }) {
  const url = new URL(req.url);
  const res = await fetch(`https://api.yield.xyz/${params.path.join("/")}${url.search}`, {
    method: req.method,
    headers: { "content-type": "application/json", "x-api-key": process.env.YIELD_API_KEY! },
    body: req.method === "GET" ? undefined : await req.text(),
  });
  return new Response(res.body, { status: res.status, headers: { "content-type": "application/json" } });
}
export { handler as GET, handler as POST, handler as PUT };

On the client, one helper calls it:

export async function yieldApi(path: string, body?: unknown, method = body ? "POST" : "GET") {
  const res = await fetch(`/api/yield${path}`, {
    method,
    headers: { "content-type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) throw Object.assign(new Error(json.message ?? `yield.xyz ${res.status}`), { status: res.status, body: json });
  return json;
}

Discover a yield

The discovery response already carries what your UI needs, so you don’t need a second request per yield.

const { items } = await yieldApi("/v1/yields?network=base&token=USDC&limit=10");

const selected = items[0];
const yieldId = selected.id;
const name = selected.metadata.name;
const rate = selected.rewardRate.total;                        // current estimated rate
const tvlUsd = selected.statistics?.tvlUsd;
const enterFields = selected.mechanics.arguments.enter.fields;  // what enter needs
const kycRequired = selected.mechanics.requirements?.kycRequired ?? false;

Every field on a yield is described in Yield metadata.

Find yields to offer

Rather than hardcoding yield IDs, which change as yields are added and retired, query the catalog for what you want to offer:

# Stablecoin and DeFi yields on Base
curl "https://api.yield.xyz/v1/yields?network=base&token=USDC&types=lending,vault" \
  -H "x-api-key: $YIELD_API_KEY"

# Native staking
curl "https://api.yield.xyz/v1/yields?type=staking&limit=100" \
  -H "x-api-key: $YIELD_API_KEY"

# Tokenized real-world assets
curl "https://api.yield.xyz/v1/yields?type=real_world_asset&networks=ethereum,base" \
  -H "x-api-key: $YIELD_API_KEY"

Add prime=true to return only yields that meet the Prime quality bar. For staking, default users to preferred validators. For DeFi, wrap yields in an OAV to charge fees and auto-compound incentives (see Monetization).

Enter a yield

Build the action, map its transactions to Sequence’s format and send them as one batch. Sequence simulates the batch first and does not broadcast it if it would fail.

import { SequenceWaaS, isSentTransactionResponse, Transaction } from "@0xsequence/waas";

const TERMINAL = ["CONFIRMED", "FAILED", "SKIPPED"];

async function signAndTrack(action: any) {
  const steps = [...action.transactions]
    .sort((a, b) => a.stepIndex - b.stepIndex)
    .filter((tx) => !TERMINAL.includes(tx.status)); // e.g. an approval already covered
  if (!steps.length) return action.id;

  const parsed = steps.map((tx) => JSON.parse(tx.unsignedTransaction));
  const chainId = parsed[0].chainId;
  const batch: Transaction[] = parsed.map((p) => ({ to: p.to, data: p.data, value: p.value ?? "0" }));

  // Sequence smart wallets need a fee quote unless the contract is sponsored in Sequence Builder
  const { data: fee } = await sequence.feeOptions({ transactions: batch, network: chainId });
  const result = await sequence.sendTransaction({
    chainId,
    transactions: batch,
    ...(fee.feeQuote && fee.feeOptions?.length
      ? { transactionsFeeQuote: fee.feeQuote, transactionsFeeOption: fee.feeOptions[0] }
      : {}),
  });

  if (!isSentTransactionResponse(result)) {
    // Simulation failed: nothing was broadcast and no gas was spent
    throw new Error(`Transaction would fail: ${result.data.error}`);
  }

  // The batch executed every step in one onchain transaction: report its hash for each step
  for (const tx of steps) {
    await yieldApi(`/v1/transactions/${tx.id}/submit-hash`, { hash: result.data.txHash }, "PUT");
  }
  return action.id;
}

const action = await yieldApi("/v1/actions/enter", { yieldId, address, arguments: { amount: "100" } });
await signAndTrack(action);

To make the flow gasless for users, sponsor the yield contracts or your users’ wallets in Sequence Builder and leave out the fee quote. Show the fee option in your UI if you charge users for gas.

Build the arguments from mechanics.arguments.enter.fields rather than hardcoding { amount }, so the same code works for yields that also need a validatorAddress or another field. Amounts are in token units, for example "100" for 100 USDC. See Enter and exit flows.

KYC-gated RWA yields

Tokenized real-world assets, such as US Treasuries, money market funds and private credit, use the same enter and exit flow, so no new signing code is needed. Some issuers require the wallet to be allowlisted first, shown by mechanics.requirements.kycRequired: true on the yield.

Check the wallet when it connects, so you can show “Verify identity” instead of “Deposit” for a gated yield:

const kyc = await yieldApi(`/v1/yields/${yieldId}/kyc/status?address=${address}`);
// kyc.kycStatus: not_required | not_started | pending | approved | rejected
// kyc.authorizeUrl: the issuer's KYC portal, when the issuer provides one

Send the user to authorizeUrl when the status is not_started or rejected, ideally in a new tab or after saving the pending deposit so you can resume it, and enter once it is approved. If you call enter for a wallet that is not cleared, the API returns 412 with RwaKycError, and the message includes the issuer’s KYC URL:

try {
  await signAndTrack(await yieldApi("/v1/actions/enter", { yieldId, address, arguments: { amount: "100000" } }));
} catch (e: any) {
  if (e.status === 412) {
    // Not allowlisted yet: fetch kyc/status and hand the user to authorizeUrl
  } else throw e;
}

Read entryLimits.minimum before you build the action: many RWA yields have high minimums. Issuer eligibility is in RWA KYC and on each issuer’s page under RWAs.

Read the position balance

Balances are lifecycle-aware: each one has a type that says whether funds are active, entering, exiting, withdrawable, claimable or locked.

const { balances } = await yieldApi(`/v1/yields/${yieldId}/balances`, { address });
for (const b of balances) {
  console.log(b.type, b.amount, b.token.symbol, b.pendingActions?.map((p: any) => p.type));
}

For many yields or wallets at once, use POST /v1/yields/balances with { "queries": [{ "address", "network" }] }, up to 25 queries per request:

const all = await yieldApi("/v1/yields/balances", {
  queries: [{ address, network: "base" }], // every yield on Base for this wallet
});

See Tracking balances.

Handle pending actions

A balance can carry pendingActions, such as CLAIM_REWARDS or CLAIM_UNSTAKED. Pass one back to POST /v1/actions/manage unchanged, then sign the result the same way as an enter:

const pending = balances.find((b: any) => b.pendingActions?.length)?.pendingActions[0];
if (pending) {
  const manage = await yieldApi("/v1/actions/manage", {
    yieldId,
    address,
    action: pending.type,
    passthrough: pending.passthrough,
  });
  await signAndTrack(manage);
}

Exit a yield

Exiting is the same pattern as entering:

const exit = await yieldApi("/v1/actions/exit", {
  yieldId,
  address,
  arguments: { amount: "50" }, // see mechanics.arguments.exit
});
await signAndTrack(exit);

Some exits need more than one transaction, for example withdraw and unwrap. Sequence sends them as one batch, with one confirmation.

Not every exit settles at once. Staking unbonds wait out the network’s cooldown, and many RWA redemptions settle on a NAV strike or over several days. While that happens the position shows as an exiting balance. When it settles it becomes withdrawable with a CLAIM_UNSTAKED pending action, which you complete through POST /v1/actions/manage as above. Poll balances on a sensible cadence and show the in-flight state in your UI.

Track transaction status

After each broadcast, report the hash with PUT /v1/transactions/{transactionId}/submit-hash, then poll GET /v1/transactions/{transactionId} (or GET /v1/actions/{actionId}) until it reaches a terminal status:

const tx = await yieldApi(`/v1/transactions/${transactionId}`);
console.log(tx.status); // CONFIRMED, FAILED, ...

See Monitoring and alerting.

Integration tips

• Send transactions in stepIndex order and skip any already at a terminal status.
• Never change to, data, value, gas or nonce before signing.
• Build arguments from mechanics.arguments.* for the right fields and units.
• Keep your yield.xyz API key on the server.
• Geo-blocking is applied by the API for your project; see Geo-blocking.
• Batch every step of an action into one sendTransaction call: one confirmation, atomic execution.
• Use sendTransaction for the raw transactions yield.xyz returns; callContract is for a single ABI call you encode yourself.
• Check isSentTransactionResponse before reporting a hash: a failed simulation is never broadcast.

Power Trails Earn with yield.xyz

Trails Earn lets users deposit into DeFi protocols and RWA vaults from any token on any chain. Trails handles the cross-chain routing, bridging and swapping. yield.xyz supplies the three things Trails Earn needs underneath: which yields to show, the calldata to enter and exit them, and the user’s positions afterwards. New yields, protocols and issuers added to yield.xyz become available to Trails without new integration work.

Trails Earn needs	yield.xyz provides
Which vaults and pools to show	GET /v1/yields, with rate, TVL, entry limits, provider metadata and KYC requirements
Calldata to deposit	POST /v1/actions/enter, ordered unsigned transactions
Calldata to withdraw	POST /v1/actions/exit, including multi-step and async exits
User positions	POST /v1/yields/{yieldId}/balances, lifecycle-aware
What the user can do next	pendingActions on each balance, such as claim rewards or claim a settled withdrawal
Regulated assets	Tokenized RWAs with a KYC status check
Fees	OAVs with configurable deposit, performance and management fees

1. Populate the Earn UI

const { items: yields } = await yieldApi("/v1/yields?network=base&type=lending");

// Each yield carries what the Earn UI needs:
// metadata.name, metadata.logoURI, providerId   display
// rewardRate.total                              current rate
// statistics.tvlUsd                             TVL
// token                                         deposit token (address, symbol, decimals)
// mechanics.arguments.enter                     required arguments
// mechanics.requirements.kycRequired            whether the wallet must be allowlisted
// mechanics.possibleFeeTakingMechanisms         monetization options

2. Build the deposit

When the user picks a yield and an amount, build the enter action for the user’s address on the destination chain:

const action = await yieldApi("/v1/actions/enter", {
  yieldId,
  address: userAddress, // the user's wallet on the destination chain
  arguments: { amount: "100" },
});
// Each step's unsignedTransaction carries to, data, value and chainId.
// Trails runs the bridge and swap, then executes these steps on the destination chain:
// `to` maps to Trails' toAddress and `data` to toCalldata.

For a KYC-gated RWA yield, check GET /v1/yields/{yieldId}/kyc/status for the destination address before the user starts a cross-chain deposit, so they don’t bridge funds and then hit a 412 on enter.

3. Track positions

const { balances } = await yieldApi(`/v1/yields/${yieldId}/balances`, { address: userAddress });
// type: active | entering | exiting | withdrawable | claimable | locked
// pendingActions: what the user can do next

Trails doesn’t need to understand each protocol’s balance model, including RWA redemptions that settle over days.

4. Build the withdrawal

const exit = await yieldApi("/v1/actions/exit", { yieldId, address: userAddress, arguments: { amount: "100" } });
// Steps come back in order; for a Sequence wallet they can be batched into one transaction.
// Async exits show as `exiting`, then `withdrawable` with a CLAIM_UNSTAKED pending action.

Without yield.xyz	With yield.xyz
One integration per protocol	4,000+ yields across DeFi, staking and RWAs through one API
Calldata encoding per protocol version	Ready-to-sign transactions
Balance tracking per protocol	Lifecycle-aware balances with pending actions
No fee layer	OAVs with configurable fees
No regulated assets	Tokenized RWAs with a KYC status check

Monetization

How you earn depends on the yield type. Each yield’s mechanics.possibleFeeTakingMechanisms says which fees you can configure on it.

• Staking: deposit fees, deducted atomically in the same transaction, and a share of validator revenue through yield.xyz’s validator agreements. See Preferred validators.
• DeFi: revenue share from some protocols and curators, and user-facing deposit, performance and management fees through OAVs.
• RWAs: issuer fees are set by the issuer and passed through. Where an RWA is wrapped in an OAV, you can add your own fees on top.

OAVs also improve the user experience: incentive tokens are sold into the deposit asset and reinvested automatically, wrapping and swapping are handled for the user, and users only ever see their deposit token. See Earn monetization for fee configuration, and Plans for commercial terms.

Next steps

Enter and exit flows

The full request, sign and poll loop.

Yield metadata

Every field returned on a yield.

Shield

Verify each transaction before Sequence signs it.

Embedded wallets

The same flow with other wallet providers.