# Opportunities

> Markdown export of the Gearbox Protocol documentation page for agents and retrieval systems.

Canonical page: https://docs.gearbox.finance/developers/gm-markets-opportunities
Source file: content/developers/gm-markets-opportunities.mdx
Section router: https://docs.gearbox.finance/developers/llms.txt
Section full export: https://docs.gearbox.finance/developers/llms-full.txt

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](https://docs.gearbox.finance/developers/gm-markets-data) — reading pool metrics and credit manager configuration
- [History & Events](https://docs.gearbox.finance/developers/gm-markets-history) — historical APY, utilization, and governance changes
- [Positions](https://docs.gearbox.finance/developers/gm-accounts-positions) — opening, adjusting, and closing positions
- [Pool Operations](https://docs.gearbox.finance/developers/gm-markets-pools) — low-level ERC-4626 pool interactions