Recipes

Copy-paste requests for common Earn tasks: discovery, portfolio balances, claiming rewards, exiting fully, and gas estimates.

Short, self-contained requests for tasks that come up often enough to skip re-deriving them. Each one assumes an enabled yield and a valid x-api-key; see Discover yields and Enter and exit flows for the full walkthroughs these are pulled from.

List USDC yields across networks

Filter GET /v1/yields by inputTokens and a comma-separated networks list, then page through with offset until you’ve collected total items.

async function listUsdcYields(networks: string[]) {
  const results: any[] = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const params = new URLSearchParams({
      inputTokens: 'USDC',
      networks: networks.join(','),
      limit: String(limit),
      offset: String(offset),
    });
    const { items, total } = await fetch(`https://api.yield.xyz/v1/yields?${params}`, {
      headers: { 'x-api-key': process.env.YIELD_API_KEY! },
    }).then((r) => r.json());

    results.push(...items);
    offset += limit;
    if (offset >= total) return results;
  }
}

const usdcYields = await listUsdcYields(['base', 'ethereum', 'arbitrum']);

Result: every USDC yield enabled for your project across the requested networks, in one array.

Portfolio across networks in one call

Send one query per network in a single POST /v1/yields/balances call instead of one request per network.

cURL

curl --request POST \
  --url https://api.yield.xyz/v1/yields/balances \
  --header "x-api-key: $YIELD_API_KEY" \
  --header 'content-type: application/json' \
  --data '{
    "queries": [
      { "address": "0xYOUR_WALLET_ADDRESS", "network": "ethereum" },
      { "address": "0xYOUR_WALLET_ADDRESS", "network": "base" }
    ]
  }'

Result: { items, errors }, with items covering both networks’ non-empty balances in one response.

Claim every claimable reward

Fetch the portfolio, then run every CLAIM_REWARDS pending action it offers through POST /v1/actions/manage.

const { items } = await fetch('https://api.yield.xyz/v1/yields/balances', {
  method: 'POST',
  headers: { 'x-api-key': process.env.YIELD_API_KEY!, 'content-type': 'application/json' },
  body: JSON.stringify({ queries: [{ address: '0xYOUR_WALLET_ADDRESS', network: 'ethereum' }] }),
}).then((r) => r.json());

for (const item of items) {
  for (const balance of item.balances) {
    for (const pending of (balance.pendingActions ?? []).filter((p: any) => p.type === 'CLAIM_REWARDS')) {
      await fetch('https://api.yield.xyz/v1/actions/manage', {
        method: 'POST',
        headers: { 'x-api-key': process.env.YIELD_API_KEY!, 'content-type': 'application/json' },
        body: JSON.stringify({
          yieldId: item.yieldId,
          address: '0xYOUR_WALLET_ADDRESS',
          action: pending.type,
          passthrough: pending.passthrough,
        }),
      });
    }
  }
}

Result: one new manage action per claimable reward found; sign, submit, and poll each the same way as any other action. If a pending action carries its own arguments schema, fill it before calling manage.

Exit a full position with useMaxAmount

Some yields’ exit schema offers useMaxAmount so you redeem the whole position without computing an exact amount. Check mechanics.arguments.exit.fields before relying on it: not every yield exposes it.

const yieldData = await fetch(`https://api.yield.xyz/v1/yields/${yieldId}`, {
  headers: { 'x-api-key': process.env.YIELD_API_KEY! },
}).then((r) => r.json());

const exitFields = yieldData.mechanics.arguments.exit?.fields ?? [];
const supportsMax = exitFields.some((f: { name: string }) => f.name === 'useMaxAmount');

const action = await fetch('https://api.yield.xyz/v1/actions/exit', {
  method: 'POST',
  headers: { 'x-api-key': process.env.YIELD_API_KEY!, 'content-type': 'application/json' },
  body: JSON.stringify({
    yieldId,
    address: '0xYOUR_WALLET_ADDRESS',
    arguments: supportsMax ? { useMaxAmount: true } : { amount: knownAmount },
  }),
}).then((r) => r.json());

Result: an exit action sized to the full position, without a separate balance read to compute the amount first.

Estimate gas before entering

POST /v1/actions/enter/simulate takes the same body as POST /v1/actions/enter and returns a gas estimate without creating or persisting an action.

cURL

curl --request POST \
  --url https://api.yield.xyz/v1/actions/enter/simulate \
  --header "x-api-key: $YIELD_API_KEY" \
  --header 'content-type: application/json' \
  --data '{
    "yieldId": "base-usdc-aave-v3-lending",
    "address": "0xYOUR_WALLET_ADDRESS",
    "arguments": { "amount": "100" }
  }'

Result: gas.amount and gas.token for the aggregate cost, plus a per-transaction breakdown in gas.transactions[]. A 200 here does not guarantee the real action succeeds on-chain.

Next steps

Enter and exit flows

The full sign, submit, and poll loop these recipes call into.

Tracking balances

Read and group balances beyond a single claim or exit call.