# PubFi Docs

Public documentation for PubFi's agent-native crypto data layer and signed Registry v2 gateway.

## Core Docs

- Docs home: https://docs.pubfi.ai
- Project overview: https://docs.pubfi.ai/project-overview
- Quickstart: https://docs.pubfi.ai/getting-started/quickstart
- Staging guide: https://docs.pubfi.ai/getting-started/staging
- API key and runtime: https://docs.pubfi.ai/getting-started/api-key-runtime
- Registry gateway examples: https://docs.pubfi.ai/reference/provider-gateway-examples
- MCP client setup: https://docs.pubfi.ai/getting-started/mcp-client
- MCP client guides: https://docs.pubfi.ai/getting-started/mcp-clients
- Accountless x402: https://docs.pubfi.ai/getting-started/x402
- Discovery concepts: https://docs.pubfi.ai/concepts/discovery
- Registry contracts: https://docs.pubfi.ai/concepts/capability-contracts
- Provider readiness: https://docs.pubfi.ai/concepts/provider-readiness
- Route planning: https://docs.pubfi.ai/concepts/route-planning
- Payment and execution modes: https://docs.pubfi.ai/concepts/payment-and-execution-modes
- Account, Credits, Auto Top-Up, usage, and billing: https://docs.pubfi.ai/concepts/account-credit-usage
- API reference guide: https://docs.pubfi.ai/reference/api-reference
- Agent interface: https://docs.pubfi.ai/reference/agent-interface
- Agent-readable surfaces: https://docs.pubfi.ai/agent-readable/surfaces

## Runtime References

- Staging product and login: https://stg.pubfi.ai, https://stg.pubfi.ai/login
- Staging API reference, OpenAPI, catalog, pricing inventory, and public status: https://api-stg.pubfi.ai/reference, https://api-stg.pubfi.ai/openapi.json, https://api-stg.pubfi.ai/v1/capabilities, https://api-stg.pubfi.ai/v1/operation-pricing-inventory, https://api-stg.pubfi.ai/v1/status
- Staging MCP root, x402 endpoint, and manifest: https://mcp-stg.pubfi.ai, https://mcp-stg.pubfi.ai/x402, https://mcp-stg.pubfi.ai/.well-known/mcp.json
- Interactive API reference: https://api.pubfi.ai/reference
- Runtime OpenAPI: https://api.pubfi.ai/openapi.json
- Current Registry v2 catalog: https://api.pubfi.ai/v1/capabilities
- Operation-pricing inventory: https://api.pubfi.ai/v1/operation-pricing-inventory
- Public status API: https://api.pubfi.ai/v1/status
- API-key auth context: https://api.pubfi.ai/v1/auth/context
- API-host Glama metadata: https://api.pubfi.ai/.well-known/glama.json
- API-host MCP manifest: https://api.pubfi.ai/.well-known/mcp.json
- MCP manifest: https://mcp.pubfi.ai/.well-known/mcp.json
- MCP OAuth protected resource: https://mcp.pubfi.ai/.well-known/oauth-protected-resource
- 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

## Product Surfaces

- Product site: https://pubfi.ai
- Pricing: https://pubfi.ai/pricing
- Status: https://pubfi.ai/status
- Partners: https://pubfi.ai/partners
- Blog: https://pubfi.ai/blog
- Product pages: https://pubfi.ai/products/subscan-api, https://pubfi.ai/products/degov-api, https://pubfi.ai/products/insight-api, https://pubfi.ai/products/defi-api
- 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
- Product LLM full export: https://pubfi.ai/llms-full.txt
- Discovery capability-card JSON: https://pubfi.ai/discovery/agent-capabilities.json
- Agent interface guide: https://docs.pubfi.ai/reference/agent-interface
- Agent-readable surfaces: https://docs.pubfi.ai/agent-readable/surfaces

## Boundary

Discovery inclusion does not imply Registry readiness. The current Registry catalog and Runtime
OpenAPI define executable paths and methods. API-key execution, registered purchases and Credits,
and accountless x402 are separate modes. An optional catalog `free_rate_limit` and OpenAPI
`x-pubfi-free-variant` advertise an API-key-authenticated `:free` route variant that charges zero
Credits. The authenticated MCP root accepts a PubFi API key or OAuth access token for
`pubfi.route.execute`, including that advertised suffix. It rejects payment metadata and does not
fall back. The separate `/x402` endpoint rejects Bearer credentials and supports the official
x402 metadata flow, so an agent can pay directly through MCP.
OpenAPI query and body fields are source-declared request-construction metadata. HTTP and MCP
execution preserve any RFC 3986-valid query of at most 65,536 encoded bytes, including duplicate
or undeclared fields. A non-empty POST body is forwarded byte-for-byte within the route-selected
limit and media type; empty bodies are omitted and GET bodies are rejected.
Each API runtime assigns the environment when it creates a key and accepts only matching keys.
Clients cannot select the environment or request per-key scopes; only a human Owner or Admin can
manage keys. `X-PubFi-Api-Key` is not accepted, but it remains a credential carrier and must be
absent from accountless x402 requests.
`GET /v1/auth/context` lets an environment-matched PubFi API key read its existing
`principal_id`, bound `billing_account_id`, and nullable `actor_subject_id`. The response is
private and no-store, creates no account or billing state, and does not accept OAuth fallback.
An API key can read its own account's usage, detailed billing, authoritative available Credit
balance, and server-authoritative free-quota counters. The focused account routes are private and
no-store. They do not expose payment or internal limiter state.
Accountless x402 creates no PubFi account, API key, Credits, or invoice. The environment-specific
wallet's USDC is the payment balance; keep separate wallets and private keys for Staging and
Production. A Signed Receipt is payment and execution evidence, not a balance, top-up, or deposit
record.
Registered-account Auto Top-Up is off by default. It uses the account's shared payment method and
buys a fixed whole-Credit quantity only under an explicitly enabled threshold and finite UTC
monthly-limit policy. Human members can read its state; only an Owner or Admin can mutate it. The
dashboard name is Auto Top-Up, while the stable API route name is `credit-auto-reload`.
The current checked-in pricing target sets one Credit and 0.001 USDC for every priced Subscan and
DeGov operation and uses a $1/1,000-Credit registered-purchase base. Confirm installed prices and
offer availability from the current catalog, Runtime OpenAPI, and offer response. Purchase
creation requires the current offer key, exact catalog release hash, amount, accepted terms
version and hash, and `Idempotency-Key`.
The public no-store `quantro.operation-pricing-inventory.v2` inventory projects every approved
typed plan in the installed snapshot as `free_health` or `merchant_priced`. It contains no selected
price, is not execution authority, and returns `503` instead of a partial inventory when the
complete projection cannot be formed.
Every bounded provider HTTP `2xx`, `4xx`, or `5xx` response keeps its status and exact body. PubFi
uses a safe parameter-free media type. These are provider responses, not PubFi gateway-error
envelopes. MCP represents valid JSON as a JSON value, valid text as a string, other bytes as base64
data, and an empty body as `null`.
The public no-store status APIs use `operational`, `degraded`, `major_outage`, or `unknown`.
Missing, stale, or incoherent evidence stays `unknown`; status does not replace the Registry
catalog as route authority.

Base Sepolia `eip155:84532` is the Staging x402 boundary. Staging HTTP and MCP acceptance completed
on 2026-07-27 with Signed Offer and Signed Receipt verification and exact replay; see
https://github.com/helixbox/pubfi-mono/actions/runs/30258511212 (source-repository access required).
The historical Production HTTP and MCP acceptance used Base mainnet `eip155:8453`, canonical Base
USDC, 1000 atomic units or 0.001 USDC per request, and the published Production payee. Those values
and that route are not current authority. Production commands spend real USDC when the current
catalog and challenge permit them. Production acceptance completed on 2026-07-27; see
https://github.com/helixbox/pubfi-mono/actions/runs/30259030111 (source-repository access required).
HTTP and MCP share the same x402 `exact` settlement and replay path. Exact replay reuses the first
settlement and receipt without a second charge. Quantro is the common accounting-fact authority,
but one request cannot debit both the registered and x402 lanes. Public docs and reachability
checks do not prove ranking, traffic, or AI citation success.