x402 Research

io.github.KevinM222Published by GitHub account KevinM222v0.5.0Updated Oct 29, 2026

Pay-per-call x402 crypto research and Base address/approval risk checks. Testnet by default.

VerifiedSTDIODesktop onlyFinanceSecurity & Monitoring

Overview

AI-generated overview

Pay-per-call crypto research and Base address risk checks over x402, paid in USDC from your own wallet, testnet by default.

What you can do
  • Get trend signals for one asset or up to ten at once
  • Pull a technical and sentiment brief (price, changes, RSI, moving averages, Fear & Greed)
  • Screen a Base address for risk flags and list its live ERC-20 approvals
  • Decode x402 payment-required headers and check settlement transactions
  • Run a combined preflight verdict before signing, swapping, approving or paying
  • Show session network, spend, cap and per-call maximum
When to use it
Useful when an assistant needs quick crypto market signals or a pre-transaction safety check on a Base address, and you are willing to pay small USDC amounts per call. Start in preview mode to see the 402 terms without paying.
Requirements
Runs locally via npx (Node.js) as a stdio server in Claude Desktop or Cursor. A dedicated wallet private key in X402_BUYER_PRIVATE_KEY is needed to pay; without it the server stays in preview. X402_NETWORK selects Base Sepolia (default) or Base mainnet; optional X402_MAX_PRICE_USDC, X402_SESSION_CAP_USDC and X402_PREVIEW. Network access to the hosted API.
Before you install
Every paid call spends USDC from the wallet behind X402_BUYER_PRIVATE_KEY, and anyone who can read the client config or process environment can spend that wallet; use a dedicated low-balance wallet, never a main one. Caps limit what the server signs, not what a leaked key can do. Setting X402_NETWORK to mainnet means real funds. Results are informational heuristics, not financial advice, and a proceed verdict does not mean safe.

Installation

In SourceWeft

  1. Open x402 Research in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

x402-research-mcp

MCP (stdio) server for the x402-research pay-per-call API. Testnet (Base Sepolia) by default. Base mainnet only if you explicitly set X402_NETWORK=eip155:8453. The publisher never holds keys: payments come from your wallet key, supplied by you via env var, and are capped per call and per session.

[!WARNING] Use a dedicated, low-balance wallet: never your main wallet. Create a fresh key just for this server and fund it with only a few USDC (on mainnet, a little more than your session cap). Anyone or anything that can read your MCP client config or this process's environment can spend that wallet's funds. The caps limit what this server signs, not what a leaked key can do.

Tools (prices per call, USDC on Base, from /llms.txt)

toolrouteprice
signal(asset)GET /api/signal/{asset}0.003
signal_batch(assets[≤10])GET /api/signal-batch?assets=0.02
brief(asset)GET /api/brief/{asset}0.03
risk_snapshot(address)GET /api/firm/risk-snapshot?address=0.03
invoice_decode(header)POST /api/x402/invoice-decode0.02
settlement_status(tx)GET /api/x402/settlement-status?tx=0.02
approval_enumerate(address)GET /api/x402/approval-enumerate?address=0.03
preflight(address, invoice?)GET /api/x402/preflight?address=[&invoice=]0.05
session_status()localfree

Assets: btc eth sol xrp doge ada avax link dot ltc bch uni aave xlm hbar shib sui near atom fil. Every paid tool also accepts preview: true (return the 402 terms, pay nothing) and max_price_usdc.

Safety

  • Preview mode is on whenever X402_BUYER_PRIVATE_KEY is unset or X402_PREVIEW=1: tools return the decoded 402 terms and never sign.
  • Per-call max X402_MAX_PRICE_USDC (default 0.10). A tool's max_price_usdc can only lower it.
  • Session cap X402_SESSION_CAP_USDC (default 0.50). A call that would push spend over the cap is refused before signing. Spend is counted when a signed payment is sent. It resets when the server process restarts.
  • Offers are refused if they're above the advertised price, on another network, not the exact scheme, or in a non-canonical USDC asset.
  • payTo allowlist (hardcoded): every paid tool (signal, signal_batch, brief, risk_snapshot, invoice_decode, settlement_status, approval_enumerate, preflight) pays only the Agent Firm treasury 0xa26f179e42836bc4ae0cea997fdfc9602d5b8147. Since 0.5.0; 0.4.x expected a different address for signal, signal_batch and brief and refuses the treasury there, so upgrade. Any other recipient is refused, even if X402_RESEARCH_URL points elsewhere.
  • The server never logs its environment or the key, and error messages don't echo config.
  • There is no way to pass in a pre-signed payment: every payment is signed by this server under the caps above.
  • Use a dedicated hot wallet holding only a few USDC. The key stays in the local process and is never logged or returned.

Config

vardefault
X402_NETWORKeip155:84532 (Base Sepolia). Set eip155:8453 for Base mainnet
X402_RESEARCH_URLhttps://x402-research-iota.vercel.app (mainnet-only; testnet needs a Sepolia deployment)
X402_BUYER_PRIVATE_KEYunset → preview only
X402_MAX_PRICE_USDC / X402_SESSION_CAP_USDC0.10 / 0.50
X402_PREVIEWunset (1 forces preview)

Install

Claude Desktop (claude_desktop_config.json) or Cursor (~/.cursor/mcp.json):

json
{  "mcpServers": {    "x402-research": {      "command": "npx",      "args": ["-y", "@agentfirm402/x402-research-mcp"],      "env": {        "X402_NETWORK": "eip155:8453",        "X402_PREVIEW": "1"      }    }  }}

Start in preview. To pay, remove X402_PREVIEW and add "X402_BUYER_PRIVATE_KEY": "0x…" (a dedicated low-balance wallet, never your main one), and optionally "X402_SESSION_CAP_USDC": "0.25".

Tests

npm test runs offline against local mocks with throwaway keys and no funds. It covers unit refusals for each check, preview with no key, and a stdio leak test that greps all stdout and stderr for /0x[0-9a-fA-F]{64}/. npm run test:mainnet-preview makes live mainnet 402 calls in preview mode and pays nothing.

Release

Dependencies are pinned exactly, with a committed lockfile. Publishing happens only through .github/workflows/mcp-publish.yml (manual dispatch, npm publish --provenance).

Informational only. Not financial advice. MIT.

Source: mcp/README.md at commit 3d88b54

Tools

9

signal

Compact live trend signal (bullish/neutral/bearish + score) for one asset. Price: 0.003 USDC per call (x402, Base Sepolia testnet). Paid from YOUR wallet; capped per call and per session.

Parametersassetrequiredpreviewmax_price_usdc

signal_batch

Live trend signals for up to 10 assets in one call (flat price). Price: 0.02 USDC per call (x402, Base Sepolia testnet). Paid from YOUR wallet; capped per call and per session.

Parametersassetsrequiredpreviewmax_price_usdc

brief

Technical + sentiment research brief (price, 24h/7d change, RSI14, SMA20/50, trend, Fear & Greed). Price: 0.03 USDC per call (x402, Base Sepolia testnet). Paid from YOUR wallet; capped per call and per session.

Parametersassetrequiredpreviewmax_price_usdc

risk_snapshot

Public-data red-flag snapshot of a Base address (contract/EOA, EIP-7702, verification, proxy, age, balances, risk level). Informational only. Price: 0.03 USDC per call (x402, Base Sepolia testnet). Paid from YOUR wallet; capped per call and per session.

Parametersaddressrequiredpreviewmax_price_usdc

invoice_decode

Decode and sanity-check a base64 x402 PAYMENT-REQUIRED header (scheme, network, USDC asset, payTo, amount); verdict ok/warn/fail. Never signs or pays. Price: 0.02 USDC per call (x402, Base Sepolia testnet). Paid from YOUR wallet; capped per call and per session.

Parametersheaderrequiredpreviewmax_price_usdc

settlement_status

Check an x402 settlement tx on Base: success, USDC Transfer / AuthorizationUsed events, confirmations. Price: 0.02 USDC per call (x402, Base Sepolia testnet). Paid from YOUR wallet; capped per call and per session.

Parameterstxrequiredpreviewmax_price_usdc

approval_enumerate

List live ERC-20 approvals for a Base address (token, spender, allowance, unlimited flag). 503 when the indexer is down (not charged). Price: 0.03 USDC per call (x402, Base Sepolia testnet). Paid from YOUR wallet; capped per call and per session.

Parametersaddressrequiredpreviewmax_price_usdc

preflight

One-call check before you sign, swap, approve or pay: Base address risk + live ERC-20 approvals + OFAC screen (+ optional x402 invoice check), with a proceed/review/stop verdict. Informational heuristic; "proceed" does not mean safe. Price: 0.05 USDC per call (x402, Base Sepolia testnet). Paid from YOUR wallet; capped per call and per session.

Parametersaddressrequiredinvoicepreviewmax_price_usdc

session_status

Free. Shows network, preview mode, USDC spent this session, cap and per-call max.

Takes no parameters.

Version history

2
  1. v0.5.0LatestOct 26, 2026
  2. v0.4.2Oct 25, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts