{"_id":"@agentradar/x402-trust","_rev":"2-d8ee29aac9d1bfc7da91d9d16acd5410","name":"@agentradar/x402-trust","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@agentradar/x402-trust","version":"0.1.0","keywords":["x402","ai-agents","agent-economy","trust","reputation","erc-8004","agentradar","payments","security","scam-detection"],"license":"MIT","_id":"@agentradar/x402-trust@0.1.0","maintainers":[{"name":"jaxaiagency","email":"admin@jaxaiagency.com"}],"homepage":"https://api.vvpro.ai","bugs":{"url":"https://github.com/Bichev/agentradar-integrations/issues"},"dist":{"shasum":"7b465d788e3740465a42243088e67a44c99805f2","tarball":"https://registry.npmjs.org/@agentradar/x402-trust/-/x402-trust-0.1.0.tgz","fileCount":4,"integrity":"sha512-7zMFBgiv+ZKV9yAnODSOmn52mzC9GPMWblYNju4SncnLYF9MRWfRaQ60H9zK8qQ1M40quw2FJZTDqzMCJiRRJw==","signatures":[{"sig":"MEQCIHGXN/XUZr7vsq1Tl+NZpbX7ArWIsXeLs0B87C6iNc4gAiAb8dW0ecPEzcsPSCx0vdW+XXd2jJjM5Ga7QqEYT2ncww==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":16235},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"26744c77fc6e9486253714dd9b107b849d2e6322","scripts":{"test":"vitest run","build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"jaxaiagency","email":"admin@jaxaiagency.com"},"repository":{"url":"git+https://github.com/Bichev/agentradar-integrations.git","type":"git","directory":"x402-trust"},"_npmVersion":"11.9.0","description":"Pre-pay trust gate for x402 agent payments. Score the payee with AgentRadar before settling an HTTP 402 — block or warn on scam/low-trust wallets. The 'Stripe Radar' for agent payments.","directories":{},"_nodeVersion":"24.14.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^2.0.0","typescript":"^5.4.0"},"_npmOperationalInternal":{"tmp":"tmp/x402-trust_0.1.0_1781658381251_0.9502952129058269","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agentradar/x402-trust","version":"0.2.0","description":"Pre-pay trust gate for x402 agent payments. Score the payee with AgentRadar before settling an HTTP 402 — block or warn on scam/low-trust wallets. The 'Stripe Radar' for agent payments.","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","test":"vitest run","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"npm run build"},"keywords":["x402","ai-agents","agent-economy","trust","reputation","erc-8004","agentradar","payments","security","scam-detection"],"license":"MIT","homepage":"https://api.vvpro.ai","repository":{"type":"git","url":"git+https://github.com/Bichev/agentradar-integrations.git","directory":"x402-trust"},"engines":{"node":">=20.0.0"},"devDependencies":{"typescript":"^5.4.0","vitest":"^2.0.0"},"gitHead":"d68bb57dfd7a90629e0ca3a1aed056abb69810b1","_id":"@agentradar/x402-trust@0.2.0","bugs":{"url":"https://github.com/Bichev/agentradar-integrations/issues"},"_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-2P04RO2pDNB10hUjvtFAP8pKpPyWHPYCcBF97dHDhwlskpZntRtwOOeO7In4VUt9RyHLkEU28GlFCa35Kaegjg==","shasum":"4547d4a74293619604971ac6ff56922d5254dbde","tarball":"https://registry.npmjs.org/@agentradar/x402-trust/-/x402-trust-0.2.0.tgz","fileCount":4,"unpackedSize":21215,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEh1tOlTDPQjMaW47cQg4HWgGKw4iWiQFfytC9abJ3GoAiAEsM4f1LkFIlVAGkeisck9Km+/aYq6HHw20DuKOWKtFA=="}]},"_npmUser":{"name":"jaxaiagency","email":"admin@jaxaiagency.com"},"directories":{},"maintainers":[{"name":"jaxaiagency","email":"admin@jaxaiagency.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/x402-trust_0.2.0_1783627176308_0.941143307705165"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-17T01:06:21.008Z","modified":"2026-07-09T19:59:36.650Z","0.1.0":"2026-06-17T01:06:21.383Z","0.2.0":"2026-07-09T19:59:36.441Z"},"bugs":{"url":"https://github.com/Bichev/agentradar-integrations/issues"},"license":"MIT","homepage":"https://api.vvpro.ai","keywords":["x402","ai-agents","agent-economy","trust","reputation","erc-8004","agentradar","payments","security","scam-detection"],"repository":{"type":"git","url":"git+https://github.com/Bichev/agentradar-integrations.git","directory":"x402-trust"},"description":"Pre-pay trust gate for x402 agent payments. Score the payee with AgentRadar before settling an HTTP 402 — block or warn on scam/low-trust wallets. The 'Stripe Radar' for agent payments.","maintainers":[{"name":"jaxaiagency","email":"admin@jaxaiagency.com"}],"readme":"# @agentradar/x402-trust\n\n**A pre-pay trust gate for x402 agent payments.** Before your agent settles an HTTP `402`, score the payee wallet with [AgentRadar](https://api.vvpro.ai) and **block or warn** when the recipient is a known scam or low-trust wallet.\n\nThink of it as the *\"Stripe Radar\" for agent payments* — a fraud check at the one universal chokepoint every paying agent passes through.\n\n- **Library-agnostic.** Works with any x402 client (`@x402/fetch`, `x402-axios`, custom). It keys off the x402 protocol's `402` response (`accepts[].payTo`), not a specific client's internals.\n- **Zero runtime dependencies.** Uses the global `fetch` (Node 20+).\n- **Fail-open or fail-closed.** `\"block\"` mode throws on a bad payee; `\"warn\"` mode logs and proceeds.\n\n> Powered by AgentRadar's on-chain trust scoring (ERC-8004 reputation + static analysis + scam-DB). Verdicts: `TRUSTED · VERIFIED · CAUTION · RISKY · BLOCKED`.\n\n## Install\n\n```bash\nnpm install @agentradar/x402-trust\n```\n\n## Quick start — native x402 lifecycle hook (recommended, v0.2.0+)\n\nx402 clients expose an official [lifecycle-hooks API](https://docs.x402.org/advanced-concepts/lifecycle-hooks). `createTrustHook` plugs straight into `x402Client.onBeforePaymentCreation`, so the trust check runs on **every transport** (HTTP, MCP) right before the payment payload is created — and blocks via the protocol's own `{ abort, reason }` mechanism:\n\n```ts\nimport { x402Client } from \"@x402/core\";\nimport { createTrustHook } from \"@agentradar/x402-trust\";\n\nconst client = new x402Client();\n\nclient.onBeforePaymentCreation(\n  createTrustHook({\n    policy: { mode: \"block\", minScore: 40 }, // block scams + anything under 40/100\n    onDecision: (d) =>\n      console.log(`[x402-trust] ${d.result.address} → ${d.result.verdict} (${d.result.score})`),\n  }),\n);\n```\n\nFailure semantics: if the AgentRadar API is unreachable, `\"block\"` mode aborts the payment (fail-closed) and `\"warn\"` mode proceeds (fail-open).\n\n## Alternative — wrap your paying `fetch`\n\nFor clients that don't use `@x402/core` (or pre-v2 setups), the original `fetch` wrapper still works:\n\n```ts\nimport { wrapFetchWithPayment } from \"@x402/fetch\";\nimport { wrapFetchWithTrust } from \"@agentradar/x402-trust\";\n\n// 1. Your normal x402 paying fetch\nconst payFetch = wrapFetchWithPayment(fetch, walletClient);\n\n// 2. Gate it: AgentRadar scores the payee before any USDC moves\nconst trustedFetch = wrapFetchWithTrust(payFetch, {\n  policy: { mode: \"block\", minScore: 40 }, // block scams + anything under 40/100\n  onDecision: (d) =>\n    console.log(`[x402-trust] ${d.result.address} → ${d.result.verdict} (${d.result.score})`),\n});\n\n// 3. Use it exactly like fetch. Blocked payees throw TrustBlockedError before payment.\nconst res = await trustedFetch(\"https://some-x402-service.example/api\");\n```\n\n## Standalone checks\n\n```ts\nimport { checkTrust, decide } from \"@agentradar/x402-trust\";\n\nconst result = await checkTrust(\"0xPayeeAddress\");\n// { address, score, verdict, riskFlags }\n\nconst decision = decide(result, { minScore: 50 });\nif (!decision.allowed) throw new Error(decision.reason);\n```\n\n## Gate inside your own 402 handler (e.g. axios)\n\nIf you handle the `402` yourself, pass the response body to `assertPayeesTrusted`:\n\n```ts\nimport { assertPayeesTrusted } from \"@agentradar/x402-trust\";\n\n// `body` is the parsed 402 response ({ accepts: [{ payTo, ... }] })\nawait assertPayeesTrusted(body, { policy: { mode: \"block\" } }); // throws on a bad payee\n// ...then run x402-axios' payment retry\n```\n\n## API\n\n| Export | Description |\n|---|---|\n| `createTrustHook(opts?)` | **v0.2.0** — Returns a native `onBeforePaymentCreation` lifecycle hook for `x402Client` (`@x402/core`). Scores the selected payee and aborts via `{ abort, reason }` per policy. |\n| `wrapFetchWithTrust(payFetch, opts?)` | Returns a `fetch` that probes for `402`, scores each payee, enforces policy, then delegates to `payFetch`. |\n| `checkTrust(address, opts?)` | Calls `GET {baseUrl}/verify?target=…`; returns `{ address, score, verdict, riskFlags }`. Cached in-memory (TTL configurable). |\n| `decide(result, policy?)` | Applies a `TrustPolicy` → `{ allowed, reason, result }`. |\n| `assertPayeesTrusted(payload, opts?)` | Extracts `accepts[].payTo` from a 402 body and enforces policy (throws in block mode). |\n| `extractPayTo(payload)` | Pulls unique, lower-cased payee addresses from a 402 body. |\n| `createTrustGate(opts)` | Factory binding one option set to all helpers. |\n| `TrustBlockedError` | Thrown in block mode; carries `.decision`. |\n\n### `TrustGateOptions`\n\n| Field | Default | Notes |\n|---|---|---|\n| `baseUrl` | `https://api.vvpro.ai` | AgentRadar API base. |\n| `apiKey` | — | Sent as `x-api-key` (raises rate limits). |\n| `policy.mode` | `\"block\"` | `\"block\"` throws on a bad payee; `\"warn\"` continues. |\n| `policy.blockVerdicts` | `[\"BLOCKED\"]` | Verdicts that fail the gate. |\n| `policy.minScore` | — | Block below this composite score (0–100). |\n| `cacheTtlMs` | `60000` | In-memory cache for `/verify`. `0` disables. |\n| `fetchImpl` | global `fetch` | Override for tests / older runtimes. |\n| `onDecision` | — | Callback per payee decision (telemetry/logging). |\n\n## How it works\n\n```\nagent ──probe──▶ x402 service           (no payment)\n        ◀─402──  { accepts:[{ payTo }] }\nagent ──verify─▶ AgentRadar /verify      (score each payTo)\n        ◀──────  { score, verdict }\n  block? ──yes──▶ throw TrustBlockedError (no funds move)\n         ──no───▶ payFetch() settles the 402 normally\n```\n\n## Develop\n\n```bash\nnpm install\nnpm test        # vitest\nnpm run build   # tsc → dist/\n```\n\nMIT © AgentRadar\n","readmeFilename":"README.md"}