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

# CLAUDE

# CLAUDE.md

CryptoQuant API documentation, built with **Mintlify**. Config: `docs.json`. Pages are `.mdx`;
API reference is generated from OpenAPI specs.

## Tab → source map

| Tab                                     | Rendered from                                                                                                                                          |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| API v1                                  | `openapi/v1.json` (Mintlify OpenAPI, `directory: api-reference`) — \~243 endpoints                                                                     |
| API v2                                  | `v2/*.mdx` pages; each `v2/community/*.mdx` pulls its reference from `openapi/v2.json` via frontmatter `openapi: "openapi/v2.json GET /community/..."` |
| Indicator API                           | hand-written `indicator-api/*.mdx` (Alpha product, host `alpha.cryptoquant.com`)                                                                       |
| Data Guide / Data Catalog / Get Started | hand-written `.mdx`                                                                                                                                    |

## MDX rendering gotchas (these break the build silently)

Mintlify compiles descriptions and page bodies as MDX. A raw `<...>` that isn't a real
component is parsed as JSX; compilation fails and the **entire block renders as raw text**
(literal `###`, `|` tables, backticks). Rules:

* **Self-close void tags**: `<br/>`, not `<br>`. Same for `<hr/>`, `<img ... />`. Bare `<br>`
  was the cause of the Lightning/Mempool "broken page" reports.
* **No raw angle-bracket placeholders in prose or frontmatter**: `<YOUR_API_KEY>`,
  `<token>`, `List<T>` etc. break MDX unless they are inside a code span (`` `<YOUR_API_KEY>` ``),
  a code fence, or written as the entity `&lt;`. Frontmatter `description:` is compiled too —
  it must not contain a raw `<...>`.
* Inside fenced/inline code, `<...>` and `{...}` are safe. `{/* ... */}` is a valid MDX comment.
  `$$ ... \frac{}{} ... $$` is KaTeX, not JSX — leave it.

Quick scan for bare void tags: `grep -n '<br>' openapi/*.json` (expect 0; only `<br/>`).

## Code-sample conventions (keep all three APIs identical)

Every `x-codeSamples` / hand-written example uses the **same shape** and the placeholder
token **`<YOUR_API_KEY>`** (never `${access_token}`, `{access_token}`, `$CRYPTOQUANT_API_KEY`).

* **Shell**: `curl -X GET "URL" \` newline `-H "Authorization: Bearer <YOUR_API_KEY>"`
  (`-X GET` is explicit even though GET is curl's default; public/no-auth endpoints omit the `-H`).
* **JavaScript / NodeJS / Ruby / Python**: match the templates already in `openapi/v2.json`
  (auth header included, `<YOUR_API_KEY>`). Language order: Shell, JavaScript, NodeJS, Ruby, Python.

Auth is required on every authenticated example — do not ship a bare `curl "URL"` for a
protected endpoint.

## `limit` parameter (differs by API — do not copy blindly)

| API                      | default | min | max    |
| ------------------------ | ------- | --- | ------ |
| v1                       | 100     | 1   | 100000 |
| v2                       | 100     | 1   | 10000  |
| Indicator API (equities) | —       | 1   | 10000  |

Exception: `/btc/flow-indicator/stablecoins-ratio` (v1) caps `limit` at 1000, not 100000 — intentional.

## Editing the OpenAPI JSON specs

Both specs are serialized with `json.dumps(data, indent=1, ensure_ascii=False)`.
Re-dumping `openapi/v2.json` is byte-exact. For `openapi/v1.json`, Python rewrites four float
literals in scientific notation — restore them after dumping:
`1.321e-05 → 0.00001321`, `1.221e-05 → 0.00001221`. Prefer surgical string replacement on the
raw text for small edits to keep diffs minimal.

## Verifying changes locally

```bash theme={null}
npx -y mint@latest dev --port 3111   # http://localhost:3111
```

`.mdx` edits hot-reload. **Changes to `openapi/*.json` require restarting the dev server**
(the parsed spec is cached). Confirm a page renders with 0 console errors before claiming done.