About

This repository is the public source of truth for PubFi's long-form docs. It is separate from the private pubfi-mono repository so public docs, examples, issue templates, and agent-readable materials can be indexed by GitHub, search engines, and answer engines.

The v0 docs framework is Mintlify. The intended production shape is:

github.com/helixbox/pubfi-docs
  -> Mintlify GitHub integration
  -> docs.pubfi.ai
  -> root docs routes such as /getting-started/quickstart and /reference/api-reference
  -> linked from pubfi.ai product surfaces and legacy docs redirects
  -> canonical cross-links from README, llms.txt, Discovery, API Reference, MCP, and examples

Snapshot sources:

• pubfi-mono source snapshot at d0ee242963fc4a6477e79b2ece98ec3aece643ce;
• quantro-mono origin/main through f5a4dec934f4a2a6e072149d694df7984391b74b; and
• public Runtime OpenAPI, Registry v2 catalog, MCP tools/list, Staging and Production x402 challenges, and the repository-access acceptance workflows observed on 2026-07-27.

Start Here

• Docs home
• Project overview
• Quickstart
• Staging guide
• API key and runtime
• Registry gateway examples
• MCP client setup
• MCP client guides
• ChatGPT and Codex Plugin
• Accountless x402
• Payment and execution modes
• API Reference
• Agent-readable surfaces
• Security and public data

Published Surfaces

• Docs site: https://docs.pubfi.ai
• Product site: https://pubfi.ai
• Staging product site: https://stg.pubfi.ai
• Staging API: https://api-stg.pubfi.ai
• Staging MCP: https://mcp-stg.pubfi.ai
• Staging MCP x402: https://mcp-stg.pubfi.ai/x402
• Pricing: https://pubfi.ai/pricing
• Contact: https://pubfi.ai/contact
• Partners: https://pubfi.ai/partners
• Blog: https://pubfi.ai/blog
• Product pages: https://pubfi.ai/products/{product_slug}
• Discovery: https://pubfi.ai/discovery
• Discovery directory Markdown: https://pubfi.ai/discovery.md
• Provider Profile index: https://pubfi.ai/discovery/sources
• Sitemap: https://pubfi.ai/sitemap.xml
• Robots policy: https://pubfi.ai/robots.txt
• IndexNow verification key: https://pubfi.ai/50e4aa84-257b-4ff4-a822-5da3d567384c.txt
• Login: https://pubfi.ai/login
• Privacy policy: https://pubfi.ai/privacy-policy
• Terms of service: https://pubfi.ai/terms-of-service
• Agents guide: https://pubfi.ai/agents.md
• Product LLM index: https://pubfi.ai/llms.txt
• Developer LLM index: https://pubfi.ai/developers/llms.txt
• Product LLM full export: https://pubfi.ai/llms-full.txt
• AI Catalog: https://pubfi.ai/.well-known/ai-catalog.json
• Agent Resource Descriptor: https://pubfi.ai/.well-known/ard.json
• RFC 9727 API Catalog: https://pubfi.ai/.well-known/api-catalog
• Discovery capability-card JSON: https://pubfi.ai/discovery/agent-capabilities.json
• Contact Markdown: https://pubfi.ai/contact.md
• Blog Markdown companions: https://pubfi.ai/blog/{slug}.md
• Environment-matched API reference: https://pubfi.ai/api-reference
• Environment-matched OpenAPI schema: https://pubfi.ai/openapi.json
• Interactive API reference: https://api.pubfi.ai/reference
• OpenAPI schema: https://api.pubfi.ai/openapi.json
• API-host MCP manifest: https://api.pubfi.ai/.well-known/mcp.json
• MCP manifest: https://mcp.pubfi.ai/.well-known/mcp.json
• OpenAI Apps domain ownership proof: https://mcp.pubfi.ai/.well-known/openai-apps-challenge
• MCP OAuth protected resource: https://mcp.pubfi.ai/.well-known/oauth-protected-resource
• MCP OAuth authorization server: https://mcp.pubfi.ai/.well-known/oauth-authorization-server
• MCP x402 endpoint: https://mcp.pubfi.ai/x402
• MCP discovery pointer: https://pubfi.ai/.well-known/mcp.json
• MCP server card: https://pubfi.ai/.well-known/mcp/server-card.json
• Optional MCP registry auth proof route: https://pubfi.ai/.well-known/mcp-registry-auth

Repository Contents

pubfi-docs/
├── AGENTS.md
├── README.md
├── docs.json
├── CONTRIBUTING.md
├── LICENSE.md
├── LICENSE-DOCS.md
├── LICENSE-CODE.md
├── CHANGELOG.md
├── llms.txt
├── llms-full.txt
├── favicon.svg
├── index.md
├── project-overview.md
├── getting-started/
├── concepts/
├── agent-readable/
├── reference/
├── use-cases/
├── faq.md
├── glossary.md
├── maintenance/
│   └── public-docs-maintenance.md
├── assets/
│   └── README.md
└── examples/
    ├── README.md
    └── agents/
        ├── capability-curl/
        ├── pubfi-route-tools-mcp/
        ├── x402-base-mainnet/
        └── x402-base-sepolia/

Runnable public-safe examples live under examples/:

• examples/agents/pubfi-route-tools-mcp/: dependency-free stdio bridge and smoke for the hosted MCP endpoint;
• examples/agents/capability-curl/: no-auth Registry v2 catalog inspection;
• examples/agents/x402-base-sepolia/: no-secret inspection of the current x402 challenge.
• examples/agents/x402-base-mainnet/: Production HTTP and MCP clients pinned to the historical 2026-07-27 Base mainnet route, asset, amount, and payee. Current catalog and challenge checks are required before use.

Shared Favicon

The root favicon.svg is copied from pubfi-mono/apps/web/app/icon.svg at 7a1b8e13943d454db5f76d03a29e1ce8f65ee616. This source keeps the docs icon aligned with the PubFi product site.

Local Development Preview

npx mint@latest dev --no-open

The local preview serves the docs site at http://localhost:3000.

Checks

npm ci
npm run check
npx mint@latest validate

The portable check validates Mintlify navigation targets, Markdown links, docs-site route links, trailing whitespace, secret patterns, unsafe SEO/GEO success phrases, and example syntax. For docs output, navigation, or generated static asset changes, also run the Mint export and static assertions documented in maintenance/public-docs-maintenance.md. These checks run locally before the current GitHub pull request merge. Main-branch release workflows deploy the canonical site.

Authenticated examples require a PubFi API key and must load it from a secret store. Paid x402 clients require a buyer wallet key that must also stay in a secret store. Do not commit credentials, wallet addresses, payment signatures, payment responses, raw account responses, or production readbacks.

Publishing

Deploy this repository with Mintlify export to Vercel and set docs.pubfi.ai as the canonical docs domain. Production builds emit sitemap.xml, robots.txt, and clean canonical metadata for root docs routes. GitHub Pages is a fallback only; do not run a second canonical docs site unless canonical and noindex rules are explicit.

Public Boundary

Safe claims:

• PubFi is building an agent-native crypto data layer.
• Discovery is an open index, demand engine, and source-selection surface for crypto data APIs.
• PubFi exposes generic route/capability tooling for agents and MCP clients. The authenticated MCP root accepts API keys or OAuth access tokens; accountless payment uses the separate /x402 endpoint.
• PubFi Staging uses separate web, API, and MCP roots and a Base Sepolia x402 test boundary.
• Public Discovery and LLM exports are generated from checked-in public-safe curated data.

Unsafe claims:

• every Discovery source is callable through PubFi;
• local SEO/GEO artifacts prove ranking, traffic, or AI citation success;
• GitHub exposure alone proves search success;
• PubFi performs supplier procurement, supplier payment, wallet custody, or live model-ranked routing by default.
• Every gateway route supports x402, or an old challenge or acceptance run proves current Production availability without a current catalog and unsigned challenge.
• A Base Sepolia Staging challenge proves that Production x402 is available.

Appreciation

We would like to extend our heartfelt gratitude to the following projects and contributors:

• Mintlify for the docs framework used by this repository.
• OpenAPI and Scalar for API-reference conventions and tooling patterns.
• Model Context Protocol contributors for the agent-tool interface standard.
• Public crypto data API providers whose documentation makes source discovery and comparison possible.

Additional Acknowledgements

• PubFi contributors and maintainers.
• The broader open-source documentation community for docs-as-code practices.