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

openapi/v1.json is a GENERATED file — never edit it directly. The nightly refresh-latency workflow runs node scripts/generate-catalog.mjs, which rebuilds it from scripts/v1.raw and commits the result: any direct edit to openapi/v1.json (also catalog/*, legacy-redirect-map.json) is silently reverted within a day. This is exactly how the Lightning-rename, <br/>, code-sample, and real-example fixes were all lost once. Instead:
  • Content changes (descriptions, examples, code samples, parameters) → edit scripts/v1.raw, then run node scripts/generate-catalog.mjs and commit raw + outputs.
  • Systematic corrections (renames, MDX escaping) → add a transform in scripts/generate-catalog.mjs (see the “Known content corrections” section: Lightning rename, bare-<br> self-closing).
  • Keyless runs of the generator keep the cached latency snapshot; only CI (with CRYPTOQUANT_API_KEY) refreshes it. The generator is idempotent — re-running must produce no diff.
openapi/v2.json is still hand-maintained; it is serialized with json.dumps(data, indent=1, ensure_ascii=False) and re-dumping is byte-exact. Prefer surgical string replacement 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.