Skip to content

CLAUDE.md

Latest commit

 

History

History
73 lines (54 loc) · 4.21 KB

CLAUDE.md

File metadata and controls

73 lines (54 loc) · 4.21 KB
Raw

CLAUDE.md

Documentation-only repo (no application code): OpenAPI spec (YAML) + Mintlify docs (MDX). Grid is an API for global payments across fiat, stablecoins, and Bitcoin.

Critical Rules

  • Edit OpenAPI in openapi/ — never edit the root openapi.yaml directly (it's generated by bundling)
  • Bump info.version only when a breaking change ships — at which point it should match a new servers.url path
  • Run make build after any OpenAPI changes to rebundle
  • Run make lint before committing
  • Mintlify CLI must be version 4.2.284 — newer versions (e.g., 4.2.312) have a bug where API reference pages render blank. Install with npm install -g mintlify@4.2.284 --force
  • Requires Node.js v20 or v22 — Mintlify does not support Node 25+. If needed: export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
  • Use snippets from mintlify/snippets/ instead of duplicating content across use cases
  • Follow writing standards in mintlify/CLAUDE.md for all documentation content
  • MDX files require frontmatter with title and description
  • React hooks (useState, useEffect, etc.) work in MDX. If the acorn parser throws, it's usually a JS expression issue (e.g., template literals in JSX curlies), not the hook itself.

Commands

make install        # Install dependencies
make build          # Bundle OpenAPI spec (openapi/ → openapi.yaml + mintlify/openapi.yaml)
make lint           # Lint OpenAPI + markdown + run mint openapi-check
make lint-openapi   # Lint OpenAPI only
make lint-markdown  # Lint markdown only
make mint           # Serve docs locally (cd mintlify && mint dev)

File Structure

openapi/                    # Source OpenAPI YAML (edit here)
  openapi.yaml              #   Root spec with $ref references
  paths/                    #   Endpoint definitions by domain
  components/schemas/       #   Reusable schema definitions
  webhooks/                 #   Webhook event definitions
openapi.yaml                # Generated bundle (don't edit)
mintlify/                   # Mintlify documentation (MDX)
  docs.json                 #   Navigation and theme config
  snippets/                 #   Shared MDX snippets (use these to avoid duplication)
  styles/base.css           #   CSS overrides
.redocly.yaml               # Redocly bundler/linter config

OpenAPI

Bundled and linted with Redocly (@redocly/cli), configured in .redocly.yaml. Lint rules enforce operation descriptions, operation IDs, and security definitions.

Helper scripts (scripts/)

For the USDB embedded wallet → USD bank offramp flow, see scripts/README.md. It walks through onboarding, on-ramp, and off-ramp with copy-pasteable curl, and points at the only operations that can't be done with curl alone:

  • HPKE bundle decrypt (the encryptedSessionSigningKey returned by POST /auth/credentials/{id}/verify)
  • Turnkey API stamp construction (the Grid-Wallet-Signature header on POST /quotes/{id}/execute)

Both are wrapped by scripts/embedded-wallet-sign.js (uses @turnkey/crypto + @turnkey/api-key-stamper). One-time setup: cd scripts && npm install.

Important gotcha: the USDB embedded wallet's Turnkey sub-org and Spark network wallet aren't fully bootstrapped when a customer is created. Verify the auto-created EMAIL_OTP auth credential on the USDB account before the first quote, otherwise on-ramp quotes fail with to_network INTERNAL_FUNDED_FIAT does not support USDB. This is documented in scripts/README.md step 1.4.

Read scripts/README.md whenever the task involves Turnkey signing, offramp, or Grid-Wallet-Signature.

CSS Overrides (mintlify/styles/base.css)

  • Tailwind utility classes (e.g., mb-3.5) are hard to override even with !important — use negative margins on sibling elements as a workaround
  • Test selectors with border: 2px solid red !important to confirm they match before debugging property conflicts
  • Mobile nav is in #mobile-nav; modals/portals are in #headlessui-portal-root

Troubleshooting: Blank API Reference Pages

  1. Restart dev server: pkill -f "mint.*dev" && cd mintlify && mint dev
  2. Verify CLI version is 4.2.284
  3. Run cd mintlify && mint openapi-check openapi.yaml