@glideco/x402-facilitator

x402 facilitator protocol shapes and a composable screening pipeline. Pure functions; settlement IO is injected by apps/web.

x402 facilitator protocol layer with Chainalysis-backed compliance screening. x402 facilitators verify off-chain payment payloads and settle them on-chain. The pipeline composes address screening, MCC screening and idempotent settlement. Screening coverage depends on the configured provider and its contract; the protocol package does not itself provide a regulated service.

This package is the protocol shape and orchestration layer: VerifyRequest, VerifyResponse, SettleRequest, SettleResponse, and the compliance-pipeline composer. Actual on-chain RPC calls, Chainalysis API invocations, and audit-event writes live in apps/web. The HTTP endpoints are mounted from app/api/x402/facilitator/{verify,settle}/route.ts.

F1 IRON RULE: The facilitator’s SettleResponse.txHash is the facilitator’s claim, not verified fact. Operators MUST independently RPC-verify the on-chain transaction before persisting it to any audit row. This package surfaces the facilitator’s response verbatim and leaves the verification step to the consumer. The reference implementation is the serverFetchChainTx dependency in the MCP x402.pay tool.

Install

npm install @glideco/x402-facilitator

npmjs.com/package/@glideco/x402-facilitator

Two-phase protocol

x402 uses a verify-then-settle protocol:

1. /verify — facilitator validates the off-chain EIP-712 payment payload and runs the compliance pipeline. Returns {isValid, invalidReason} without touching chain state.
2. /settle — facilitator broadcasts the on-chain transaction after a TOCTOU re-verify pass. Returns {success, txHash, network}.

The handleVerify and handleSettle orchestrators implement this contract. Settlement uses a store-before-broadcast pattern: a pending sentinel is written before invoking broadcast so a process kill mid-broadcast does not re-broadcast on replay.

API surface

Export	Description
handleVerify(rawRequest, deps)	Parse + validate payload, run compliance pipeline, return VerifyResponse.
handleSettle(rawRequest, deps)	Re-verify (TOCTOU defense), store sentinel, broadcast, store terminal state.
runCompliancePipeline(args, screener)	Compose sanctions + MCC + cap screening. Short-circuits on first block.
deriveIdempotencyCacheKey(args)	Content-bound cache key: ${idempotencyKey}:${sha256(payTo|network|payload)}.
FACILITATOR_MAX_BODY_BYTES	4 MB — request size limit to bound CPU + memory.
X402_FACILITATOR_VERSION	'2.0' — version echoed in X-X402-Version response header.

Wiring the /verify route

// apps/web/src/app/api/x402/facilitator/verify/route.ts
import {
  handleVerify,
  FACILITATOR_MAX_BODY_BYTES,
  X402_VERSION_HEADER,
  X402_FACILITATOR_VERSION,
} from '@glideco/x402-facilitator';
import { chainalysisScreener } from '@/server/lib/screeners';

export async function POST(req: Request) {
  if (Number(req.headers.get('content-length') ?? 0) > FACILITATOR_MAX_BODY_BYTES) {
    return new Response(null, { status: 413 });
  }
  const body = await req.json();
  const result = await handleVerify(body, {
    async decodePayload({ payload, network }) {
      // Validate EIP-712 signature, check expiry + replay
      return eip712Decoder.decode(payload, network);
    },
    screener: chainalysisScreener,
  });

  return Response.json(result, {
    headers: { [X402_VERSION_HEADER]: X402_FACILITATOR_VERSION },
  });
}

Compliance pipeline

The pipeline is composable — each screener returns 'allow' | 'block' | 'review'. The first non-allow result short-circuits; 'review' is treated as block (conservative posture).

import { runCompliancePipeline, type ComplianceScreener } from '@glideco/x402-facilitator';

const screener: ComplianceScreener = {
  async screenSanctions({ payerAddress, payeeAddress, network, asset, amount }) {
    const verdict = await chainalysis.screenAddress(payerAddress);
    return {
      verdict: verdict.risk === 'high' ? 'block' : 'allow',
      reason: verdict.reason ?? 'ok',
      provider: 'chainalysis',
      screeningId: verdict.screeningId,
    };
  },
  async screenMcc({ mcc, payeeAddress }) {
    return mccEngine.check({ mcc, payeeAddress });
  },
};

const result = await runCompliancePipeline({
  payerAddress: '0xPayer…',
  payeeAddress: '0xMerchant…',
  network: 'base',
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  amount: '1000000',
}, screener);

if (result.verdict !== 'allow') {
  console.log('Blocked by:', result.blockingResult);
}

Idempotency defense

The cache key is content-bound to defend against cross-tenant cache poisoning. An attacker who guesses a victim’s idempotency key also needs to match the exact (payTo, network, paymentPayload) triple:

import { deriveIdempotencyCacheKey } from '@glideco/x402-facilitator';

const cacheKey = deriveIdempotencyCacheKey({
  idempotencyKey: request.idempotencyKey,
  payTo: request.paymentRequirements.payTo,
  network: request.paymentRequirements.network,
  paymentPayload: request.paymentPayload,
});
// → 'user-supplied-key:a3f8b2c1…' (SHA-256 prefix of content triple)

Verify response invalidReason vocabulary

Reason	Cause
insufficient_funds	Payload amount exceeds on-chain balance.
invalid_signature	EIP-712 signature verification failed.
expired	Payment payload past validBefore.
replayed	Nonce already consumed.
sanctions_block	Payer or payee matched an OFAC / sanctions entry.
mcc_blocked	Merchant category code on the deny list.
amount_exceeds_policy_cap	Amount exceeds the policy-engine cap for this agent.
velocity_exceeded	Per-period transaction velocity cap hit.

Reading list

• Money-safety contracts — the F-rules, including F1 (server-side RPC verify) that governs txHash handling.
• @repo/connectors-coinbase-x402 (workspace-internal — wraps @glideco/x402-facilitator with Coinbase CDP integration) — Coinbase CDP integration that wraps this facilitator for receiver-side flows.
• Source on GitHub