Prime-Agent x402 Intelligence

Prime-Agent x402 Intelligence: first slice

Three configured paid Base routes (/chain/status, /token/metadata/{address}, and /token/context/{address}) share a SQLite evidence cache. The context response explicitly marks holder, liquidity, and activity coverage as absent. An offline /token/verdict function returns insufficient_evidence; it is not offered as a paid route until those sources exist. No simulated payment is counted as revenue.

Local core test

Run python3 -m unittest discover -s tests -v in this directory. No third-party libraries are needed for the core or offline audits. After installing requirements.txt and httpx2, run python3 -m unittest discover -s tests/integration -v to verify all three route challenges, an invalid retry, and mock acceptance and settlement paths using a local fake facilitator. The invalid retry reaches /verify and never calls /settle. On mock success, the handler runs between /verify and /settle; on mock settlement failure, paid content is withheld. The fake deliberately does not validate signatures or move funds.

Paid server

Install requirements.txt in a Python 3.11+ environment. Set PRIME_PAY_TO to the operator's real Base address, PRIME_FACILITATOR_URL to a facilitator confirmed to support x402 v2 exact Base, PRIME_BASE_RPC_URL to a Base mainnet RPC endpoint, PRIME_EVIDENCE_DB to a writable SQLite file path, and PRIME_DELIVERY_JOURNAL to a writable JSONL file in a private directory. Start with uvicorn server:app --host 127.0.0.1 --port 8000. Startup fails when required configuration is absent. There is no free access switch.

The x402 middleware is responsible for payment challenge, verification and settlement. The intelligence core checks Base chain ID, pins reads to an EIP-1898 block hash with requireCanonical, and checks the block by number again before returning composed token facts. Providers without EIP-1898 support fail closed. RPC responses over 512,000 bytes are rejected. A later reorganization remains possible: each response identifies its observed block rather than claiming finality. All three unsigned challenges, a rejected retry, mock settlement success and failure, and the absence of the unfinished verdict route have passed in CI on Python 3.11 and 3.12. The middleware price patterns use x402's :address syntax while FastAPI handlers use {address}. A production browser-wallet request has now completed the x402 flow for /chain/status: the server observed a paid retry, returned HTTP 200 protected content, and PayAI subsequently listed the route in its Bazaar catalog. This bootstrap transaction proves the integration path, not organic demand or profitability. Exact transaction-to-delivery reconciliation remains a separate audit requirement.

The outer delivery journal records a transaction reference, configured route price and payee, facilitator-reported payer, and SHA-256 of the response bytes after ASGI send completion when a 200 response carries a successful settlement header. It never stores the payment signature. An unsigned challenge or failed settlement produces no paid journal record. A server-side send event does not establish that the buyer received content; the header, journal, and reported payer are not independent settlement evidence. If a journal write fails, the already sent response remains available and an error is logged, leaving an explicit audit gap. Protect and back up the journal; this is an operational event log, not a tamper-proof ledger.

Receipt evaluation

Run python3 evaluate.py --receipts receipts.jsonl --costs costs.jsonl. Receipt records need status, transaction, network, amount_usd, payer; cost records need amount_usd. Outputs are explicitly named reported_*: this calculation deduplicates seller claims but does not independently verify settlement or costs. It does not count merely verified authorizations.

Run python3 verify_transfers.py --claims claims.jsonl --audit-rpc-url https://YOUR_BASE_RPC --pay-to 0xYOUR_PAYEE to corroborate inbound transfers against a separately configured Base RPC. Each JSONL claim needs status: "settled", network: "eip155:8453", asset set to Circle's Base USDC contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, transaction as a transaction hash, payer as an EVM address, and amount_atomic as a positive decimal integer string (for example "20000" for 0.02 USDC). The checker rejects failed, noncanonical at audit time, or fewer than 12 blocks deep transactions; it requires an exact ERC-20 Transfer to the independently configured payee and rejects duplicate log claims. matched_usdc_nominal represents transferred USDC units, not verified x402 revenue: an inbound transfer alone cannot link a payment to a delivered request or establish independent buyer identity. Block depth is not a guarantee of finality. No real claims or live RPC receipts have been audited here.

Run python3 audit_sales.py --journal "$PRIME_DELIVERY_JOURNAL" --audit-rpc-url "$PRIME_AUDIT_RPC_URL" --pay-to "$PRIME_PAY_TO" to correlate journaled responses with onchain transfers. Configure PRIME_AUDIT_RPC_URL separately from the serving RPC and direct it to Base mainnet. The offered route prices have one source in pricing.py: the joiner derives exact USDC atomic amounts from the price table and checks receipt success, block depth and hash, ERC-20 sender/payee/amount, duplicate request and transaction references, and the response digest format. Its result is named chain_correlated_response_events, not sales or settled revenue. Journal content, facilitator-reported payer, and route attribution remain seller-side evidence; this tool does not attest to client receipt, verify a payment signature, or establish profit. Running it with a live provider and real journal is still outstanding.

Bazaar discoverability

Every paid x402 v2 route declares the official Bazaar discovery extension. The 402 challenge includes a stable service name, endpoint-specific search tags, route-specific descriptions, callable input metadata, and output examples/schemas. Dynamic token routes declare the :address path parameter so facilitators can consolidate concrete token URLs under a single route template.

This makes the service discovery-ready, not automatically indexed. Catalog inclusion is facilitator-controlled and must be observed after a real paid request echoes the Bazaar extension through settlement. For a live deployment, verify all of the following before claiming discoverability:

1. An unsigned public request returns a v2 PAYMENT-REQUIRED header whose decoded payload contains extensions.bazaar, an absolute public resource.url, serviceName: "Prime-Agent x402 Intelligence", and the expected tags.
2. A real buyer echoes the Bazaar extension in its PAYMENT-SIGNATURE payload and settlement succeeds through the configured facilitator.
3. If the facilitator returns EXTENSION-RESPONSES, decode it and confirm bazaar.status is success or processing; treat rejected as a failed discovery registration.
4. Query the facilitator's discovery API, preferably GET /discovery/resources?payTo=<payee>, and confirm the public route appears. Allow for asynchronous indexing. Payment settlement by itself does not prove catalog inclusion.

The integration suite asserts that dynamic-route 402 responses contain Bazaar metadata and that mock paid retries echo the extension back to the facilitator boundary.

References: x402 FastAPI integration, x402 v2 specification, SDK changes.

Block-hash addressing: EIP-1898.

Agent discovery and MCP

The production service exposes a free discovery/control plane around the paid x402 data plane:

• GET /catalog — product list, prices, route templates, capability tags, and purchase URL templates.
• GET /capabilities.json — compatibility alias for machine capability crawlers.
• GET /.well-known/ai-catalog.json — machine-readable catalog alias.
• GET /llms.txt — concise agent-readable usage documentation.
• GET /openapi.json — OpenAPI schema for the HTTP service.
• GET /server.json — MCP Registry-compatible server metadata.
• /mcp/ — MCP v2 Streamable HTTP endpoint.

The MCP server intentionally exposes only list_products and quote_token_product. These tools discover and quote paid products without spending funds and without returning paid intelligence. Buyers still obtain chain status, token metadata, or token context through the x402-protected HTTP routes under their own authorization and budget policy.

The repository also contains prime-agent-x402/server.json so the remote MCP server can be published to the official MCP Registry after the live MCP endpoint is verified. The registry entry is not claimed until publication is observed in the registry.

Enriched token context (0.3.0)

GET /token/context/{address} now composes canonical Base contract metadata with a bounded DEX Screener token-pairs observation. The DEX observation is cached for 60 seconds and reports, at most, 30 Base pairs with:

• aggregate reported liquidity in USD,
• aggregate reported 24-hour volume,
• reported 24-hour buy/sell counts,
• the highest-liquidity observed pair,
• an evidence ID and explicit source note.

DEX Screener values are third-party reported market observations, not Prime-Agent-verified onchain accounting. The response says this explicitly and does not turn those values into a risk verdict. If the upstream source is unavailable or malformed, the paid response remains partial and sets liquidity/activity coverage false rather than inventing data.

Holder coverage remains false. Blockscout documents a token-holder API, but the zero-key Base instance path did not pass the independent cloud reliability probe used for this release. Prime-Agent therefore does not claim holder concentration evidence yet. A future holder source must pass availability, bounded-response, provenance, and failure-mode tests before coverage.holders can become true.

References: DEX Screener API reference, Blockscout token API.