x402-payguard / tree / README.md · raw (this view has old GitHub links rewritten for the mirror; raw is byte-exact)

PayGuard: OFAC sanctions screening for crypto addresses (MCP server + x402 API)

Start here: copy-paste MCP configs for Claude, Cursor and Windsurf, x402 client code, AgentKit and LangChain wrappers: https://agentgate-source.pages.dev/start/
API: https://api.youraitools.co/payguard · fallback (same Worker): https://payguard.agentgate.workers.dev · npm: @agentgate-builder/payguard

OFAC SDN sanctions screening for crypto addresses, for AI agents and payment flows, paid per call over x402. One call reports whether an address appears in the US Treasury OFAC Specially Designated Nationals (SDN) list, and if so which entity, which sanctions programs and since when.

Live API: https://api.youraitools.co/payguard (fallback: https://payguard.agentgate.workers.dev)
Price: $0.001 USDC per address (/v1/address), $0.01 USDC per batch of up to 50 (/v1/batch), on Base (eip155:8453). Invalid input is never charged.
Free tier: /v1/preview (sanctioned true/false + chain guess) and a remote MCP server at /mcp (10 calls/min per IP).
Local MCP (stdio): npx -y @agentgate-builder/payguard. Free and offline: the same verdict as the free preview (sanctioned true/false, match count, chain guess) from a bundled list snapshot. Optional full details through the paid API with your own wallet (below).
Source: https://agentgate-source.pages.dev/x402-payguard/ (MIT) · npm: @agentgate-builder/payguard · all our tools: https://youraitools.co/built-by-us

Informational screening against public OFAC SDN data. Not legal advice and not a compliance program.

Why

Agents are starting to send money: x402 payments, payouts, refunds, bounties. Paying an address that OFAC has designated is the one mistake that is both easy to check and expensive to get wrong. OFAC publishes the addresses it designates ("Digital Currency Address - ETH / XBT / TRX / USDT ..." identifiers in the SDN list); PayGuard turns that file into a fast exact-match lookup with the context a human reviewer needs.

Quick start

# Free preview (the sample is a Lazarus Group address from the SDN list; the second is the USDC contract on Base)
curl -s "https://api.youraitools.co/payguard/v1/preview?address=0x098B716B8Aaf21512996dC57EB0615e2383E2f96"
curl -s "https://api.youraitools.co/payguard/v1/preview?address=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

# Paid: answers 402 with x402 terms; any x402 client pays it
curl -i "https://api.youraitools.co/payguard/v1/address?address=0x098B716B8Aaf21512996dC57EB0615e2383E2f96"

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';
import { privateKeyToAccount } from 'viem/accounts';

const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(privateKeyToAccount(process.env.BUYER_KEY)) }],
});
const r = await (await pay('https://api.youraitools.co/payguard/v1/address?address=' + encodeURIComponent(recipient))).json();
if (r.sanctioned) holdForReview(recipient, r.matches);

Response (`GET /v1/address`)

{
  "address": "0x098b716b8aaf21512996dc57eb0615e2383e2f96",
  "sanctioned": true,
  "match_count": 1,
  "matches": [{ "entity": "LAZARUS GROUP", "entity_type": "Entity", "sdn_uid": 27307, "programs": ["DPRK3"],
                "list_date": "2019-09-13", "listed_currency": "ETH", "listed_as": "Digital Currency Address - ETH" }],
  "chain": { "format": "evm-hex20", "guess": "evm", "checksum": "eip55", "checksum_valid": true, "checksum_address": "0x098B716B8Aaf21512996dC57EB0615e2383E2f96" },
  "source": "US Treasury OFAC Specially Designated Nationals (SDN) list",
  "source_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN.XML",
  "list_updated_at": "2026-10-21",
  "list_age_days": 0,
  "sdn_address_count": 1050,
  "disclaimer": "Informational screening against the public OFAC SDN list ... Not legal advice. ..."
}

POST /v1/batch {"addresses": [...]} (1-50) returns count, sanctioned_count, any_sanctioned and one result per address.

MCP

{ "mcpServers": { "payguard": { "type": "http", "url": "https://api.youraitools.co/payguard/mcp" } } }
{ "mcpServers": { "payguard": { "command": "npx", "args": ["-y", "@agentgate-builder/payguard"] } } }

Tools screen_address (remote and stdio) and screen_addresses (stdio, up to 50).

	Remote `/mcp`	stdio (npm), default	stdio with `PAYGUARD_X402_PRIVATE_KEY`
Cost	free, 10 calls/min per IP	free, offline, unlimited	$0.001 per address, $0.01 per batch (USDC on Base, from your wallet)
Returns	sanctioned true/false, match count, chain guess	same, from the list snapshot bundled in the installed version (`list_updated_at`)	full result: SDN entity, type, uid, programs, list date, checksum; list refreshed daily

The free tiers don't include entity, program or date details. Those come from the paid endpoint https://api.youraitools.co/payguard/v1/address, which every offline result points to (full_details).

Paid mode in the stdio server. Set PAYGUARD_X402_PRIVATE_KEY (or X402_PRIVATE_KEY) to the private key of a Base wallet holding a little USDC, and add the optional x402 client packages:

{ "mcpServers": { "payguard": {
  "command": "npx",
  "args": ["-y", "-p", "@agentgate-builder/payguard", "-p", "@x402/fetch", "-p", "@x402/evm", "-p", "viem", "payguard"],
  "env": { "PAYGUARD_X402_PRIVATE_KEY": "0x<key of a wallet with a few cents of USDC on Base>" } } } }

The server then pays the hosted API per call over x402 with @x402/fetch. Guards: Base USDC only, at most $0.01 per payment, and only to PayGuard's pay-to address. Invalid input is rejected locally and never paid for. If a paid call fails, you get the offline preview plus the error. Use a dedicated low-balance wallet: the key stays in your MCP client's config and is never logged or sent anywhere except as an x402 payment signature. PAYGUARD_API_URL overrides the endpoint (e.g. the workers.dev fallback).

Library

import { previewAddress } from '@agentgate-builder/payguard';
previewAddress('0x098B716B8Aaf21512996dC57EB0615e2383E2f96');
// { sanctioned: true, match_count: 1, chain: { guess: 'evm', ... }, tier: 'preview', full_details: 'https://api.youraitools.co/payguard/v1/address', ... }

Since 0.2.0 the npm package ships a lite snapshot (lookup keys and match counts only) and exports previewAddress, previewBatch, normalizeAddress and invalidInput. The full engine with entity details (src/screen.js) runs only in the hosted Worker. Before 0.2.0, the package bundled the full list and exported screenAddress.

Data and matching

Source: the official SDN files from sanctionslistservice.ofac.treas.gov (SDN.XML for names, programs and every Digital Currency Address - XXX id; SDN_ADVANCED.XML for the date each entry was added). No third-party mirrors.
scripts/build-sdn.py builds src/data/sdn.js; scripts/refresh.sh runs daily, and redeploys only when the list changed (with a guard against truncated downloads).
Exact match. 0x EVM hex and bech32 / cashaddr addresses are case-insensitive; base58 formats (BTC legacy, TRX, SOL, LTC, XMR ...) are matched exactly. ethereum: / bitcoin: style URI prefixes are stripped.
Chain guess and checksum: EIP-55, base58check (BTC, LTC, DOGE, DASH, BTG, TRX, ZEC), bech32 / bech32m, cashaddr, XRP; Solana and Monero are recognised by format.

Honest limits

Only addresses OFAC publishes are matched. A clear result does not mean an address or its owner is unsanctioned: sanctions also cover persons and property that OFAC does not list by address, and funds can be one hop away.
No EU / UK / UN lists and no on-chain exposure analysis.
Inputs are looked up in memory and not stored or logged.

Routes

Route	Price
`GET\\|POST /v1/address`	$0.001	full screening result
`POST /v1/batch`	$0.01	up to 50 addresses
`GET\\|POST /v1/preview`	free, 10/min/IP	sanctioned true/false + chain guess
`POST /mcp`	free, 10/min/IP	remote MCP, `screen_address`
`GET /v1/list`, `/v1/stats`, `/health`	free	list date and counts, usage counters
`GET /openapi.json`, `/.well-known/x402`	free	discovery

x402 v2 (PAYMENT-SIGNATURE) and v1 (X-PAYMENT) clients both work; only HTTP 200 responses are settled.

Testnet payment routes (Solana devnet, Stellar testnet)

The same full screening result, paid on test networks. They are separate routes, so the Base mainnet terms above are unchanged. Both use the official x402 packages (@x402/svm, @x402/stellar) and the public, free x402.org facilitator, which pays the network fee. No real money moves.

Route	Network (CAIP-2)	Price	Pays to	Facilitator
`GET\\|POST /solana-devnet/v1/address`	`solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` (v1 name `solana-devnet`)	0.001 devnet USDC (`4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`, 1000 atomic)	`DmeY2NNcgbgSd2S7HTipepnCnFsfF6bhmBEms3ctknkq`	x402.org (fee payer `CKPKJWNdJEqa81x7CkZ14BVPiY6y16Sxs7owznqtWYp5`)
`GET\\|POST /stellar-testnet/v1/address`	`stellar:testnet`	0.01 XLM (native XLM Stellar Asset Contract `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC`, 100000 stroops)	`GD2I22CZ7K6BJR2JLN54LDM7TSXFSMTDWYFPJECWXZOHK3TFM6PEX44I`	x402.org (fees sponsored)

Base URL: https://api.youraitools.co/payguard (or https://payguard.agentgate.workers.dev). Both routes speak x402 v2 only (PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE).

# 402 terms (base64 JSON in the PAYMENT-REQUIRED header)
curl -si 'https://api.youraitools.co/payguard/solana-devnet/v1/address?address=0x098B716B8Aaf21512996dC57EB0615e2383E2f96'
curl -si 'https://api.youraitools.co/payguard/stellar-testnet/v1/address?address=0x098B716B8Aaf21512996dC57EB0615e2383E2f96'

# Pay and get the result (scripts in this repo, npm install first)
SOLANA_KEYPAIR=./devnet-payer.json node scripts/solana-devnet-pay.mjs      # needs devnet USDC (faucet.circle.com, Solana Devnet); no SOL needed
STELLAR_SECRET_FILE=./stellar-payer.txt node scripts/stellar-testnet-pay.mjs # file has a line secret=S...; fund the account with Friendbot

Client code (Stellar; Solana is the same with ExactSvmScheme from @x402/svm/exact/client and a @solana/kit signer):

import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
import { createEd25519Signer } from '@x402/stellar';
import { ExactStellarScheme } from '@x402/stellar/exact/client';

const signer = createEd25519Signer(process.env.STELLAR_SECRET, 'stellar:testnet');
const client = x402Client.fromConfig({
  schemes: [{ network: 'stellar:testnet', client: new ExactStellarScheme(signer) }],
  // XLM is not a default x402 asset, so opt in to it (cap 0.1 XLM per payment)
  spendControls: { allowedAssets: [{ network: 'stellar:testnet', asset: 'CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC', maxAmountPerPayment: '1000000' }] },
});
const pay = wrapFetchWithPayment(fetch, client);
const res = await pay('https://api.youraitools.co/payguard/stellar-testnet/v1/address?address=0x098B716B8Aaf21512996dC57EB0615e2383E2f96');
console.log(res.status, await res.json()); // 200, sanctioned: true (LAZARUS GROUP, DPRK3), payment.network "stellar:testnet"

Proven payments:

Stellar testnet, Oct 22 2026 02:07 UTC: HTTP 200 with the full result; settlement tx 311982af…09e0bc (ledger 5322251).
Solana devnet: proven. A live paid call settled through the x402.org facilitator and returned the full result (HTTP 200): devnet transaction.

Develop

npm install
npm test                    # engine (real bundled list), x402 v2 + v1, proxy, CDP facilitator switch, MCP, stdio free + paid mode
npm run build:lite          # regenerate src/data/sdn-lite.js (also runs on prepack)
npm run build:sdn           # rebuild the list from Treasury
node scripts/injectscan-listing.mjs   # listing text through InjectScan's rules
npx wrangler deploy

MIT licensed.

agentgate-source: code mirror on Cloudflare Pages. All repos