Opportunities

Discover yield opportunities across Gearbox Markets using the SDK vNext. The unified opportunity surface lets you search pools, leveraged strategies, and markets from a single entry point, across all supported chains.

Unified Discovery

The sdk.opportunities.search() method returns a combined list of pools and strategies, ranked and filterable. This is the recommended starting point for any discovery flow.

TypeScript

import { GearboxSDK } from "@gearbox-protocol/sdk/official";

const sdk = await GearboxSDK.init({
  chains: [1, 42161, 10],
  startFromCache: true,
});

// Discover all opportunities across chains
const opportunities = await sdk.opportunities.search();

for (const opp of opportunities) {
  console.log(`${opp.title} — ${opp.type} on chain ${opp.chainId}`);
  console.log(`  APY: ${opp.headlineApy}%  Capacity: ${opp.capacity}`);
}

Opportunity Fields

Every opportunity — whether pool, strategy, or market — shares a common shape:

Field	Type	Description
`id`	`string`	Unique identifier (address or composite key)
`chainId`	`number`	Chain where the opportunity lives
`type`	`"pool" \| "strategy" \| "market"`	Kind of opportunity
`title`	`string`	Human-readable name (e.g. "dUSDC-V3-Tier1")
`depositToken`	`TokenRef`	Token used to enter the position
`headlineApy`	`number`	Composite APY (organic + incentives)
`yieldType`	`string`	Yield source classification (e.g. "lending", "staking_spread")
`capacity`	`string`	Remaining capacity in underlying token
`access`	`"permissionless" \| "kyc"`	Whether entry requires KYC verification
`risk`	`object`	Risk metadata (curator, oracle types, utilization)
`points`	`object \| null`	Active points programs, if any

Pool Discovery

Use sdk.pools.list() when you specifically want LP deposit opportunities:

TypeScript

const pools = await sdk.pools.list({
  chainId: 1,
  asset: "STABLE",
  minApy: 5,
  minTvl: 1_000_000,
});

for (const pool of pools) {
  console.log(`${pool.title} — APY ${pool.headlineApy}%`);
  console.log(`  TVL: $${pool.tvlUsd}  Utilization: ${pool.utilizationRate}%`);
}

Strategy Discovery

Use sdk.strategies.list() for leveraged strategy opportunities:

TypeScript

const strategies = await sdk.strategies.list({
  chainId: 42161,
  asset: "ETH",
  minNetApy: 3,
});

for (const s of strategies) {
  console.log(`${s.title} — Net APY ${s.headlineApy}%`);
  console.log(`  Borrow: ${s.borrowableAmount}  Leverage: up to ${s.maxLeverage}x`);
}

Filtering

All discovery methods accept a common filter object. Filters compose — pass multiple to narrow results.

Filter by Chain

TypeScript

// Single chain
const mainnetOpps = await sdk.opportunities.search({ chainId: 1 });

// Multiple chains
const multiChain = await sdk.opportunities.search({ chainId: [1, 42161] });

Filter by Asset Class

The SDK classifies underlying tokens into asset classes for coarse filtering:

Asset Class	Constant	Tokens
Stablecoins	`Asset.STABLE`	USDC, USDT, DAI, GHO
ETH-correlated	`Asset.ETH`	WETH, wstETH, rETH, cbETH
BTC-correlated	`Asset.BTC`	WBTC, tBTC, sBTC
Monad native	`Asset.MON`	MON, wMON

TypeScript

import { Asset } from "@gearbox-protocol/sdk/official";

// Only stablecoin opportunities
const stables = await sdk.opportunities.search({ asset: Asset.STABLE });

// ETH-correlated strategies on Arbitrum
const ethStrategies = await sdk.strategies.list({
  asset: Asset.ETH,
  chainId: 42161,
});

Filter by APY Floor

TypeScript

// Only opportunities with 5%+ headline APY
const highYield = await sdk.opportunities.search({ minApy: 5 });

Filter by TVL Minimum

TypeScript

// Only pools with at least $1M TVL
const largePools = await sdk.pools.list({ minTvl: 1_000_000 });

Filter by Access

TypeScript

// Only permissionless opportunities (no KYC)
const open = await sdk.opportunities.search({ access: "permissionless" });

// Only KYC-gated opportunities
const gated = await sdk.opportunities.search({ access: "kyc" });

Combined Filters

TypeScript

const candidates = await sdk.opportunities.search({
  chainId: [1, 42161],
  asset: Asset.STABLE,
  minApy: 4,
  minTvl: 500_000,
  access: "permissionless",
});

Multi-Chain Support

Every entity in the SDK vNext includes a chainId field. The SDK can be initialized with multiple chains and will aggregate results across all of them:

TypeScript

const sdk = await GearboxSDK.init({
  chains: [1, 42161, 10, 8453],
  startFromCache: true,
});

// Results span all configured chains
const allOpps = await sdk.opportunities.search();

// Group by chain
const byChain = Object.groupBy(allOpps, opp => opp.chainId);

Freshness Metadata

Discovery responses include metadata about data freshness and sources, so you can make trust decisions:

TypeScript

const result = await sdk.opportunities.search();

console.log(`Data as of: ${result.meta.asOf}`);
console.log(`Sources: ${result.meta.sources.join(", ")}`);
console.log(`Backend available: ${result.meta.backendAvailable}`);

Meta Field	Type	Description
`asOf`	`string`	ISO timestamp of the data snapshot
`sources`	`string[]`	Data sources used (e.g. `["backend", "onchain"]`)
`backendAvailable`	`boolean`	Whether the backend enrichment service was reachable

When the backend is unavailable, the SDK falls back to on-chain data. APY enrichment and points data may be missing in this mode.

Method Signatures

Method	Returns	Description
`sdk.opportunities.search(filters?)`	`Opportunity[]`	Unified discovery across pools, strategies, and markets
`sdk.pools.list(filters?)`	`PoolOpportunity[]`	LP pool discovery
`sdk.strategies.list(filters?)`	`StrategyOpportunity[]`	Leveraged strategy discovery
`sdk.pools.getDetail(id)`	`PoolDetail`	Full pool due-diligence data
`sdk.strategies.getDetail(id)`	`StrategyDetail`	Full strategy due-diligence data

Learn More

Markets Data — reading pool metrics and credit manager configuration
History & Events — historical APY, utilization, and governance changes
Positions — opening, adjusting, and closing positions
Pool Operations — low-level ERC-4626 pool interactions