smartflow-verify-mcp

MCP server for SmartFlow Observatory, an independent x402 observatory on Base that runs its own ledger of USDC micro-transfers. It gives any MCP-capable agent (Claude Code, Claude Desktop, Cursor, and others) two capabilities:

1. Read the integrity-sealed decomposition of x402 network growth: how much of the headline volume is wash or self-dealing activity, how much is ERC-4337 bundler plumbing, and how large the organic core really is. Free.
2. Order a $199 signed, human-reviewed audit of any x402 endpoint or receiving wallet, paid over the x402 rail itself. No human needed on the buying side.

The server is a pure HTTP client of the public observatory API. It holds no keys, stores nothing locally, and never moves funds. Payment, if you choose to make one, happens entirely outside this server through your own wallet or x402 client.

Human-facing verification portal: https://verify.smartflowproai.com

Installation

Requires Node.js 18 or newer.

Claude Code

claude mcp add smartflow-verify -- npx -y smartflow-verify-mcp

Claude Desktop

Add to claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "smartflow-verify": {
      "command": "npx",
      "args": ["-y", "smartflow-verify-mcp"]
    }
  }
}

Restart Claude Desktop and the three tools appear under the smartflow-verify server.

From a local checkout

npm install
claude mcp add smartflow-verify -- node /path/to/mcp/src/server.js

Tools

get_network_decomposition (free)

Input: none.

Output: the full sealed decomposition document plus fields added by this client:

• data: the dataset (30d / 7d / previous-7d windows; universe, bundler, facilitator, wash, and clean_core categories with tx counts, USDC volume, and unique payers; category overlaps; concentration checks; explicit limitations).
• seal and seal_verified: the server publishes a SHA-256 seal over the canonical JSON of data. This client recomputes it locally and reports whether it matches, so the numbers are tamper-evident end to end. The recipe is included in the response.
• data_age_hours: how stale the snapshot is. The dataset refreshes roughly daily.

Use this before trusting any headline x402 volume figure. Note the clean_core field is a dataset category name meaning: facilitator-settled transfers with no flagged conditions after the full 48h detection window. Figures reflect the observatory's ingest time, so the most recent hour of activity may be under-represented.

order_endpoint_audit (creates a $199 payable order; the call itself is free)

Input:

• target (string): an x402 endpoint URL (https://...) or a receiving wallet address (0x...).
• email (string): where the signed audit report is delivered.

Output: an order id (aud_ + 16 hex chars), plain-language payment instructions, and the raw x402 payment challenge (see payment flow below).

What you are buying: a signed, human-reviewed audit of the target covering wash-share, payer concentration, demand dispersion, and attribution, delivered by email within 24h of payment.

Calling this tool moves no funds. It only creates an order and returns payment instructions. Unpaid orders are harmless and expire on their own within 24h.

get_audit_order_status (free)

Input:

• order_id (string): the id returned by order_endpoint_audit.

Output: order state. pending_payment means the exact-amount payment has not been detected yet; paid: true confirms the payment was matched; a delivered state means the signed report was emailed.

Payment detection reads Base USDC transfer logs and can lag a few minutes behind the chain. If you just paid, wait 2-5 minutes and poll again before assuming a problem.

Free vs paid

| Tool | Cost | |---|---| | get_network_decomposition | free | | order_endpoint_audit | free to call; creates a $199 payable order | | get_audit_order_status | free |

Nothing in this package can spend money by itself. A purchase happens only if you (or your operator) send the quoted USDC amount from your own wallet.

How the x402 payment flow works

1. order_endpoint_audit POSTs to the observatory API. The API answers HTTP 402 Payment Required with an x402 v2 challenge envelope. That 402 is the success path for order creation, not an error.
2. The challenge quotes a per-order unique amount: $199 plus a unique micro-USDC fraction, for example 199.002732 USDC. The fraction is how the observatory matches your on-chain payment to your order. Pay the exact amount; do not round it.
3. Pay in either way:
   • x402 client: use the exact scheme entry from the accepts array (network eip155:8453, USDC asset contract, payTo address are all in the challenge).
   • Plain transfer: send the exact USDC amount on Base to the payTo address from any wallet.
4. After paying, poll get_audit_order_status with your order id. Detection usually completes within minutes.
5. Once matched, the order flips to paid and the signed audit report is prepared, human-reviewed, and emailed to the address you gave, within 24h of payment.

Safety rules built into the tool descriptions, worth repeating:

• If a payment submission times out, poll status before paying again. Never pay the same order twice.
• Unpaid orders expire within 24h and cost nothing.
• Agents with spend policies: creating an order is free, but paying it is a real $199 purchase. Confirm with your operator if your policy requires it.

Example session

A typical agent conversation:

User: Before I integrate with this x402 endpoint, is the network volume real? And get me an audit of https://api.example-x402-service.com/paywall

Agent calls get_network_decomposition, checks seal_verified: true, and reports that a large share of headline volume carries wash flags while the organic core is far smaller, citing exact figures and the dataset's own limitations.

Agent calls order_endpoint_audit with the target URL and the user's email, and relays the payment instructions: "Pay exactly 199.002732 USDC on Base to 0xd779...C893. The order id is aud_a80214548a0c4276. Unpaid orders expire in 24h."

User pays from their wallet (or approves their agent's x402 client to pay).

Agent polls get_audit_order_status until paid: true, then tells the user the signed report will arrive by email within 24h.

Configuration

• SMARTFLOW_BASE_URL (env var): overrides the API base. Default https://verify.smartflowproai.com.
• HTTP timeout is 25s per request; the server reports timeouts as retryable network errors and never retries payments on its own.

Selftest (from a source checkout)

npm run selftest

Writes selftest.log with the full JSON-RPC exchange against the live API. The selftest creates one real unpaid test order for https://example.com; test orders are harmless and expire in 24h. The selftest never pays anything.

License

MIT. See LICENSE.