@clearagent/x402

KYA (Know Your Agent) compliance screening for x402 payments.

OFAC sanctions screening, spend policy enforcement, and behavioral monitoring for autonomous AI agent transactions — as a single x402 hook.

npm install @clearagent/x402

→ npm · API Docs · clearagent.dev

Quick Start

Add one line to your x402 server to require KYA compliance on every payment:

import { x402ResourceServer, x402HTTPResourceServer } from "@x402/core/server";
import { paymentMiddlewareFromHTTPServer } from "@x402/express";
import { kyaComplianceHook } from "@clearagent/x402";

const resourceServer = new x402ResourceServer(facilitatorClient)
  .register(NETWORK, evmScheme);

const httpServer = new x402HTTPResourceServer(resourceServer, routes)
  .onProtectedRequest(kyaComplianceHook({           // ← this line
    apiKey: process.env.CLEARAGENT_API_KEY,
  }));

app.use(paymentMiddlewareFromHTTPServer(httpServer));

That's it. Every payment request is now screened against 25 compliance rules in <50ms before x402 processes the payment.

What It Does

When an AI agent sends a payment request to your x402-protected endpoint:

1. The hook extracts the X-KYA-Token header from the request
2. Calls api.clearagent.dev/v1/screen with the token + transaction context
3. Gates access based on the verdict:

| Verdict | What happened | Default behavior | |---------|--------------|-----------------| | CLEAR | All 25 rules passed | Continue to x402 payment | | BLOCK | OFAC hit, revoked credential, or hard policy violation | Abort request | | REVIEW | Soft flag: spend limit, model change, velocity anomaly | Abort (configurable) | | UNKNOWN | No KYA credential presented | Abort (configurable) |

What Gets Screened

The KYA engine runs 25 rules in precedence order on every request:

• OFAC sanctions — operator wallet + legal name checked against live SDN list (synced nightly)
• Counterparty screening — recipient wallet + name independently screened
• Credential validity — ACTIVE/REVOKED/EXPIRED/SUSPENDED status check
• Spend policy — per-transaction limit, daily rolling limit, allowed chains, protocol restrictions
• Behavioral flags — velocity spikes, unusual operating hours
• Ownership transfer — credential invalidated if operator changes
• Model change — flags if the underlying AI model changed since issuance

Configuration

kyaComplianceHook({
  // Required
  apiKey: "your-clearagent-api-key",

  // Optional
  apiUrl: "https://api.clearagent.dev",  // default
  tokenHeader: "X-KYA-Token",            // default
  timeoutMs: 5000,                       // default

  // Verdict handling
  onUnknown: "block",   // "block" | "allow" | "review"
  onReview: "block",    // "block" | "allow"

  // Callbacks
  onScreen: (result, ctx) => {
    console.log(`[KYA] ${result.verdict} on ${ctx.method} ${ctx.path}`);
  },
  onError: (error, ctx) => {
    console.error(`[KYA] API unreachable: ${error.message}`);
    return false;  // fail-closed (default). Return true to fail-open.
  },
})

Environment Variable Shorthand

import { kyaComplianceHookFromEnv } from "@clearagent/x402";

// Reads CLEARAGENT_API_KEY and CLEARAGENT_API_URL from process.env
httpServer.onProtectedRequest(kyaComplianceHookFromEnv());

How Agents Include Their Token

AI agents include their KYA credential as an HTTP header alongside the x402 payment:

GET /api/data HTTP/1.1
X-KYA-Token: eyJhbGciOiJFUzI1NiIs...
PAYMENT-SIGNATURE: <x402 payment payload>

Agents register and receive their KYA token via:

curl -X POST https://api.clearagent.dev/v1/agents/register \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "my-agent",
    "operatorLegalName": "Acme AI Inc.",
    "operatorWallet": "0x...",
    "spendPolicy": { "maxSingleTxUSDC": 500, "dailyLimitUSDC": 5000 }
  }'

Review Dispositions

When a payment is held for REVIEW, a BSA officer can post their decision:

curl -X POST https://api.clearagent.dev/v1/reviews/txn_abc123 \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"disposition": "APPROVED", "reviewedBy": "J. Smith"}'

Dispositions: APPROVED | REJECTED | ESCALATE_SAR

Full API

The ClearAgent KYA API at api.clearagent.dev provides:

| Endpoint | Description | |----------|-------------| | POST /v1/agents/register | Issue a KYA credential (W3C VC as JWT) | | POST /v1/screen | Screen a transaction (25-rule engine, <50ms) | | POST /v1/reviews/:txnId | BSA officer disposition | | GET /v1/audit/:txnId | Retrieve audit record | | GET /v1/health | Health check | | GET /v1/.well-known/jwks.json | Public key for JWT verification |

License

MIT