> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trails.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Markets & Providers

> Discover markets and supported providers at runtime

Every `lend` and `deposit` action needs a `marketId`.

## React hooks

Use `useEarnMarkets`, `useEarnProviders`, and `useEarnBalances` inside a React tree wrapped with `TrailsProvider`:

```tsx theme={null}
import { useEarnMarkets, useEarnProviders, useEarnBalances } from '0xtrails'

function MarketPicker({ walletAddress }: { walletAddress: `0x${string}` }) {
  const { data: providers } = useEarnProviders()

  const { data: markets, total, isLoading } = useEarnMarkets({
    chain: 'base',
    type: 'lending',         // "lending" | "vault"
    provider: 'aave',        // optional
    search: 'usdc',          // optional free-text
    sortBy: 'rewardRateDesc',
    limit: 20,
    offset: 0,
  })

  const { data: balances } = useEarnBalances({
    walletAddress,
    chain: 'base',
  })

  // markets[i].id → pass to lend / deposit
  // balances[i].yieldId → match against market.id
}
```

### `useEarnMarkets` filters

| Field      | Type                          | Description                        |
| ---------- | ----------------------------- | ---------------------------------- |
| `chain`    | `ChainIdentifier`             | Chain name or ID                   |
| `type`     | `"lending"` \| `"vault"` \| … | Market category                    |
| `provider` | `ProviderId`                  | Restrict to one protocol           |
| `search`   | `string`                      | Free-text search over market names |
| `sortBy`   | `SortBy`                      | e.g. `"rewardRateDesc"`            |
| `limit`    | `number`                      | Page size                          |
| `offset`   | `number`                      | Page offset                        |

Each `EarnMarket` exposes `id`, `rewardRate`, `statistics.tvlUsd`, `metadata.*`, `providerId`, and more.

Use these hooks in browser apps to discover supported markets, providers, and the user's existing earn positions before building an action list.

### `useEarnBalances`

Fetch a wallet's earn balances for one chain:

```tsx theme={null}
const { data: balances, errors, isLoading } = useEarnBalances({
  walletAddress: '0x9ec762D784B653E168d93eA3078B023d8958dBc6',
  chain: 'polygon',
})
```

Fetch balances across multiple chains in a single backend request:

```tsx theme={null}
const { data: balances } = useEarnBalances({
  walletAddress,
  chains: ['polygon', 'ethereum', 'base'],
})
```

Restrict the lookup to one market:

```tsx theme={null}
const { data: balances } = useEarnBalances({
  walletAddress,
  chain: 'polygon',
  marketId: 'polygon-usdc-aave-v3-lending',
})
```

| Field           | Type                | Description                                      |
| --------------- | ------------------- | ------------------------------------------------ |
| `walletAddress` | `string`            | Wallet whose earn positions should be fetched    |
| `chain`         | `ChainIdentifier`   | Single chain name, ID, or viem chain object      |
| `chains`        | `ChainIdentifier[]` | Multiple chains; mutually exclusive with `chain` |
| `marketId`      | `string`            | Optional market ID to filter one position        |
| `arguments`     | `object`            | Optional market-specific balance arguments       |
| `enabled`       | `boolean`           | Set `false` to disable the query                 |

## End-to-end example

Wire a market picker into a typed action:

```tsx theme={null}
import {
  useQuote,
  useEarnMarkets,
  lend,
} from '0xtrails'

function LendWithMarketPicker() {
  const { data: markets } = useEarnMarkets({
    chain: 'base',
    type: 'lending',
    search: 'USDC',
    sortBy: 'rewardRateDesc',
    limit: 5,
  })

  const market = markets... // Choose your market

  const { send } = useQuote({
    from: { chain: 'arbitrum', token: 'USDC' },
    to:   { chain: 'base',     token: 'USDC', amount: '100' },
    actions: market
      ? [lend({ marketId: market.id, amount: "100" })]
      : [],
  })

  return (
    <button disabled={!send} onClick={() => send?.()}>
      Lend on {market?.metadata.name ?? '…'}
    </button>
  )
}
```