Skip to main content

​
CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

​
Project Overview

GoldRush API documentation site built with Mintlify. Content is authored in MDX (Markdown + JSX). The site documents multiple products: Foundational API (REST), Streaming API (GraphQL/WebSockets), CLI, x402 protocol, and MCP Server.

​
Commands

TaskCommand
Local dev servernpm run dev (runs mintlify dev on localhost:3000)
Run generation pipelinenpm run generate (interactive TUI to select scripts)
Populate changelognpm run script:populate-changelog
Check nav consistencynode s/check-nav-consistency.js
Install dependenciesyarn install

​
Content Architecture

​
Hand-authored vs Generated content

Hand-authored (safe to edit directly):
  • goldrush-foundational-api/ — API overview, quickstart, authentication
  • goldrush-streaming-api/ — Streaming API guides
  • goldrush-cli/ — CLI documentation
  • goldrush-x402/ — x402 protocol docs
  • resources/ — Feature-specific guides
  • overview.mdx, faq.mdx, error-handling.mdx, root-level pages
  • snippets/ — Reusable MDX components (some are generated, see below)
Auto-generated (do NOT edit directly — regenerate instead):
  • api-reference/foundational-api/**/*.mdx — from OpenAPI + DatoCMS metadata
  • api-reference/streaming-api/**/*.mdx — from YAML definitions
  • api-reference/openapi.json — compiled OpenAPI spec
  • chains/*.mdx (except chains/overview.mdx) — from DatoCMS chain data
  • changelog/*.mdx — from DatoCMS
  • snippets/supported-chains-dexes.mdx — from Streaming API query
  • llms.txt, llms-full.txt — LLM context files
  • skills/*/references/*.md — per-product skill reference files for AI agents
  • data/*.json — intermediate data files
docs.json is the source of truth for site structure. Generation scripts read from and write to it. Keep it in sync with page files.

​
Data Flow

Conjure YAML (api-defn/src/) → build-conjure → data/conjure-output.json
DatoCMS endpoints API        → get-apiendpoints → data/dato-apiendpoints.json
DatoCMS chains API           → get-chains.js → data/dato-chains.json

conjure-output + dato-apiendpoints + docs.json → convert-openapi.js → api-reference/foundational-api/**
dato-chains + dato-apiendpoints + docs.json    → generate-chain-docs.js → chains/*.mdx
YAML defs + dato-apiendpoints + docs.json      → convert-streaming.js → api-reference/streaming-api/**

​
Generation Pipeline (9 steps, order matters)

  1. ./s/build-conjure — compile Conjure YAML schemas
  2. ./s/get-apiendpoints — fetch endpoint metadata from DatoCMS
  3. node ./s/get-chains.js — fetch chain metadata from DatoCMS
  4. node ./s/convert-openapi.js — generate Foundational API MDX pages
  5. node ./s/generate-chain-docs.js — generate per-chain MDX pages
  6. node ./s/fetch-streaming-chains-dexes.js — fetch supported chains/DEXes
  7. node ./s/convert-streaming.js — generate Streaming API MDX pages
  8. node ./s/generate-llm-txt.js — generate LLM context files and skills reference files
  9. node ./s/populate-changelog.js — generate changelog (optional)
Steps 1-3 fetch data; steps 4-8 generate content from that data. Use npm run generate for the interactive runner.

​
MDX Conventions

Frontmatter format: 
---
title: "Page Title"
sidebarTitle: "Nav Label"    # optional, shorter name for sidebar
description: "SEO description"
---
Common Mintlify components used: <Card>, <CardGroup>, <CodeGroup>, <Accordion>, <AccordionGroup>, <Tip>, <Info>, <Warning>, <Note>, <Steps>, <Columns>.

​
Agent Skills (skills/)

Per-product reference files for AI agent consumption, generated by step 8 of the pipeline. Each product has a hand-authored SKILL.md routing index and auto-generated references/*.md files. 
skills/
├── goldrush-foundational-api/   # REST API, 36 endpoints, 100+ chains
│   ├── SKILL.md                # Hand-authored routing index (do NOT regenerate)
│   └── references/              # Auto-generated (7 files)
├── goldrush-streaming-api/      # GraphQL/WebSocket, 8 endpoints, 10 chains
│   ├── SKILL.md
│   └── references/              # Auto-generated (3 files)
├── goldrush-x402/               # Pay-per-request proxy, 60+ endpoints
│   ├── SKILL.md
│   └── references/              # Auto-generated (3 files)
└── goldrush-cli/                # 17 CLI commands, MCP server
    ├── SKILL.md
    └── references/              # Auto-generated (1 file)
SKILL.md files are hand-crafted — edit them directly. references/ files are auto-generated — regenerate with node s/generate-llm-txt.js. Key conventions for skills content:
  • SKILL.md must have YAML frontmatter with name and description fields (per agent skills spec)
  • description is the primary trigger mechanism — include what the skill does, trigger contexts, and cross-routing to sibling skills
  • SKILL.md body should stay generic (no hardcoded endpoint counts/chain lists); delegate specifics to auto-generated reference files
  • Reference file tables use “When to read” column to guide the model
  • Reference files must be self-contained: no links to repo MDX pages, only external URLs and #section anchors
  • MDX imports and [Read more] links are stripped during generation; local links [text](/path) → **text** (bold)
  • Foundational API reference files include structured parameter and response field tables extracted from the OpenAPI spec (api-reference/openapi.json)
  • Content headings from source MDX files are bumped down one level in formatEndpointSection() to nest correctly under the endpoint H2

​
Key Files

  • docs.json — Mintlify site config and navigation tree
  • s/run.js — TUI orchestrator for generation pipeline
  • s/generate-llm-txt.js — generates llms.txt, llms-full.txt, and skills/*/references/*.md
  • s/sdk-methods-mapping.json — maps TypeScript SDK methods to OpenAPI operations
  • api-defn/src/ — Conjure YAML schema definitions (base, balances, nft, transactions, queries, subscriptions)
  • data/ — intermediate JSON data files consumed by generation scripts