Skip to main content

​
CLAUDE.md

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

​
Tab → source map

​
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)

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

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