io.github.kaditang/402sentinel-mcp
x402 payment safety for AI agents: counterparty risk gate, payment firewall, compliance, RWA gate.
Open source Open in the app JSON README (API)
About
x402 payment safety for AI agents: counterparty risk gate, payment firewall, compliance, RWA gate.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- kaditang
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.7.1
- Stars
- 1
- Last push
- 2026-09-06T07:48:50Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-29 04:00:18
- Updated
- 2026-08-29 04:00:18
- Origin id
io.github.kaditang/402sentinel-mcp
README
# 402sentinel-mcp
MCP tools that let your AI agent **check an x402 counterparty's risk before it
pays** — and turn that risk into an enforceable wallet spending policy. Give it a
payTo address, get back a 0–100 risk score + an `allow` / `review` / `block`
decision, scored from on-chain settlement behaviour on Base (address age,
facilitator-aware payer diversity, settlement maturity) + a delivery-outcome
flywheel, with honest confidence/coverage.
Tools — vet the **seller**:
- `assess_counterparty` ($0.002) — risk score + decision + a ready-to-apply `recommended_policy`
- `assess_counterparty_deep` ($0.02) — same, scans more on-chain history
- `recommend_policy` ($0.002) — decision + wallet-ready spending policy (caps, denylist, approval)
- `report_outcome` (free) — after paying, report delivery to train the reliability flywheel
Tools — vet the **payment itself** (buyer-side):
- `firewall` ($0.002) — should YOUR agent make THIS payment now? Catches fraudulent routing (payTo swapped vs the address you usually pay), drain velocity, overcharge, and injection-sourced instructions. `agent_id` + a wallet-ownership signature are attached automatically from your configured wallet — trusted routing history with no extra steps.
- `firewall_record` (free) — seed your agent's payment history so the firewall has a behavioural baseline.
- `firewall_outcome` (free) — after a verdict, report what actually happened (fraud / legit / …) so the firewall learns which signals are predictive and downweights noisy ones (safety signals stay deterministic).
Tools — vet the **asset** and the **flow**:
- `assess_rwa` ($0.02) — RWA risk gate: score a **tokenized asset** (treasury/stock/credit) before buying it. Proxy-aware transfer-restriction scan + behavioral transfer simulation — catches permissioned securities an agent can buy but **not transfer or redeem** (trapped funds), live pause state, issuer identity + issuer sanctions.
- `compliance_check` ($0.02) — pre-pay compliance screen: OFAC sanctions (hard block), counterparty due-diligence tier, structuring/smurfing detection, FATF Travel-Rule threshold (informational). Not legal advice.
- `verify_service` ($0.02) — opt-in **402Sentinel Verified** badge: submit your own payTo for a deep settlement-graph audit; pass → signed time-boxed credential + public allow-list. Failures stay private.
It's a thin client for the hosted service at **https://402sentinel.com** — the
scoring model and facilitator-identification logic live server-side (closed); this
package only forwards the request and pays for it, so it's open source.
## Quickstart — gate a payment in 5 lines
Before your agent pays **any** x402 counterparty, ask the firewall; if it doesn't say
`allow`, don't pay. No MCP needed — any standard x402 v2 client works:
```ts
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const client = new x402Client();
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.AGENT_KEY) });
const http = new x402HTTPClient(client);
const body = JSON.stringify({
payment: { payto_address: target, amount, resource_url },
context: { source: "web_content", untrusted_text: pageYouActedOn }, // pass what you scraped
});
const url = "https://402sentinel.com/api/firewall";
const init = (h = {}) => ({ method: "POST", headers: { "Content-Type": "application/json", ...h }, body });
const r1 = await fetch(url, init());
const pr = http.getPaymentRequiredResponse((n) => r1.headers.get(n), await r1.json());
const payment = http.encodePaymentSignatureHeader(await http.createPaymentPayload(pr));
const data = await (await fetch(url, init(payment))).json();
if (data.decision !== "allow") throw new Error(`402Sentinel ${data.decision}: ${data.recommended_action}`);
// …safe to pay `target`.
```
That one $0.002 call catches **fraudulent routing** (payTo swapped vs the address you
usually pay), **prompt-injection payments** (a payTo that appeared in `untrusted_text`),
**drains**, **overcharges**, and **sanctioned/illicit** counterparties.
**In an MCP framework** (Claude, Cursor, …) instead, just add the server — your agent gets
all 10 tools by name (see Configure below):
```jsonc
{ "mcpServers": { "402sentinel": { "command": "402sentinel-mcp", "env": { "CLIENT_PRIVATE_KEY": "0x…" } } } }
```
## Install
```sh
npm i -g @kaditang/402sentinel-mcp
```
## Configure
Add to your MCP client (Claude Desktop, Cursor, etc.):
```jsonc
{
"mcpServers": {
"402sentinel": {
"command": "402sentinel-mcp",
"env": {
"CLIENT_PRIVATE_KEY": "0x... // a Base wallet holding USDC on-chain (no ETH/gas needed)"
}
}
}
}
```
Paid calls cost from **$0.002** (shallow) to **$0.02** (deep), paid automatically
in USDC via standard x402 (`exact` EIP-3009 on Base — the facilitator submits the
transfer, so the buyer needs no gas) from the configured wallet. The free tools
need no key.
## Use
The agent calls it before authorizing a payment:
```
assess_counterparty({
target: { payto_address: "0x..." },
payment_context: { amount: 10, asset: "USDC" },
policy: { block_at_score: 70, review_at_score: 40 }
})
→ { decision: "review", risk_score: 52, confidence: 0.41, coverage: {...},
dimensions: [...], recommendation: "...",
recommended_policy: { action: "limit", max_payment_usdc: 5, daily_cap_usdc: 15,
add_to_denylist: false, require_human_approval: true } }
```
- `block` / `deny` → don't pay
- `review` / `limit` → cap exposure / escrow (use `recommended_policy` for the caps)
- `allow` → proceed
`recommend_policy(...)` returns just the decision + `recommended_policy` — apply
`max_payment_usdc` / `daily_cap_usdc` / `add_to_denylist` directly to your agent
wallet's spending limits. After paying, call `report_outcome({ assessment_id,
outcome })` to improve future scores.
## Disclaimer
Algorithmic risk signal, informational only — **not advice, not an endorsement,
and not an accusation** about any party. Scores are probabilistic estimates from
limited public on-chain data and heuristics, and may misclassify. Do your own due
diligence; don't rely on it as your sole basis to pay or refuse. See
https://402sentinel.com/terms.
MIT.