npm package: @pausesecure/x402-risk
Description: PAUSE Risk Extension for x402 — risk-score every payTo address before payment
Author: PAUSE
Latest version: 1.0.0

# @pause/x402-risk

**PAUSE Risk Extension for x402 — risk-score every address before payment.**

Stop AI agents from paying malicious addresses. `@pause/x402-risk` adds [PAUSE Risk Engine](https://pausescan.com) scoring to the [x402 payment protocol](https://x402.org), blocking payments to high-risk wallets before any money moves.

Works with `@x402/fetch`, `@x402/axios`, Express, Hono, and any custom x402 flow.

## Why

x402 lets agents pay for resources over HTTP. But agents pay whatever address the server tells them to — **blindly**.

- The [402Bridge hack](https://crypto.news/402bridge-hack-leads-to-over-200-users-drained-of-usdc/) drained 200+ users' USDC
- x402 V2's dynamic `payTo` routing means addresses can change per-request
- AI agents executing payments autonomously have no human oversight

`@pause/x402-risk` fixes this. Every `payTo` address is scanned across **11 Bayesian risk signals** before your agent signs anything. HIGH risk = payment blocked. Zero funds lost.

## Install

```bash
npm install @pause/x402-risk
```

## Quick Start — Client (Protect Your Agent)

```typescript
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createRiskGuard, wrapFetchWithRiskGuard } from "@pause/x402-risk/client";

// Setup x402 client (standard)
const client = new x402Client();
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`),
});

// Add PAUSE risk guard — ONE LINE
const guard = createRiskGuard({ minScore: 40 });

// Wrap fetch with both payment and risk
const safeFetch = wrapFetchWithRiskGuard(
  wrapFetchWithPayment(fetch, client),
  guard
);

// Every payment is now risk-scored automatically
const response = await safeFetch("https://api.example.com/paid-endpoint");
```

If the `payTo` address scores below 40 (HIGH risk), the payment is **blocked** and a `PaymentBlockedError` is thrown. No signature. No gas. No funds lost.

## Quick Start — Server (Protect Your Service)

```typescript
import express from "express";
import { paymentMiddleware } from "@x402/express";
import { createRiskMiddleware } from "@pause/x402-risk/server";

const app = express();

// Add PAUSE risk check BEFORE x402 payment middleware
app.use(createRiskMiddleware({ minScore: 40 }));

// Standard x402 paywall
app.use(paymentMiddleware({ /* your routes */ }, resourceServer));
```

Payers with HIGH risk wallets are rejected with a 403 before your endpoint runs.

## Configuration

```typescript
const guard = createRiskGuard({
  // Required
  minScore: 40,           // Block addresses scoring below this (0-100)

  // Optional
  riskEngineUrl: "https://api.pausescan.com",  // PAUSE Risk Engine URL
  apiKey: "pk_...",       // Pro API key (50 free scans/month without)
  warnScore: 70,          // Trigger onWarning callback below this score
  cacheTtlMs: 300000,     // Cache scores for 5 minutes (default)
  timeoutMs: 5000,        // Risk engine timeout (default)
  failOpen: false,        // true = allow payment if engine is down

  // Address lists
  allowlist: ["0xYourWallet", "0xTrustedPartner"],
  blocklist: ["0xKnownScammer"],

  // Callbacks
  onBlocked: (assessment, payTo) => { /* log, alert, etc */ },
  onWarning: (assessment, payTo) => { /* caution logging */ },
  onAssessment: (assessment, payTo) => { /* every scan */ },
});
```

## Risk Scoring

The PAUSE Risk Engine analyzes each address across **11 independent Bayesian signals**:

| Signal | Weight | What It Detects |
|---|---|---|
| Mixer Exposure | 0.45 | Tornado Cash and mixing service interaction |
| Draining Pattern | 0.30 | Wallet drainer behavior (approve + sweep) |
| Exchange Cluster | 0.25 | Proximity to exchange hot/cold wallets |
| Sweep Pattern | 0.25 | Funds consolidation into single address |
| TX Burst Anomaly | 0.20 | Bot-like transaction volume spikes |
| Scam Graph | 0.20 | Connections to reported scam addresses |
| Dusting Attack | 0.15 | Micro-transactions for wallet tracking |
| ENS Authenticity | 0.15 | ENS domain ownership verification |
| Rival Consensus | 0.15 | Cross-reference with external scoring |
| Wallet Age | 0.10 | Account creation date and activity |
| Balance Volatility | 0.10 | Abnormal balance fluctuation patterns |

Signals are combined using **log-odds Bayesian scoring with correlation discounting** to produce a single 0-100 safety score.

| Score | Risk | Action |
|---|---|---|
| 70-100 | SAFE | Payment proceeds normally |
| 40-70 | MEDIUM | Payment proceeds, `onWarning` fires |
| 0-40 | HIGH | **Payment BLOCKED**, `PaymentBlockedError` thrown |

## Standalone Usage (No x402)

Use the risk engine directly for any address screening:

```typescript
import { PauseRiskEngine } from "@pause/x402-risk";

const engine = new PauseRiskEngine();
const result = await engine.scan("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045");

console.log(result.score);    // 87
console.log(result.risk);     // "SAFE"
console.log(result.signals);  // Array of 11 signal results
```

## Error Handling

```typescript
import { PaymentBlockedError, RiskEngineUnavailableError } from "@pause/x402-risk";

try {
  const response = await safeFetch("https://api.example.com/paid");
} catch (error) {
  if (error instanceof PaymentBlockedError) {
    // Address was HIGH risk — payment blocked, no funds lost
    console.log(error.assessment.score);  // e.g., 23
    console.log(error.assessment.risk);   // "HIGH"
    console.log(error.payTo);             // "0x..."
  }
  if (error instanceof RiskEngineUnavailableError) {
    // Risk engine down and failOpen=false
    console.log(error.payTo);
  }
}
```

## API Reference

### Client

| Export | Description |
|---|---|
| `createRiskGuard(config)` | Create a risk guard instance |
| `wrapFetchWithRiskGuard(fetch, guard)` | Wrap fetch with risk checking |
| `createRiskCheck(config)` | Standalone risk check function |

### Server

| Export | Description |
|---|---|
| `createRiskMiddleware(config)` | Express/Connect middleware |
| `createPayerCheck(config)` | Standalone payer check function |

### Core

| Export | Description |
|---|---|
| `PauseRiskEngine` | Direct risk engine client |
| `PaymentBlockedError` | Error thrown when payment is blocked |
| `RiskEngineUnavailableError` | Error thrown when engine is unreachable |

## Links

- **PAUSE Platform**: [pausesecure.com](https://pausesecure.com)
- **Free Scanner**: [pausescan.com](https://pausescan.com)
- **x402 Protocol**: [x402.org](https://x402.org)
- **Smart Contract**: [PAUSECommit V2 on Etherscan](https://etherscan.io/address/0x604152D82Fd031cCD8D27F26C5792AC2CD328bF4)

## License

MIT — PAUSE (Pre-Authorization Unified Security Engine)