​
Product Boundary

PubFi is an agent-facing execution and discovery layer for crypto data:
  • Discovery provides public source-selection context.
  • Registry v2 owns executable path, method, request, response, meter, and readiness contracts.
  • The account service owns API keys, fixed product access, environment binding, admission, allocation, and usage facts.
  • The HTTP gateway executes exact current Registry operations.
  • MCP exposes generic Registry catalog list and detail tools plus exact route execution.
  • Registered purchases can create purchase-origin service units after verified settlement.
  • Eligible HTTP and MCP routes can use an accountless x402 payment lane.
Discovery content does not make a route executable. The installed Registry snapshot is the runtime authority.

​
Runtime Surfaces

​
Registry v2 Execution Flow

  1. The Registry control plane produces an immutable generation and manifest.
  2. The API Data Plane installs one valid serving snapshot and fails closed when no valid snapshot is available.
  3. /v1/capabilities, Runtime OpenAPI, MCP discovery, and MCP route tools derive from that same snapshot.
  4. An HTTP or MCP request supplies an exact path and method.
  5. The Data Plane performs the same matcher lookup, query bounds, and body method and byte checks for both entry surfaces.
  6. The gateway selects either the API-key lane or an eligible accountless x402 lane.
  7. The typed executor calls the selected upstream and bounds the response without applying an OpenAPI payload schema.
  8. The caller receives the exact bounded provider response. API-key responses identify the Registry generation. Settled x402 responses include the payment result.
MCP pubfi.route.execute uses API-key or OAuth account admission on the authenticated root. The separate /x402 endpoint rejects Bearer credentials and owns accountless payment metadata. Both endpoints use the same typed Registry and provider executor.

​
Registered Commerce Flow

Registered purchases are separate from route execution:
  1. An authenticated human account member reads current provider-neutral offers.
  2. An Owner or Admin creates a purchase with an advertised offer key, its exact catalog and terms identities, a valid amount, and Idempotency-Key.
  3. The checkout provider completes the external payment flow.
  4. Verified settlement can create a purchase-origin request_count allocation that PubFi shows as Credits.
  5. Later API-key execution can consume that allocation.
A route or UI control does not prove that an offer is currently available. Accountless x402 buys one eligible response and does not create or consume Credits.

​
Repository Layout

The normal PubFi backend release publishes exactly three runtime images: pubfi-api-server, pubfi-registry, and pubfi-registry-token-agent. The five Registry deployments keep separate workload identities, configuration, probes, and failure boundaries while sharing the one pubfi-registry image. The source refresher is one of those long-running hosted roles; it is not an offline operations command.

​
Ownership Rules

  • Rust owns runtime route authority, matching, execution, auth, allocation, purchases, MCP, storage, and operational fail-closed behavior.
  • Next.js owns public presentation, Discovery, dashboard presentation, and public text or manifest exports.
  • Registry v2 route data is provider-neutral. Provider identity is data, not an execution branch or a permanent URL convention.
  • The Runtime OpenAPI includes current ready routes. It does not use checked-in provider schemas.
  • Provider credentials, payment evidence, account data, and commercial records stay outside public docs and examples.
Use Runtime Endpoints for the concrete route families and the Agent Interface Reference for MCP tools.