agentleFS
Sign inStart free
coinbasecoinbase/x402/docs/AGENTS.md

x402

AGENTS.md168 starsChanged 28 days agoApache-2.0View on GitHub

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 1

    1. x402-foundation/x402★ 6.8k100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,774 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository2 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

28 rules. About 0 are common, 18 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈18

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use TypeScript for primary code examples (it's the reference SDK)

    line 35
  2. Distinctive:

    Keep scheme overviews network-agnostic.

    line 37
  3. Distinctive:

    Write for developers with 2-5 years experience

    line 39
  4. Very specific:

    Use MDX components (<Tabs>, <Tab>, <Callout>, <Card>) for interactive content

    line 40
  5. Distinctive:

    Use real-world parameter values in examples (not foo/bar placeholders)

    line 42
  6. Very specific:

    DO: Add new pages to docs.json navigation

    line 45
  7. Distinctive:

    DO: Include code examples from real SDK files (not made-up snippets)

    line 46
  8. Very specific:

    DO: Link to relevant specs in specs/ for protocol details

    line 47
  9. Very specific:

    DO: Use <Tabs> for multi-language code examples

    line 48
  10. Distinctive:

    DO: Add frontmatter (title, description) to all pages

    line 49
  11. Distinctive:

    DO: Link scheme pages to relevant server/client examples

    line 50
  12. Very specific:

    DON'T: Duplicate protocol details from specs/ — link instead

    line 51
  13. Very specific:

    DON'T: Add pages without updating docs.json

    line 52
  14. Very specific:

    Use .md for standard markdown pages

    line 69
  15. Very specific:

    Use .mdx for pages with React components (Tabs, Cards, etc.)

    line 70
  16. Distinctive:

    All links work (no broken references)

    line 79
  17. Distinctive:

    When triggered by GitHub Actions or other automated workflows:

    line 87
  18. Distinctive:

    ONLY update documentation directly related to the specific code changes

    line 90
  19. Distinctive:

    Update SDK references if API signatures change

    line 92
  20. Distinctive:

    Update quickstart guides if SDK usage patterns change

    line 93
  21. Distinctive:

    Update core-concepts if protocol behavior changes

    line 94
  22. Distinctive:

    Add documentation for ecosystem partners not mentioned in the code change

    line 98
  23. Distinctive:

    Add documentation for features unrelated to the trigger

    line 99
  24. Distinctive:

    Create PRs for trivial changes (comment removal, formatting, etc.)

    line 100
  25. Distinctive:

    If the code changes are limited to:

    line 128
  26. Very specific:

    Test files only (*.test.ts, __tests__/, etc.)

    line 131
  27. Distinctive:

    When SDK code changes involve:

    line 141
  28. Very specific:

    Update sdk-features.md to reflect the current state.

    line 146

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Documentation Agent Instructions

Package Identity

  • Mintlify documentation source for docs.x402.org
  • MDX/Markdown files with docs.json as navigation configuration

Directory Structure

  • advanced-concepts/ — Advanced topics (lifecycle hooks, etc.)
  • core-concepts/ — Protocol explanations (HTTP 402, client-server, facilitator, wallet)
  • schemes/ — Payment scheme documentation with end-user server/client setup
  • extensions/ — x402 extension documentation (Bazaar discovery, and future extensions)
  • getting-started/ — Quickstart guides for buyers and sellers (MDX files with tabs)
  • guides/ — How-to guides (MCP server, v1→v2 migration)
  • dev-tools/ — Curated third-party SDKs, extensions, and facilitators
  • introduction.md — Welcome/landing page
  • faq.md — Frequently asked questions
  • docs.json — Mintlify navigation and configuration
  • sdk-features.md - Feature list of SDKs

Code-to-Doc Mapping

  • Changes to typescript/packages/core/src/ affect Core Concepts docs
  • Changes to typescript/packages/mechanisms/, go/mechanisms/, or python/x402/mechanisms/ affect Payment Schemes docs and sdk-features.md
  • Changes to typescript/packages/extensions/src/ affect Extensions docs (Bazaar, etc.)
  • Changes to typescript/packages/*/src/ affect SDK references and quickstart guides
  • Changes to python/x402/ affect Python SDK references
  • Changes to python/x402/extensions/ affect Extensions docs
  • Changes to go/ affect Go SDK references
  • Changes to go/extensions/ affect Extensions docs
  • Changes to facilitator endpoints affect quickstart guides
  • Changes to specs/schemes/ may require updates to Payment Schemes docs
  • Changes to other specs/ files may require updates to Core Concepts docs
  • Curated third-party SDK, extension, or facilitator listings → update dev-tools/*.md

Style Guidelines

  • Use TypeScript for primary code examples (it's the reference SDK)
  • For scheme pages, lead with server setup before client setup
  • Keep scheme overviews network-agnostic; put network-specific behavior in the relevant scheme page section and link to specs for protocol details
  • Include error handling in all API examples
  • Write for developers with 2-5 years experience
  • Use MDX components (<Tabs>, <Tab>, <Callout>, <Card>) for interactive content
  • Show both success and error response examples for API endpoints
  • Use real-world parameter values in examples (not foo/bar placeholders)

Conventions

  • DO: Add new pages to docs.json navigation
  • DO: Include code examples from real SDK files (not made-up snippets)
  • DO: Link to relevant specs in specs/ for protocol details
  • DO: Use <Tabs> for multi-language code examples
  • DO: Add frontmatter (title, description) to all pages
  • DO: Link scheme pages to relevant server/client examples
  • DON'T: Duplicate protocol details from specs/ — link instead
  • DON'T: Add pages without updating docs.json
  • Git: Create PRs for review; NEVER commit directly to main

Touch Points / Key Files

  • introduction.md — Landing page
  • faq.md — Frequently asked questions
  • docs.json — Navigation and configuration (MUST update when adding pages)
  • core-concepts/*.md — Conceptual documentation
  • schemes/*.mdx — Payment scheme docs. Keep overview network-agnostic; individual scheme pages may include network-specific SDK setup and spec links
  • extensions/*.mdx — Extension documentation (Bazaar, future extensions)
  • advanced-concepts/*.mdx — Advanced topics (lifecycle hooks for custom workflows, etc.)
  • getting-started/*.mdx — Quickstart guides (MDX for tab components)
  • guides/*.md — How-to guides
  • dev-tools/*.md — Curated third-party SDKs, extensions, and facilitators
  • sdk-features.md — Update when SDK capabilities change

File Extensions

  • Use .md for standard markdown pages
  • Use .mdx for pages with React components (Tabs, Cards, etc.)

Common Gotchas

  • docs.json controls Mintlify navigation; pages not listed won't appear
  • Images/diagrams go in project root static/ directory
  • Code examples should reference actual SDK file paths
  • Links between pages should omit file extensions (e.g., ../core-concepts/http-402 not ../core-concepts/http-402.md)

Pre-PR Checks

  • All links work (no broken references)
  • New pages added to docs.json navigation
  • Code examples are from actual SDK files and compile
  • Frontmatter present on all pages (title, description)
  • MDX syntax is valid (run mint dev to verify)

Agent Behavior Rules (Automated Workflows)

When triggered by GitHub Actions or other automated workflows:

DO

  • ONLY update documentation directly related to the specific code changes
  • Focus on the files and commits mentioned in the trigger
  • Update SDK references if API signatures change
  • Update quickstart guides if SDK usage patterns change
  • Update core-concepts if protocol behavior changes

DO NOT

  • Perform general documentation audits or sync operations
  • Add documentation for ecosystem partners not mentioned in the code change
  • Add documentation for features unrelated to the trigger
  • Create PRs for trivial changes (comment removal, formatting, etc.)
  • Sync ecosystem partner data from typescript/site/app/ecosystem/ unless explicitly changed

Code-to-Doc Mapping (for automated updates)

Code ChangeDoc Update Required
typescript/packages/core/src/*.ts API changesCore Concepts, quickstart guides
typescript/packages/extensions/src/*.ts Extensions changesExtensions docs (Bazaar, etc.)
typescript/packages/mechanisms/**/*.ts API changesPayment Schemes docs, SDK Features
typescript/packages/*/src/*.ts API changesSDK reference, quickstart guides
python/x402/*.py API changesPython SDK reference
python/x402/mechanisms/**/*.py API changesPayment Schemes docs, SDK Features
python/x402/extensions/*.py Extensions changesExtensions docs
go/*.go API changesGo SDK reference
go/mechanisms/**/*.go API changesPayment Schemes docs, SDK Features
go/extensions/*.go Extensions changesExtensions docs
java/src/**/*.java API changesJava SDK reference
specs/schemes/*.md protocol changesPayment Schemes docs
specs/*.md protocol changesCore Concepts docs
specs/extensions/*.md Extensions changesExtensions docs (only if SDK implementation exists)
Comment removal, formattingNO update needed
Test file changesNO update needed
Build/CI config changesNO update needed
Ecosystem partner metadata onlyNO update needed (partners-data/ is not the docs source of truth; curated listings live in dev-tools/)

When to Skip (No PR)

If the code changes are limited to:

  • Removing or adding code comments
  • Formatting/style changes (prettier, linting)
  • Test files only (*.test.ts, __tests__/, etc.)
  • CI/build configuration only (.github/, turbo.json, etc.)
  • Dependency updates without API changes (package.json, go.mod, etc.)
  • Ecosystem partner metadata (typescript/site/app/ecosystem/partners-data/)
  • Legacy packages (typescript/packages/legacy/*, go/legacy, python/legacy)

Then report "No documentation updates needed" and do not create a PR.

SDK Feature Parity Document

When SDK code changes involve:

  • New mechanisms in */mechanisms/
  • New extensions in */extensions/
  • New hooks in client/server/facilitator files

Update sdk-features.md to reflect the current state. Check all three SDKs (typescript/, go/, python/) when updating.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free