@fretumai/facilitator

Drop-in Fretum facilitator for x402. Wraps Coinbase CDP's mainnet facilitator with OFAC + geo-block compliance hooks at the verify phase.

Installed as @fretumai/facilitator — imports are from '@fretumai/facilitator'.

Install

npm install @fretumai/facilitator @fretumai/express

Quick Start

import { paymentMiddleware } from "@fretumai/express";
import { facilitator } from "@fretumai/facilitator";

app.use(paymentMiddleware(
  "0xYourMerchantAddress",
  {
    "POST /my-endpoint": {
      price: "$1.00",
      network: "base",
      config: { name: "My Service", description: "...", discoverable: true },
    },
  },
  { facilitator }
));

What Fretum adds over CDP's base facilitator

1. OFAC wallet screening — Every paying wallet is checked against the Treasury SDN list before settlement. Sanctioned addresses are blocked with isValid: false.
2. Geo-block — Requests from sanctioned jurisdictions (per Fretum's compliance feed) are rejected before CDP ever sees them.
3. Graceful degradation — Compliance API outages default to allow so you don't hard-fail on our downtime. Opt into fail-closed behavior by providing your own complianceCheck.

Configuration

Environment:

FRETUM_API_BASE   default: https://api.fretum.ai
FRETUM_API_KEY    optional — required for higher rate limits

Or build a custom facilitator:

import { createFacilitator } from "@fretumai/facilitator";

const facilitator = createFacilitator({
  complianceMode: "strict", // "strict" | "advisory" | "off"
  complianceCheck: async ({ walletAddress, clientIp }) => {
    // your own OFAC feed / allowlist
    return { allow: true };
  },
});

Compliance modes

• strict (default) — block payments that fail OFAC / geo checks
• advisory — log failures, allow settlement (for testing)
• off — skip compliance entirely (dev only — never ship this to mainnet)

License

MIT — Cameron Fagan / MCF Agentic