# PubFi Docs Full Context PubFi is building an agent-native crypto data layer. It helps software teams and AI agents discover crypto data sources, inspect the installed signed Registry generation, select exact routes, inspect schemas, and execute eligible operations without binding every workflow directly to a different upstream API. ## Read First - https://docs.pubfi.ai - https://docs.pubfi.ai/project-overview - https://docs.pubfi.ai/getting-started/quickstart - https://docs.pubfi.ai/getting-started/staging - https://docs.pubfi.ai/getting-started/api-key-runtime - https://docs.pubfi.ai/reference/provider-gateway-examples - https://docs.pubfi.ai/getting-started/mcp-client - https://docs.pubfi.ai/getting-started/chatgpt-codex-plugin - https://docs.pubfi.ai/getting-started/mcp-clients - https://docs.pubfi.ai/getting-started/x402 - https://docs.pubfi.ai/concepts/discovery - https://docs.pubfi.ai/concepts/payment-and-execution-modes - https://docs.pubfi.ai/reference/api-reference ## Canonical Docs Pages - https://docs.pubfi.ai - https://docs.pubfi.ai/project-overview - https://docs.pubfi.ai/getting-started/quickstart - https://docs.pubfi.ai/getting-started/staging - https://docs.pubfi.ai/getting-started/api-key-runtime - https://docs.pubfi.ai/reference/provider-gateway-examples - https://docs.pubfi.ai/getting-started/mcp-client - https://docs.pubfi.ai/getting-started/chatgpt-codex-plugin - https://docs.pubfi.ai/getting-started/mcp-clients - https://docs.pubfi.ai/getting-started/x402 - https://docs.pubfi.ai/concepts/discovery - https://docs.pubfi.ai/concepts/capability-contracts - https://docs.pubfi.ai/concepts/provider-readiness - https://docs.pubfi.ai/concepts/route-planning - https://docs.pubfi.ai/concepts/payment-and-execution-modes - https://docs.pubfi.ai/concepts/account-credit-usage - https://docs.pubfi.ai/concepts/readiness-and-claim-safety - https://docs.pubfi.ai/use-cases/crypto-api-discovery - https://docs.pubfi.ai/use-cases/source-evaluation - https://docs.pubfi.ai/use-cases/provider-integration-review - https://docs.pubfi.ai/use-cases/answer-engine-discovery - https://docs.pubfi.ai/use-cases/agent-wallet-balance - https://docs.pubfi.ai/reference/api-reference - https://docs.pubfi.ai/reference/runtime-endpoints - https://docs.pubfi.ai/reference/agent-interface - https://docs.pubfi.ai/reference/public-surfaces - https://docs.pubfi.ai/agent-readable/surfaces - https://docs.pubfi.ai/reference/architecture-map - https://docs.pubfi.ai/reference/security-and-public-data - https://docs.pubfi.ai/faq - https://docs.pubfi.ai/glossary ## ChatGPT And Codex Plugin The PubFi Plugin uses the existing universal Account/OAuth MCP root at https://mcp.pubfi.ai/. Catalog reads are public. The workflow calls pubfi.capabilities.list, inspects the exact selected capability with pubfi.capabilities.get, and calls pubfi.route.execute only with the current path and method returned by the catalog. It discloses the published credit_cost before paid calls and does not initiate commerce, wallet, transfer, trade, investment, or accountless payment actions. See https://docs.pubfi.ai/getting-started/chatgpt-codex-plugin. ## Concepts - Discovery is the editorial public source-selection layer. Discovery inclusion does not establish execution. - `GET https://api.pubfi.ai/v1/capabilities` returns the current paginated `pubfi.gateway.registry.capability-page.v5` catalog. Follow each opaque `next_cursor` for the complete installed generation. Match the selected method to `operations[].billing`; billing is `free_health`, `pricing_unavailable`, or `quantro_priced`. - Runtime OpenAPI is generated from the installed Registry snapshot. It includes the current ready gateway operations. Each operation includes `x-pubfi-billing`. A `quantro_priced` operation also repeats its method price in `x-pubfi-credit-cost`, `x-pubfi-price-policy-key`, `x-pubfi-price-version`, and `x-pubfi-x402`; non-priced operations omit these four fields. Separate static provider schemas are not execution authority. OpenAPI query parameters are source-declared request-construction metadata. HTTP execution preserves 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. - Direct-HTTP response delivery is automatic on the normal authenticated paid or `:free` route. The catalog and Runtime OpenAPI publish no stream-policy field or caller-selected `:stream` suffix. The platform ceiling is 128 MiB, with 10-second idle and 120-second body deadlines and heavy-transfer concurrency limits of 1 per account, 4 per provider, and 8 globally. A route can impose a stricter budget. - The current checked-in pricing target sets `credit_cost: 1` and x402 `atomic_amount: "1000"` (0.001 USDC) for every priced Subscan and DeGov operation. Confirm the installed values in the selected environment before execution. - `GET https://api.pubfi.ai/v1/operation-pricing-inventory` returns the complete public-safe `quantro.operation-pricing-inventory.v2` producer projection for the installed snapshot. It contains canonical route facts and `free_health` or `merchant_priced` classification, but no selected price or execution authority. It uses `Cache-Control: no-store` and returns `503` instead of a partial inventory when the complete approved projection cannot be formed. - Registry execution matches an exact path and method. A successful HTTP operation returns the provider's exact bounded body plus PubFi request and Registry-generation headers. - Every bounded provider HTTP `2xx`, `4xx`, or `5xx` response keeps its status and exact body. PubFi reduces a valid content type to its parameter-free media type and uses `application/octet-stream` when it is missing or malformed. These are provider responses, not PubFi gateway-error envelopes. Transport failure, redirects, oversized data, and unsupported final status classes remain gateway failures. Buffered overflow returns HTTP `502` with `gateway.upstream_response_too_large` and no provider response body. - MCP keeps provider response bodies at or below 1 MiB inline. A larger result returns exactly one HTTPS `resource_link` plus compact fallback metadata with `status`, `content_type`, `bytes`, `sha256`, `expiry`, and `uri`, but no inline body. The returned capability URI is private and no-store and preserves the original status, media type, and exact bytes until expiry. PubFi does not add generic artifact resources, templates, or resource-read execution. - An optional capability-level `free_rate_limit` and Runtime OpenAPI `x-pubfi-free-variant` advertise an authenticated `:free` final-segment variant for an eligible exact `GET` or `POST`. It keeps the exact operation input, uses the same PubFi API key and account identity, charges zero Credits, and rejects anonymous or x402 admission. The policy can include an independent quota, cumulative limit, and shared bucket scope. Retryable rejection returns `429` with `gateway.free_rate_limited` and `Retry-After`; a cumulative limit uses `gateway.free_limit_reached` without `Retry-After`. Successful MCP execution reports `execution_status: registry_free_route_executed` and `credits_charged: 0`. The checked-in Subscan policy is provider-scoped across eligible default and bounded `{network}` routes, including XCM, multi-chain, Pro, and `net_assets` operations. Require the current catalog or OpenAPI advertisement before execution. - Registry readiness is `ready` or `blocked`. Editorial terms such as `requestable` and `contract_ready` do not make an operation executable. - Registered API-key execution consumes the account's applicable meter allocation. - 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; a key can read usage, detailed billing, authoritative available Credit balance, and server-authoritative free-quota counters only for its own account. The focused reads are private and no-store. Credit balance is a canonical whole-number string; free-quota counters are JavaScript-safe integers and omit internal bucket keys and permit settings. - `GET /v1/auth/context` lets a valid environment-matched PubFi API key read its existing provider-neutral execution context. The private, no-store response contains exactly `principal_id`, `billing_account_id`, and nullable `actor_subject_id`; it creates no account or billing state and does not accept OAuth fallback. - `X-PubFi-Api-Key` is not accepted, but it remains a credential carrier. Remove it before an accountless x402 request or the request stays in the credential lane. - The free starter allocation is 1,000 requests and is not Credits. PubFi uses Credits only for eligible purchase-origin `request_count` units. - Registered purchase routes expose the currently available offers. The route existing does not prove that an offer is open for sale. - Purchase creation requires the current offer key, exact catalog release hash, amount, accepted terms version and hash, and `Idempotency-Key`. The checked-in pricing target uses a $1/1,000-Credit base, but the current offer response remains availability authority. - Registered-account Auto Top-Up is off by default. It can buy a fixed whole-Credit quantity when the available Credit balance falls below an explicitly enabled threshold, subject to a current eligible offer, active shared payment method, accepted terms, and finite UTC monthly limit. 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`. - Accountless x402 buys one eligible HTTP or MCP response. It creates no PubFi account, API key, Credits balance, or invoice. The caller's USDC in the environment-specific wallet is the payment balance; PubFi does not mirror it as an account balance. - Staging x402 permits Base Sepolia `eip155:84532` only and uses the exact `https://api-stg.pubfi.ai` and `https://mcp-stg.pubfi.ai/x402` endpoints. Production x402 permits Base mainnet `eip155:8453` only when x402 is enabled for the exact route. These rules do not prove current route or offer availability. Use separate dedicated wallets and private keys for the two environments. - Enabled x402 routes use V2 `exact`, EIP-3009, the standard HTTP headers, official MCP payment metadata, and official Ed25519 Signed Offers & Receipts. The live catalog is route authority. The live challenge is the authority for route-specific payment terms. It contains the Signed Offer. A settled HTTP response carries `PAYMENT-RESPONSE`. A settled MCP result carries the decoded response and Signed Receipt at `result._meta["x402/payment-response"]`. - A Signed Receipt is verifiable payment and execution evidence. It is not an account balance, Credits, top-up, or deposit record. Exact replay reuses the original response, settlement, and receipt without a second charge. - PubFi uses one active private Ed25519 signer. Its `did:web` document can retain up to eight public verification keys so supported historical receipts remain verifiable after rotation. - A public Staging-only pinned-client example for bounded Base Sepolia HTTP and MCP payment, signed offer and receipt verification, and exact replay is available at https://github.com/helixbox/pubfi-docs/tree/main/examples/agents/x402-base-sepolia. - The 2026-07-27 Staging acceptance run completed both official-client lanes with verified Signed Offers, Signed Receipts, and exact replay: https://github.com/helixbox/pubfi-mono/actions/runs/30258511212. The workflow link requires source-repository access. - A separate historical Production archive records HTTP and MCP for the 2026-07-27 acceptance route, `https://api.pubfi.ai/v1/gateway/quantro/health`, Base mainnet `eip155:8453`, canonical Base USDC, 1000 atomic units or 0.001 USDC per request, and the published payee. It verifies signed offers, signed receipts, and exact replay. Schema v5 classifies exact health operations as `free_health`, so the archived paid commands must not be run. The pinned values are not current availability or payment authority: https://github.com/helixbox/pubfi-docs/tree/main/examples/agents/x402-base-mainnet. - The 2026-07-27 Production acceptance run completed both HTTP and MCP payments with verified signed receipts and exact replay: https://github.com/helixbox/pubfi-mono/actions/runs/30259030111. The workflow link requires source-repository access. Bounded read-only acceptance confirmed one `settled` settlement and one signed receipt for each lane. Exact replay did not create a second charge. Public Base transactions: `0xb011351c24f40b597778ec1dd79807d2a4a01950ae219db3299f0c51f2cc594f` and `0x25819c481c83ddc7dd028a8c3c6832ee7ba77a00b3b7300106bb6db5e73f9934`. - The examples require a buyer key injected by a wallet or secret manager. They never accept the key in an MCP tool argument or prompt. The Production commands spend real USDC. ## Runtime And Agent Surfaces - Staging guide: https://docs.pubfi.ai/getting-started/staging - Staging interactive API reference: https://api-stg.pubfi.ai/reference - Staging Runtime OpenAPI: https://api-stg.pubfi.ai/openapi.json - Staging Registry v2 catalog: https://api-stg.pubfi.ai/v1/capabilities - Staging operation-pricing inventory: https://api-stg.pubfi.ai/v1/operation-pricing-inventory - Staging MCP endpoint: https://mcp-stg.pubfi.ai - Staging MCP x402 endpoint: https://mcp-stg.pubfi.ai/x402 - Staging MCP manifest: 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 endpoint: https://mcp.pubfi.ai - MCP x402 endpoint: https://mcp.pubfi.ai/x402 - 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 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 - 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 - MCP client guides: https://docs.pubfi.ai/getting-started/mcp-clients - Agent-readable surfaces: https://docs.pubfi.ai/agent-readable/surfaces - Product site: https://pubfi.ai - About: https://pubfi.ai/about - Developers: https://pubfi.ai/developers - Products: https://pubfi.ai/products - 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 - 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 - Homepage Markdown: https://pubfi.ai/index.md - About Markdown: https://pubfi.ai/about.md - Developers Markdown: https://pubfi.ai/developers.md - Products Markdown: https://pubfi.ai/products.md - Pricing and access Markdown: https://pubfi.ai/pricing.md - Authentication Markdown: https://pubfi.ai/auth.md - Discovery: https://pubfi.ai/discovery - Discovery directory Markdown: https://pubfi.ai/discovery.md - Provider Profile index: https://pubfi.ai/discovery/sources The public no-store status contracts use `pubfi.status.v1` and `pubfi.status.gateway.v2` with `operational`, `degraded`, `major_outage`, or `unknown`. Missing, stale, or incoherent evidence is `unknown`. Gateway summaries count source operations separately from Registry route variants. Operation status binds source, route, and monitor identities; signals identify the responsible owner layer. Schema v2 separates offered and unoffered operations and reports monitoring coverage, nullable health, and evidence status. Deliberately inapplicable monitoring is not unknown health. Incidents use `suspect`, `open`, `recovering`, or `resolved` state. Status is operational evidence, not Registry route authority or proof that a purchase or x402 offer is available. Gateway summaries expose `operation_pricing_status`; a known pricing outage blocks paid execution without replacing independent provider or PubFi proxy evidence, and missing pricing evidence remains `unknown`. ## MCP Registry v2 Tools - `pubfi.capabilities.list`: optional `limit`, opaque `cursor`, exact `provider_key`, and exact `method`. Follow every `next_cursor` for one installed generation. - `pubfi.capabilities.get`: required exact `capability_id` returned by `pubfi.capabilities.list`. - `pubfi.route.execute`: required `raw_path` and `method`; optional exact `query`, exact `body`, `idempotency_key`, and `request_id`. - `pubfi.substrate.runtime_upgrade.verify` is available only on the authenticated root. It requires `network`, `expected_authorized_code_hash`, and exactly one of `extrinsic_index` or `extrinsic_hash`; `idempotency_key` and `request_id` are optional. The expected hash is the Blake2b-256 hash of the FRAME System `AuthorizedUpgrade` code payload, not the active `:code` hash at the apply block. The tool returns a compact proof and charges one Credit; identical replay does not call the provider or charge again. - The optional execution `query` is preserved byte-for-byte when it is an RFC 3986-valid query component of at most 65,536 encoded bytes. PubFi allows duplicate and undeclared query fields and does not enforce source-declared query-value relationships. 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. - MCP exposes valid provider JSON as a JSON value, valid `text/*` bytes as a string, other or invalid bytes as base64 data, and an empty provider body as `null`. - The hosted MCP endpoints support current `2026-07-28` `server/discover` requests and legacy `2025-11-25` initialize-era clients without protocol sessions. Modern requests carry complete per-request metadata and mirrored MCP HTTP routing headers. The local stdio bridge is modern-only. - `tools/list` publishes the current generation, manifest, and endpoint-specific tool metadata. The authenticated root declares `noauth` for capability reads and `oauth2` with no scopes for both execution tools. Route execution includes free-health, account-free, and account-paid outcomes. The runtime-upgrade tool returns only its compact proof. `/x402` declares `noauth` for its three tools and exposes only free-health, x402 settlement, payment-required, and x402 error outcomes. - `pubfi.capabilities.list` and `pubfi.capabilities.get` are public Registry reads. The client selects a capability; PubFi does not infer intent or rank candidates. - The authenticated MCP root accepts a PubFi API key or OAuth access token for `pubfi.route.execute` and `pubfi.substrate.runtime_upgrade.verify`. It rejects payment metadata, and invalid credentials do not fall back. A missing or invalid OAuth execution credential returns HTTP `401` with protected-resource discovery and `_meta["mcp/www_authenticate"]`; an invalid `pf_sk_v1_` API key uses the separate API-key `401` response. The explicit `/x402` endpoint rejects Bearer credentials. An unsigned eligible call there returns `PaymentRequired`; the paid retry supplies `x402/payment`; the settled result supplies `x402/payment-response`. A wallet-capable agent can complete this payment directly through MCP without a separate paid HTTP request. - Unrelated bounded MCP `_meta` entries can coexist with the flow. Only `x402/payment` carries payment. Paid replay compares structured content and payment-response metadata, not raw JSON-RPC bytes. - HTTP and MCP share the same Registry route, x402 `exact` payment, Quantro settlement, receipt, and exact replay path. - A failed paid retry can return a fresh standard payment requirement. HTTP preserves `PAYMENT-REQUIRED`; MCP preserves the official fields in `structuredContent` and adds an `error` message. Validate the replacement requirement before signing again. - Mainstream clients connect to the hosted endpoint selected for their execution mode. The authenticated root has four tools; `/x402` retains the three general Registry tools. Client-specific setup for Codex, Claude, GitHub Copilot, VS Code, Cursor, Devin, Windsurf, Gemini CLI, Kiro, Continue, Amazon Q Developer, Cline, Roo Code, Zed, JetBrains, Raycast, LM Studio, OpenCode, Warp, LibreChat, goose, and Cherry Studio is indexed at https://docs.pubfi.ai/getting-started/mcp-clients. - Subscan and DeGov are exact `provider_key` filters and Registry data, not provider-specific MCP tool namespaces. An agent lists, gets, and then executes the exact selected current route. ## Public-Safe Claims - PubFi has public Discovery pages and agent-readable exports for source selection and answer-engine retrieval. - PubFi has three general Registry v2 MCP tools for complete catalog listing, exact capability detail, and route execution, plus one authenticated-root Substrate runtime-upgrade verifier. - PubFi exposes a dynamic Registry catalog and Runtime OpenAPI for current executable operations. - PubFi supports registered API-key and MCP OAuth account execution plus separate accountless x402 execution over HTTP and the explicit MCP `/x402` endpoint. - Quantro owns provider-neutral purchase, settlement, receipt, and resulting allocation facts. One request selects either the authenticated account and Credits lane or the accountless x402 lane; it cannot debit both. ## Non-Claims - Discovery inclusion is not gateway availability. - A route plan is not execution authority by itself. - A route or purchase API existing is not proof of a current ready route or available offer. - Accountless x402 support and environment permission do not prove that every route accepts x402 or that a Production offer is currently available. - PubFi does not perform automatic supplier procurement, supplier payment, or wallet custody. - SEO/GEO readbacks and local automation outputs are diagnostics, not ranking, traffic, or AI citation proof. - Public docs do not prove supplier settlement or production model-ranked routing.