@clearagent/mpp

OFAC sanctions screening for Machine Payments Protocol (MPP). Screen counterparties before your AI agent authorizes payment — in under 50ms.

When an MPP service returns a 402 Payment Required challenge, this middleware extracts the recipient address, screens it against the OFAC SDN list via the ClearAgent API, and blocks the payment if the counterparty is sanctioned. No sanctions match? The 402 is returned unchanged and your MPP client proceeds normally.

Install

npm install @clearagent/mpp

Quick Start

1. Get your tokens

Register at api.clearagent.dev — you'll receive an operator token (1-year) and an agent token (90-day) instantly.

2. Wrap your fetch

import { withKYAScreening } from "@clearagent/mpp";

const safeFetch = withKYAScreening(fetch, {
  operatorToken: process.env.CLEARAGENT_OPERATOR_TOKEN!,
  agentToken: process.env.CLEARAGENT_AGENT_TOKEN!,
});

// Use safeFetch anywhere you'd use fetch with MPP services.
// 402 responses are automatically screened before payment proceeds.
const res = await safeFetch("https://openai.mpp.tempo.xyz/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  }),
});

That's it. If the recipient is OFAC-sanctioned, safeFetch throws a KYAComplianceError and no payment is authorized. If clear, the 402 is returned so your MPP client (mppx, Tempo wallet, etc.) handles payment normally.

How It Works

Agent ──► MPP Service
              │
              ▼ 402 Payment Required
              │  (recipient: 0xABC..., amount: $0.10)
              │
          ┌───┴───┐
          │ @clearagent/mpp
          │  1. Parse 402 challenge
          │  2. Extract recipient address
          │  3. Call /v1/screen (<50ms)
          └───┬───┘
              │
    ┌─────────┴─────────┐
    │                   │
  CLEAR              BLOCKED
    │                   │
    ▼                   ▼
  Return 402        Throw error
  (MPP proceeds     (payment halted,
   with payment)     funds safe)

API

withKYAScreening(fetchFn, config)

Wraps a Fetch-compatible function. Returns a new fetch that automatically screens 402 responses.

const safeFetch = withKYAScreening(fetch, {
  operatorToken: "ey...",   // Required — from /v1/operators/register
  agentToken: "ey...",      // Required — from /v1/operators/register
  apiUrl: "https://api.clearagent.dev",  // Optional, default shown
  onReview: "block",        // "block" | "allow" — default: "block"
  timeoutMs: 5000,          // ClearAgent API timeout — default: 5000
  onScreen: (result, ctx) => {
    console.log(`[KYA] ${result.verdict} for ${ctx.url} (${result.responseTimeMs}ms)`);
  },
  onError: (err, ctx) => {
    console.error(`[KYA] API error for ${ctx.url}:`, err.message);
    return false; // fail-closed (default). Return true to fail-open.
  },
});

withKYAScreeningFromEnv(fetchFn, overrides?)

Convenience — reads tokens from environment variables:

export CLEARAGENT_OPERATOR_TOKEN="ey..."
export CLEARAGENT_AGENT_TOKEN="ey..."

import { withKYAScreeningFromEnv } from "@clearagent/mpp";
const safeFetch = withKYAScreeningFromEnv(fetch);

screenMPPChallenge(challenge, config)

Standalone — screen a parsed 402 challenge directly:

import { parseMPPChallenge, screenMPPChallenge } from "@clearagent/mpp";

const res = await fetch("https://service.mpp.tempo.xyz/api/data");
if (res.status === 402) {
  const challenge = await parseMPPChallenge(res);
  const result = await screenMPPChallenge(challenge, config);

  if (result.verdict === "CLEAR") {
    // Proceed with payment...
  } else {
    console.log(`Blocked: ${result.reason} (txn: ${result.txnId})`);
  }
}

parseMPPChallenge(response)

Parse an MPP 402 response into a structured MPPChallenge object. Handles JSON body and WWW-Authenticate header formats.

KYAComplianceError

Thrown by withKYAScreening when a payment is blocked:

try {
  await safeFetch(url);
} catch (err) {
  if (err instanceof KYAComplianceError) {
    console.log(err.verdict);        // "BLOCK" | "REVIEW" | "UNKNOWN"
    console.log(err.txnId);          // "txn_7bPMkGCp"
    console.log(err.ruleTriggered);  // "OFAC_COUNTERPARTY"
    console.log(err.screenResponse); // Full /v1/screen response
  }
}

Use with Tempo CLI

If your agent uses mppx or the Tempo wallet CLI, wrap the underlying fetch:

// In your agent's initialization
import { withKYAScreening } from "@clearagent/mpp";

// Replace globalThis.fetch with a screened version
const originalFetch = globalThis.fetch;
globalThis.fetch = withKYAScreening(originalFetch, {
  operatorToken: process.env.CLEARAGENT_OPERATOR_TOKEN!,
  agentToken: process.env.CLEARAGENT_AGENT_TOKEN!,
  onScreen: (result) => {
    console.log(`[compliance] ${result.verdict} — ${result.txnId}`);
  },
});

// Now all MPP payments go through OFAC screening automatically

Use with LangChain / CrewAI / OpenAI Agents

Any agent framework that makes HTTP requests to MPP services can use withKYAScreening by wrapping the fetch function the framework uses internally.

What Gets Screened

When a 402 is intercepted, ClearAgent screens:

• Recipient wallet against 38K+ OFAC SDN entity names and sanctioned addresses across ETH, BTC, Tron, Solana, Sei, and all EVM chains
• Service name (derived from hostname) against SDN entity names
• Amount against agent spend policy (if configured in the agent credential)

Screening adds <50ms latency (p99) to the 402 handling flow.

Links

• ClearAgent API Docs
• Register for API keys
• Machine Payments Protocol
• Tempo Documentation
• @clearagent/x402 — compliance screening for x402 payments