PubFi executes provider-backed requests through the currently installed Registry v2 generation. There is no permanent provider URL pattern. Use the public catalog or Runtime OpenAPI before every integration or route refresh.

​
1. Inspect Current Authority

Get the first page of the installed catalog:
The paginated response uses pubfi.gateway.registry.capability-page.v5. Each compact capability summary includes:
  • the exact generation, manifest, and compile time;
  • each capability ID, public provider key, matcher, and allowed method;
  • whether PubFi needs a configured upstream credential;
  • one billing state for each allowed method; and
  • current ready or blocked readiness.
Read each opaque next_cursor page to enumerate the complete installed generation. Keep the provider_key and method filters unchanged when you send a cursor. A saved first page is not the complete catalog. Use the Runtime OpenAPI when you need only current ready operations:
Do not infer execution from a Discovery listing, an old example, or a saved route from a different Registry generation. For a free-capable route, the capability summary includes free_rate_limit. Runtime OpenAPI adds x-pubfi-free-variant to the same operation. These fields authorize the :free suffix; do not infer it from a provider name or billing mode. For a quantro_priced route, Runtime OpenAPI copies the matching method price from x-pubfi-billing into x-pubfi-credit-cost, x-pubfi-price-policy-key, x-pubfi-price-version, and x-pubfi-x402. Use these fields only on the selected path and method. They are omitted for free_health and pricing_unavailable operations.

​
Filter Subscan Or DeGov

Use the exact public provider key to limit discovery. For example, select subscan or degov:
If next_cursor is present, request the next page with the same provider_key and limit, plus cursor=<next_cursor>. Continue until next_cursor is absent. Then select one ready operation whose matching method has billing.mode set to quantro_priced, and read its positive billing.credit_cost. A free_health operation uses its exact path without authentication, Credits, or x402. A pricing_unavailable operation is not a paid execution target. Confirm the same path and method in the Runtime OpenAPI, where a priced operation repeats the method terms in the top-level x-pubfi-* price extensions. Use the live filtered catalogs for current operations: PubFi’s DeGov routes use the DeGov Partner Agent API at agent-api.degov.ai. atlas.degov.ai is a UI and reference surface. It is not a second execution contract. Always invoke the PubFi gateway path from the live catalog; do not send an upstream provider credential.

​
2. Select An Exact Operation

Copy the path and HTTP method from one current ready operation. Replace each documented path parameter with a value that satisfies its schema. The resulting concrete path is the gateway path. Do not add provider, network, or endpoint segments that are not present in the current schema. Only GET and POST are supported. Use the operation’s OpenAPI query parameters and body schema to construct the provider request. PubFi forwards a valid RFC 3986 query exactly as supplied, including duplicate or undeclared fields, up to 65,536 encoded bytes. It does not apply the source-declared query-value rules during execution. A non-empty POST body is forwarded byte-for-byte within the route-selected limit and uses the route-selected media type. Empty bodies are omitted, and GET bodies are rejected. Set placeholders from the current schema:

​
3. Execute With A PubFi API Key

Send the supported API-key header:
Example:
The key must match the endpoint environment. The billing account must also have active admission and enough allocation for the method-specific credit_cost. X-PubFi-Api-Key is not accepted; remove it before accountless x402 because its presence still selects the credential lane. For a JSON POST operation, construct the body from the current OpenAPI schema:
OpenAPI guides client construction, but PubFi does not apply that source schema to the body bytes during execution. Do not copy a request body from another operation.

​
4. Execute An Advertised Free Variant

Only use this lane when the current capability has free_rate_limit or the matching Runtime OpenAPI operation has x-pubfi-free-variant. The underlying operation can be an exact GET or POST, can require a server-side provider credential, and can have a request body. Append :free to its final path segment, keep the exact current operation input, and use the same PubFi API key:
For a JSON POST, add the body constructed from the selected current schema, as in the paid API-key example above. PubFi selects the upstream media type from the route contract. The free variant is account-level rate-limited and charges zero Credits. It does not reserve, finalize, replay, or emit Quantro request usage. A retryable limit rejection returns HTTP 429 with gateway.free_rate_limited and Retry-After. A cumulative hard-limit rejection returns gateway.free_limit_reached without Retry-After. The checked-in Subscan policy shares a 2-request-per-second and 20,000-request-per-day allowance across its eligible exact routes for one billing account. Policy presence does not prove current route readiness. Require the current catalog or OpenAPI advertisement before execution, and do not send PAYMENT-SIGNATURE for this variant.

​
5. Use The Accountless x402 Lane When Eligible

An exact gateway route can separately enable accountless x402. The public Base Sepolia example is Staging-only. Inspect the Staging catalog and Runtime OpenAPI, then select an exact ready path and method from that environment:
Do not reuse a Production-selected path or method unless the current Staging contracts advertise the same operation as ready. Set new Staging values, then send the exact request without a PubFi API key or payment signature:
An eligible unpaid request returns 402 Payment Required, a PAYMENT-REQUIRED header, and the same current requirements in the JSON body. Validate that challenge before a wallet signs it. The paid retry uses PAYMENT-SIGNATURE. A settled success returns PAYMENT-RESPONSE. Never send a PubFi API key and PAYMENT-SIGNATURE together. MCP pubfi.route.execute supports the same payment lane through x402/payment and x402/payment-response metadata. The Base Sepolia example uses https://mcp-stg.pubfi.ai/x402, which rejects Bearer credentials. Staging permits Base Sepolia eip155:84532. Production permits Base mainnet eip155:8453 only when the exact route has x402 enabled. The environment policy does not establish current availability. Treat the live catalog as route authority and the live challenge as payment-term authority. See Accountless x402 for the environment safety boundary and exact replay rules. See the Staging guide for all Staging endpoints.

​
Success Response

A successful gateway request returns the provider’s exact bounded response bytes. PubFi does not wrap the body in a stable success envelope. Every success includes:
An API-key lane success also includes:
An x402 lane success instead includes PAYMENT-RESPONSE and Cache-Control: private, no-store. The response shape depends on the provider. Use Runtime OpenAPI to design the client, and handle the provider’s advertised media types and response shapes.

​
Provider Error And Business Responses

A bounded provider HTTP 2xx, 4xx, or 5xx response keeps its status and exact response bytes. PubFi reduces a valid content type to its parameter-free media type. It uses application/octet-stream when the provider content type is missing or malformed. These completed provider responses are not PubFi gateway-error envelopes. Transport failure, redirects, oversized data, and unsupported final status classes remain gateway failures. In the API-key lane, an admitted provider attempt consumes the operation’s selected credit_cost, even when the provider returns an error or the attempt times out. A free-variant provider response charges zero Credits.

​
Registry Failure Classes

PubFi Registry failures use one provider-neutral vocabulary. Provider responses described above can use the same HTTP status numbers without a PubFi error code: The error body uses the standard PubFi error object:
Lane admission can return more specific codes. For example:
  • An advertised free variant can return gateway.free_rate_limited with Retry-After, or gateway.free_limit_reached without it when a cumulative limit is exhausted.
  • API-key admission can return gateway.insufficient_meter_escrow, gateway.billing_account_inactive, gateway.billing_admission_unknown, or gateway.billing_admission_stale.
  • x402 can return x402.conflicting_payment_lanes, x402.invalid_payment, x402.payment_failed, x402.claimed_payment_conflict, x402.provider_failure, x402.provider_timeout, or x402.unavailable.
A 402 response is not always an account-allocation failure. A PAYMENT-REQUIRED header identifies an x402 challenge. A failed paid retry can also return a fresh standard challenge. Validate all of its terms before deciding whether to create a new authorization. MCP preserves the equivalent official PaymentRequired fields in the error result’s structuredContent and adds an error message. Inspect the challenge and error before choosing the next action.

​
Public-Safe Boundary

Examples must not publish:
  • PubFi API keys;
  • PAYMENT-SIGNATURE or PAYMENT-RESPONSE values;
  • wallet secrets or unredacted payment payloads;
  • upstream provider credentials;
  • account, purchase, usage, or billing records; or
  • claims that an old path, current offer, price, uptime result, or route remains available.