<!-- canonical: https://docs.melee.markets/resolver-api/agents | markdown: https://docs.melee.markets/resolver-api/agents.md | index: https://docs.melee.markets/llms.txt -->
# For agents and automation

This site is built to be read by programs as well as people. If you are an AI agent or an automated
integration client, use the entry points below instead of scraping HTML. **Access always requires the
partner password**; there is no separate machine credential.

## Authenticating with the password

The site is password-protected at the edge. An unauthenticated request receives `401 Authentication Required`
with an HTML page offering the visitor password form (and a Vercel team login you can ignore); this applies to every path, including `/llms.txt`, the `.md` mirrors and the
OpenAPI file, and regardless of `Accept` headers. Authenticate the way a browser does:

1. `POST` to the page URL you want (the form has no separate action; it posts back to the same URL) with
   `Content-Type: application/x-www-form-urlencoded` and the body `_vercel_password=<partner password>`.
   The field name is verified against the live gate.
2. Vercel answers `303 See Other` to that URL and sets the session cookie `_vercel_jwt` for the
   `docs.melee.markets` host (`Path=/; Secure; HttpOnly; SameSite=Lax`, `Max-Age` 90 days). Persist it with a
   cookie jar; a wrong password returns `401` with no cookie.
3. Send the cookie on every subsequent request. It stays valid for 90 days or until Melee rotates the
   password, at which point requests return `401` again and you repeat step 1. All of this was verified against
   the live gate.

```bash
# 1. exchange the password for the session cookies (follow the redirect, keep the jar)
curl -sS -L -c melee-docs.cookies -o /dev/null \
  -X POST https://docs.melee.markets/ \
  --data-urlencode "_vercel_password=$MELEE_DOCS_PASSWORD"

# 2. read the index as Markdown
curl -sS -b melee-docs.cookies -H "Accept: text/markdown" https://docs.melee.markets/llms.txt
```

Store the password with your other Melee credentials and never embed it in URLs or logs. The password grants
read access to documentation only; it is unrelated to your API credentials.

## Discovery

| URL | Content |
|---|---|
| `/llms.txt` | Index of every page with a one-line description, in [llmstxt.org](https://llmstxt.org) format. Start here. |
| `/llms-full.txt` | Every page concatenated into one Markdown document, each section prefixed with its canonical URL. About 110k characters; if your fetch limit is smaller, read pages individually from `/llms.txt`. |
| `/resolver-api/openapi.yaml` | OpenAPI 3.1 description of the Melee Resolver API; the endpoints you implement are described under `webhooks`. |
| `/sitemap.xml` | All page URLs with their Markdown alternates. |

## Reading pages as Markdown

Every page is available as clean Markdown, without navigation or scripts:

- **URL suffix:** append `.md` to any page path. `/resolver-api/changes` → `/resolver-api/changes.md`. Section
  pages also answer at `/index.md` (`/resolver-api/index.md`).
- **Content negotiation:** request the HTML URL with `Accept: text/markdown` (or with `text/markdown` ranked
  above `text/html`) and the server returns the Markdown mirror with `Content-Type: text/markdown`.
- **Query parameter:** `?format=md` for clients that cannot set headers.

HTML responses advertise their alternates: `<link rel="alternate" type="text/markdown">` and a `Link` header
with `rel="alternate"`, plus `rel="describedby"` pointing at `/llms.txt`. Each page's Markdown begins with an
HTML comment naming its canonical URL, its Markdown URL and the index.

## Conventions that help you

- One topic per page; every page has a single H1 and a `description` in its metadata.
- Headings are stable and anchorable; the anchor is the lowercase, hyphenated heading text.
- Every enumeration and bound is collected on the [Integration reference](/resolver-api/reference) page.
- Byte-exact test vectors for signing, hashing and evidence are on the same page; validate your implementation
  against them before contacting Melee.
- Code blocks are tagged with their language (`json`, `http`, `text`, `js`, `bash`).
- Pages stay under 50k characters.

## Machine-readable API description

`/resolver-api/openapi.yaml` is the normative description of request and response shapes. When prose and
OpenAPI disagree, tell your Melee integration lead; until resolved, treat the prose as authoritative for
semantics and the OpenAPI document as authoritative for field names and types.

## What not to do

- Do not scrape the HTML; the Markdown mirrors are the same content with far fewer bytes.
- Do not share the partner password outside your organization or place it in URLs.
- Do not act on `/llms-full.txt` alone for anything involving signing or hashing without re-reading the
  Integration reference page's test vectors.
