This page explains how PubFi API-key auth, billing-account admission, request allowance, usage facts, and runtime execution fit together from a public-docs perspective.

​
Runtime Surfaces

Staging uses the separate roots api-stg.pubfi.ai, mcp-stg.pubfi.ai, and stg.pubfi.ai. Create the key through the Staging dashboard. The server assigns the Staging environment; the client does not select it. Load the key as STG_PUBFI_API_KEY in the public examples. See the Staging guide.

​
API Key Boundary

PubFi API keys are caller credentials for Registry gateway and MCP execution. They can also read usage, billing, authoritative Credit-balance, and free-quota data for their own billing account. PubFi uses one fixed product-access model; clients cannot request or inspect per-key scopes. Listing billing accounts, managing API keys, and all purchase operations require an authenticated human dashboard session. Key management requires Owner or Admin membership. Create keys from the PubFi dashboard under Manage application keys. Copy the key when it is shown, because the full secret is displayed only once. The runtime assigns the key environment. The dashboard does not ask you to select one, and the create API accepts only a name:
Create a separate key from each environment’s dashboard. A Staging runtime creates and accepts Staging keys; a Production runtime creates and accepts Production keys. Supported public auth shape:
X-PubFi-Api-Key is not accepted. Its presence still selects the credential lane, so remove it before an accountless x402 request.

​
Find The Key’s Billing Account

Use the API key with GET /v1/auth/context to get its provider-neutral execution context:
Use billing_account_id in the same-account usage, billing, Credit-balance, and free-quota paths. The route accepts only a valid PubFi API key for the selected environment. It does not accept an OAuth token as a fallback, and it rejects query parameters. The response is private and uses Cache-Control: private, no-store.

​
Billing Account And Usage Model

PubFi groups API keys and product usage under billing accounts. Public docs should describe the model at a high level:
  • API keys authenticate the caller and can read their existing execution context.
  • Every key uses the same fixed product-access model.
  • A key can execute through the gateway or MCP and read its own billing account’s usage, authoritative billing data, available Credit balance, and free-quota counters.
  • Only an authenticated human Owner or Admin can create, list, rename, or revoke keys.
  • A fresh active admission snapshot and sufficient allocation for the operation’s current positive credit_cost are required before priced provider execution.
  • The current checked-in pricing target sets credit_cost: 1 for each priced Subscan and DeGov operation. The same target sets x402 atomic_amount: "1000", or 0.001 USDC. Confirm the installed values in the current catalog and Runtime OpenAPI before execution.
  • An advertised :free variant keeps the same API key and billing-account binding, but uses an account-level rate limiter and charges zero Credits.
  • The free starter allocation provides 1,000 requests and is not Credits.
  • PubFi displays eligible purchase-origin request_count units as Credits. Credits are service units, not money or a PubFi-owned financial ledger.
  • Usage facts record immutable raw-unit observations and execution outcomes.
  • The billing-account /billing route is the detailed authoritative billing read. The focused /credit-balance route returns the authoritative available whole-Credit balance, while /free-quotas returns non-financial server-authoritative limiter state. PubFi usage rows are not billing truth and do not supply either focused read.

​
Registered Purchases

The Runtime OpenAPI includes provider-neutral purchase-offer, create, list, and status routes. Purchase creation requires an authenticated human Owner or Admin, Idempotency-Key, and the strict body:
PubFi API keys cannot call purchase routes. The checked-in pricing target uses a base offer of 1for1,000Credits.Purchaseamountsmustbefrom1 for 1,000 Credits. Purchase amounts must be from 1 through 1,000in1,000 in 0.10 increments and must produce a whole-Credit quantity. The API surface does not prove that a production offer is currently available. A client must use the current offer response and proceed only when an offer is advertised as available.

​
Execution Preflight

A route can execute only when these gates pass:
  • valid PubFi API key for the selected environment;
  • fresh active billing admission and sufficient raw-unit allocation;
  • a matching path and method in the installed Registry generation;
  • current provider readiness;
  • server-side upstream credential configuration;
  • source freshness evidence;
  • query syntax and byte bounds, plus request-body method and byte bounds.
Runtime OpenAPI query parameters and body schemas are source-declared guidance for constructing the provider request. The gateway preserves and forwards any RFC 3986-valid query exactly, including duplicate or undeclared fields, up to 65,536 encoded bytes. It does not enforce declared query semantics at execution time. 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.

​
Free Route Variant

The current capability catalog can advertise free_rate_limit for an eligible exact GET or POST route. Runtime OpenAPI represents the same contract as x-pubfi-free-variant. Only then, append :free to the final path segment and send the normal Bearer API key. Keep the exact query intended for the current provider operation, and keep the body required by the current operation schema. A server-side provider credential does not make an advertised free variant ineligible. The effective policy contains a fixed request window, a concurrency limit, a permit TTL, and can also advertise an independent quota window, a cumulative limit, or shared bucket scope. A free request skips Credit admission, reservation, usage emission, and replay. A retryable window or concurrency rejection returns 429, gateway.free_rate_limited, and Retry-After. A cumulative limit returns 429 with gateway.free_limit_reached and no Retry-After. This lane is not anonymous and is not x402. It is also distinct from an exact free_health operation, which uses its advertised path without the suffix or authentication.

​
Security Boundary

Keep real keys, account ids, usage rows, billing-provider payloads, customer data, and production financial records out of prompts, source code, logs, and public artifacts. This API-key lane is separate from accountless x402. A request with PAYMENT-SIGNATURE must not also contain Authorization or X-PubFi-Api-Key. The legacy header is not valid authentication, but it is still a credential carrier and conflicts with payment. See Payment And Execution Modes.

​
Next Steps