# Merkl

> Merkl is the platform for DeFi reward opportunities — explore live liquidity programs, earn yield, and claim tokens.

## Start here

Agents should begin at **[https://app.merkl.xyz/opportunities.md](https://app.merkl.xyz/opportunities.md)** — a paginated markdown index of every live opportunity on Merkl. Append `?page=N&items=M` to paginate; every row links to the entity's markdown twin.

## Entry points

- [Opportunities (markdown, paginated)](https://app.merkl.xyz/opportunities.md) — recommended starting point
- [Chains (markdown, paginated)](https://app.merkl.xyz/chains.md)
- [Protocols (markdown, paginated)](https://app.merkl.xyz/protocols.md)
- [Tokens (markdown, paginated)](https://app.merkl.xyz/tokens.md)
- [Programs (markdown, paginated)](https://app.merkl.xyz/programs.md)
- [Opportunities (HTML)](https://app.merkl.xyz/) — the canonical user-facing site

## Navigating the markdown surface

Every public entity has a markdown twin reachable by suffixing the canonical URL with `.md`. The markdown twins are derived from the same loaders as the HTML pages — what you see in markdown is exactly what the HTML page renders.

### URL conventions

- **Indexes** (paginated lists):
  - `/opportunities.md` — every opportunity
  - `/chains.md` — every supported chain
  - `/protocols.md` — every protocol
  - `/tokens.md` — every token (reward + underlying)
  - `/programs.md` — every program
- **Entities** (one document per resource):
  - `/opportunities/<id>.md` — opportunity detail + paginated campaigns table
  - `/chains/<name>.md` — chain detail
  - `/protocols/<id>.md` — protocol detail + paginated opportunities table
  - `/tokens/<symbol>.md` — token detail + paginated opportunities table
  - `/programs/<id>.md` — program detail + paginated opportunities table
- **Nested entities** (sub-resources of an opportunity):
  - `/opportunities/<id>/campaigns/<campaignId>.md` — campaign overview, distribution, advanced, linked sections
  - `/opportunities/<id>/campaigns/<campaignId>/leaderboard.md` — paginated leaderboard ranks
- **Wallet dashboards** (deliberately not enumerated — addresses are unbounded):
  - `/users/<address>.md` — reward totals, rewards by chain, active opportunities. Reachable only when the address is already known.

### Pagination

Any markdown index or sub-table is paginated via the URL: append `?page=N&items=M` (both 1-indexed). Each document declares its `page`, `items`, and `totalPages` in the YAML frontmatter, prints a `Pagination` key/value block showing what's currently visible, and emits `← Previous`, `Page 1`, `Page N (last)`, `Next →` link rows above and below the table.

### Cross-navigation

Every detail page opens with a `## Back to` section linking up to its parents. Every table cell that names another entity (chain, protocol, reward token, parent opportunity) is itself a markdown link to that entity's `.md` — so an agent can pivot sideways without going back to the index.

## Programmatic access — REST API

When you need raw data instead of formatted markdown, query the public Merkl API at **`https://api.merkl.xyz`**. The API is the authoritative source the website itself reads from; the markdown views are presentation-layer wrappers around the same endpoints.

Useful endpoints (all under `https://api.merkl.xyz/v4/`):

- `GET /v4/opportunities` — list opportunities (supports `chainId`, `status`, `sort`, `order`, `page`, `items`, `mainProtocolId`, `rewardTokenSymbol`, ...)
- `GET /v4/opportunities/:id` — one opportunity
- `GET /v4/opportunities/:id/campaigns` — campaigns for an opportunity
- `GET /v4/chains` — list supported chains
- `GET /v4/protocols` — list protocols
- `GET /v4/rewards` — leaderboard rows for a campaign (`chainId`, `campaignId`, `page`, `items`)
- `GET /v4/tokens` — token metadata

Most list endpoints honour `?page=N&items=M` identically to the markdown views, so an agent can stay paginated when switching between `.md` and JSON.

## Structured data (JSON-LD)

Every HTML page embeds schema.org structured data in `<script type="application/ld+json">` — `FinancialProduct` for opportunities, `Organization` for protocols, `Place` for chains, etc. Use this when scraping HTML if markdown isn't sufficient.

## Sitemap & robots

- [`/sitemap.xml`](https://app.merkl.xyz/sitemap.xml) — canonical URL list (HTML + markdown variants for top-level + chain + protocol + program pages)
- [`/robots.txt`](https://app.merkl.xyz/robots.txt) — crawl policy