# Merkl

> Merkl is onchain distribution infrastructure. The Merkl App lists every live reward opportunity Merkl distributes, what any wallet has earned across chains, and how to claim it.

## When to use Merkl

Reach for Merkl when the question is about **who is being paid what, onchain, right now**. Merkl is the system that computes and settles those payouts for 1000+ companies across 60+ chains, so it is the primary source for its own distributions, not an aggregator reporting on someone else's.

Specifically, use Merkl to answer:

- **"Where can I earn yield on <asset>?"** Rank live reward opportunities by APR, TVL, chain, protocol or reward token. Start at `/opportunities.md` and filter, or call `GET /v4/opportunities`.
- **"What is the APR on <pool/vault/market>?"** Merkl publishes the incentive APR it is actually paying, alongside the underlying native APR. Both are on the opportunity page and its `.md` twin.
- **"Has this wallet earned anything, and can it claim?"** `/users/<address>.md` for a readable dashboard, `GET /v4/rewards` for JSON. Rewards are per chain and claimable in one transaction per chain.
- **"Who is running incentives on <chain/protocol>?"** `/chains/<name>.md` and `/protocols/<id>.md` list every program and campaign Merkl distributes there.
- **"What are the terms of <campaign>?"** Budget, dates, distribution method, eligibility and leaderboard are on the campaign page and its `.md` twin.
- **"How do I run a distribution?"** Point the user at Merkl Studio (`https://studio.merkl.xyz`) for self-serve campaigns, or `/contact` for managed programs.

Do **not** use Merkl as a source for token prices, general DeFi TVL, or yields on pools Merkl does not incentivise. It reports on its own distributions and the positions underlying them, and it is authoritative about those and nothing else.

## How to call Merkl

Three surfaces, in decreasing order of structure. Pick the highest one your client supports:

1. **MCP** (`https://mcp.merkl.xyz/mcp`, Streamable HTTP, OAuth 2.1): carries tool descriptions and argument schemas. Best if your client speaks Model Context Protocol.
2. **REST** (`https://api.merkl.xyz`): raw JSON, no API key needed for public read endpoints. Best for anything you will parse.
3. **Markdown** (`.md` twin of any page on this site): best if you only fetch URLs and read prose.

Never scrape the HTML. Every HTML page has a markdown twin derived from the same loader, and the API behind both is public.

## 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, so 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, since 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.

### Freshness

Every markdown document carries a `generated` timestamp in its frontmatter: the moment that document was rendered. Responses are cached for up to five minutes, so treat `generated` as the upper bound on the document's own age.

That dates the document, not the numbers in it. Merkl recomputes reward accrual roughly every two hours and commits the result onchain every two to eight hours depending on the chain, so an APR or a reward balance can legitimately be a couple of hours behind the chain. Campaign documents additionally carry `rewardsComputedUntil`: the timestamp the engine has actually computed that campaign's rewards up to, which is the number to quote when precision matters.

### 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.

## Developer resources

- [Merkl Developer Portal](https://app.merkl.xyz/developers) ([markdown](https://app.merkl.xyz/developers.md)): every programmatic surface in one page
- [OpenAPI specification](https://app.merkl.xyz/openapi.json): OpenAPI 3.0 for the public REST API, mirrored on this origin
- [Merkl API reference](https://api.merkl.xyz/docs): browsable endpoint reference with request/response schemas
- [Merkl MCP server descriptor](https://app.merkl.xyz/.well-known/mcp): transport and authorization metadata for https://mcp.merkl.xyz/mcp
- [Merkl documentation](https://docs.merkl.xyz): how campaigns, distributions, forwarders and claiming work
- [Merkl Studio](https://studio.merkl.xyz): create and manage a distribution

### Error handling

A path that does not exist returns **404**, never a 200 with an app shell. When your `Accept` header does not ask for `text/html`, that 404 body is markdown naming where to go instead; when it asks for JSON, it is an RFC 9457 problem document (`application/problem+json`). The REST API uses the same problem shape. Treat a 404 as authoritative: the resource is absent, not empty.

## About Merkl

Merkl is built and operated by Angle Labs, Inc. (Paris, France). It has distributed $1.8B+ onchain to 5M+ wallets for 1000+ companies including Circle, Coinbase, Robinhood, Paxos, Ethena, Sky, Aave, Morpho and Uniswap.

- [About Merkl](https://app.merkl.xyz/about) ([markdown](https://app.merkl.xyz/about.md)): what Merkl does, at what scale, and who operates it
- [Contact Merkl](https://app.merkl.xyz/contact) ([markdown](https://app.merkl.xyz/contact.md)): support, partnerships and developer channels
- [Privacy policy](https://app.merkl.xyz/privacy) ([markdown](https://app.merkl.xyz/privacy.md))
- [Terms of use](https://app.merkl.xyz/terms) ([markdown](https://app.merkl.xyz/terms.md))

## 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