Session-gated free tier to make the PRO API key requirement structural

[akolotov]

Description

Introduce a session identifier that unlock_blockchain_analysis issues and every other tool requires, backed by a small usage budget for callers who do not supply their own PRO API key. Requests carrying a client-supplied PRO API key bypass the budget entirely. The mechanism turns two things that are currently requests into preconditions: obtaining the server's operating rules before the first tool call, and registering for a PRO API key before sustained analysis.

Motivation

Two separate problems converge on the same lever.

The first is that unlock_blockchain_analysis does not reliably run. Its description asserts that calling it is mandatory, but agents treat the assertion as advisory and skip it, which means the blockscout-analysis skill pointer and the operating rules it delivers never reach a substantial share of sessions. Persuasion through naming and description wording has already been pushed as far as it goes; what remains is to make the call a functional precondition rather than an instruction.

The second is that free, unauthenticated access gives users no reason to register for a PRO API key, and no reason at all to move to a paid plan. The existing operator-configurable notice announces the coming requirement but carries no consequence, so it can be ignored indefinitely.

Both problems are solved by the same construct: a token that only the initialization call can issue, that every other call must present, and whose usefulness is deliberately limited.

Current State

• unlock_blockchain_analysis is a stateless call that returns reference data and a skill pointer. Nothing depends on it having happened, so skipping it has no consequence beyond the agent operating without the rules.
• Every tool serves any caller. A client-supplied PRO API key changes which credential authorizes the upstream request, but never whether the request is served.
• The server holds no cross-request state: the HTTP transport is stateless and all caches are in-process and derived, so nothing survives a restart and nothing needs to.
• The only pressure toward registration is an advisory note appended to responses, which agents and users are free to disregard.
• There is no server-side identity for a caller. Address-based identification is unusable in both directions: shared egress addresses from hosted assistant products and corporate proxies would make one user exhaust a quota belonging to thousands, while address rotation in those same environments would reset a quota continuously. Client-declared metadata is too low-entropy to stand on its own. The practical consequence is that any quota must be attached to something the client carries, which makes the mechanism a deterrent shaping default behavior rather than a hard enforcement boundary — a trade-off accepted deliberately in this design.

Proposed Changes

• Make the initialization call the sole issuer of a session identifier, and make a valid identifier a precondition for every other tool — including the chain-discovery tool, so the precondition binds from the very first call an agent makes.
• Meter usage per session identifier with two limits serving different purposes: a short rolling allowance that paces bursts and lets an engaged user finish a conversation, and a small lifetime total that keeps the free tier from becoming an unmetered substitute for a PRO API key. Chain discovery and failed calls are exempt from metering so the budget is spent on data rather than on navigation and typos.
• Exempt requests that carry the caller's own PRO API key from the mechanism entirely, so obtaining a key is the visible and complete remedy.
• Report the remaining budget on every successful response, so the pressure toward registration is continuous and the agent never has cause to suspect its identifier has stopped working.
• Reframe the initialization tool's own description: drop the unenforceable claim that it must be called, which the gate now supersedes, and replace it with the one rule the gate cannot enforce — that it is called once per session and that repeat calls yield nothing.
• Shape every refusal so the agent's best available action is to relay the requirement to the user rather than to re-initialize: state plainly that no in-session remedy exists, that the remedy is the user's to apply, and that it takes effect in a later session.
• Apply identical behavior in MCP and REST modes, with a single set of messages rather than mode-specific variants.
• Keep the mechanism off by default and enable it only where it can function — presence of a signing secret together with an HTTP transport — so self-hosted and stdio deployments are unaffected and retain today's behavior.
• Persist session state across restarts in an embedded store requiring no new service, provisioned so that its loss degrades to invalidated sessions rather than to an unmetered server.

Expected Benefits

• The operating rules and skill pointer reach every gated session, closing a gap that description wording has repeatedly failed to close.
• Registration for a PRO API key acquires a concrete, recurring incentive, and the existing advisory notice gains a consequence to point at.
• Sustained analysis becomes materially easier with a key than without one, which is the intended commercial signal, while casual lookups continue to work unregistered.
• Free-tier consumption of upstream PRO API credits acquires a ceiling instead of growing with traffic.
• Free-tier usage becomes measurable through existing usage analytics, so the limits can be tuned and the policy tightened later without redesigning the mechanism.
• Self-hosted, stdio, and community deployments are untouched, so the change carries no cost for operators who do not want it.