@ashlar-blue/x402-trust

Find an x402 facilitator, and decide whether to trust it before you pay.

Reference implementation of four proposed x402 and agent extensions:

• discovery (x402-foundation/x402 #2979) — find a facilitator from a domain name via DNS TXT + /.well-known/x402. No central directory, no list, no gatekeeper.
• attestations (#3000) — verify what a service claims about itself before paying it: TEE attestation blocks and soulbound, revocable, evidence-linked reputation records.
• switchboard & directory (Spec #04) — discover autonomous agents, inspect Intel TDX / AMD SEV hardware quotes, and route encrypted payloads gated by x402 micro-tolls.
• isda-cdm (IETF draft) — parse ISDA Common Domain Model derivatives/securities events and execute atomic DvP clearing across EVM and XRPL rails.

Discovery finds a service. Attestations tell you whether to trust it. The Switchboard lets agents discover and transact with each other.

Four verbs

An agent that spends money and trades has to do four things. This library does each in a handful of lines, with zero dependencies and — for the two verification verbs — zero network and zero trust in us.

import { checkService, Transcript, verifyReceipt, AshlarSwitchboard } from '@ashlar-blue/x402-trust';

// 1. BEFORE YOU PAY — resolve a service and get a plain decision + reasons.
const t = await checkService('facilitator.example');
if (!t.safeToPay) throw new Error(t.reasons.join('; '));   // e.g. off-domain resource, stale manifest

// 2. WHAT YOU PRODUCE — commit the work your agent did to a Merkle transcript.
const work = new Transcript()
  .add('inv-002', 'GET /price?asset=XRP', '{"price":"2.99"}');
const root    = work.root();      // sign or anchor this ONE value
const receipt = work.prove(0);    // hand a counterparty a proof of just their line

// 3. WHAT YOU'RE HANDED — verify a receipt offline, trusting no one.
verifyReceipt(receipt);           // true iff the work was in the committed set

// 4. WHO YOU TRANSACT WITH — discover attested agents and route encrypted messages.
const switchboard = new AshlarSwitchboard();
const oracles = switchboard.searchDirectory({ capability: 'market-oracle' });
const message = switchboard.routeMessage({
  from: 'did:x402:my-agent',
  to: oracles[0].did,
  topic: 'quote-request',
  ciphertext: '...',
  nonce: '12345',
  signature: '...',
});

checkService composes the hardened resolver (same-origin enforcement, SSRF/DoS guards, HTTPS-only redirects, live /supported cross-check) into one call, so you do not re-implement the adversarial edge cases. The verification functions are pure RFC 6962 Merkle math: if a proof verifies, the claim is true no matter who produced it — an enterprise does not have to trust the facilitator or operator to use the proofs.

Three more offline verifiers cover the artifacts the catalog and reconciler emit — verifyDirectoryEntry (one host in a census), verifyReconcileRow (one row of a two-observer reconciliation), and the signed-manifest / evidence grammar below.

Runnable tour: examples/demo.mjs — npm run build && node examples/demo.mjs. Produces work, verifies it, catches a tamper, and refuses a spoofed facilitator, all offline.

The rest of this document is the building blocks checkService sits on, for callers who want the lower-level surface.

Model Context Protocol (MCP) Server

Connect any autonomous AI coding agent (Claude Desktop, Cursor, Antigravity, VS Code, or custom AI agents) directly to the x402 trust and discovery mesh via standard MCP over stdio:

# Run standalone MCP server
npx @ashlar-blue/x402-trust mcp

Claude Desktop / Cursor MCP Configuration:

{
  "mcpServers": {
    "x402-trust": {
      "command": "npx",
      "args": ["-y", "@ashlar-blue/x402-trust", "mcp"],
      "env": {
        "X402_NETWORK": "coston2"
      }
    }
  }
}

Supported MCP Tools:

• x402_check_service: Resolves DNS TXT (_x402) and /.well-known/x402 to return a hardened safeToPay decision with full reasons.
• x402_verify_attestation_entry: Offline RFC 6962 Merkle verification of Intel TDX / AMD SEV TEE hardware quote measurements against a signed directory root.
• x402_verify_transcript_inclusion: Offline RFC 6962 Merkle verification of agent-to-agent session audit entries against a signed transcript root.
• x402_verify_reconcile_row: Offline verification of EIP-3009 / XRPL settlement reconciliation rows against a signed census root.
• x402_catalog_search: Filter and search the decentralized catalog of active x402 endpoints across discovery and bazaar-mirror lanes.
• x402_catalog_get: Retrieve complete provenance records and re-derivation recipes for any resource URL or hostname.
• x402_catalog_stats: Inspect network-wide node counts, active chains, and on-chain Coston2/Flare Merkle anchor hashes.
• x402_query_agent_directory: Query the attested agent directory by capability, model, or hardware attestation (Intel TDX / AMD SEV).
• x402_send_agent_message: Route an encrypted, micro-settled A2A message to an agent inbox with nonce anti-replay and x402 settlement.
• x402_fetch_agent_inbox: Fetch pending messages from an attested agent switchboard mailbox with FIFO ordering.

Zero dependencies

npm ls returns nothing. That is deliberate: a library whose job is "decide whether to trust a stranger before sending them money" cannot credibly arrive with a dependency tree you will never read. The entire trust path — DNS record parsing, manifest validation, redirect handling, the eth_call, the digest grammar — is auditable in one sitting.

The one consequence: we cannot compute keccak256 at runtime, so the badge function selector and well-known kind hashes are compile-time constants. They are asserted against ethers in the test suite, so they are verified, not trusted. You can pass your own hasher for any other kind.

Install

npm install @ashlar-blue/x402-trust

Find a facilitator from a domain name

import { resolveX402 } from '@ashlar-blue/x402-trust';

const r = await resolveX402('ashlar.blue');

r.via;              // 'dns-txt' — found via _x402.ashlar.blue
r.manifest.facilitator.baseUrl;
r.liveKinds;        // fetched from /supported — authoritative over the manifest
r.kindsMatchLive;   // false = the operator's manifest is stale
r.attestationUsable // false = treat any TEE claim as absent

Runs in Node out of the box. In a browser or a worker, inject a DNS resolver (DoH) and it works unchanged:

await resolveX402('ashlar.blue', { resolveTxt: myDohResolver, fetchImpl: fetch });

What it refuses to do

These are the extension's security rules, enforced rather than documented:

| Situation | Behaviour | |---|---| | wk in the TXT record points off-domain | hard error (spoofing signal) | | Manifest redirects off-domain | hard error — the in-domain rule is re-applied to every hop, so the check runs on where the bytes came from, not where you asked | | facilitator.baseUrl is off-domain | hard error — otherwise any domain could claim someone else's facilitator, and point every crawler at them | | TEE block whose verifier is not a dereferenceable HTTPS URL | attestationUsable: false — an unverifiable claim must not read as a verified one |

Decide whether to trust it

The important part, and the part most callers get wrong:

import { checkOperatorTrust } from '@ashlar-blue/x402-trust';

const trust = await checkOperatorTrust({
  manifest: r.manifest,
  rpcUrl:   'https://coston2-api.flare.network/ext/C/rpc',
  registry: '0xb02f83e994830C4954c89C10482665A3963229c5',  // PIN THIS
  subject:  r.manifest.badges.subject,
  kind:     'x402-facilitator-attested',
});

trust.verified;         // was this operator ever verified?      (registry)
trust.liveAttestation;  // is it in that mode right now?          (manifest)
trust.attestedNow;      // both — this is what you gate on

Why these are three values and not one

A registry record is soulbound, therefore durable. TEE attestation is transient. Point the first at the second and you get a claim that is true when written and silently false later, with nothing in the record to reveal the drift.

We shipped exactly that bug. Our own x402-facilitator-attested record read active on-chain while our own manifest honestly reported attestation: none, because the enclave was down. The record was not lying about what it attested — a verification really did happen, and its evidence still hashes — it was being read as a liveness signal it cannot carry.

So:

| Question | Source of truth | |---|---| | Was this operator verified, by whom, against what evidence? | the registry record (durable, revocable) | | Is it operating that way right now? | the operator's live manifest (self-degrading) |

checkOperatorTrust keeps them apart and only combines them explicitly. It fails closed: anything it cannot establish yields attestedNow: false.

hasActiveBadge likewise throws rather than returning false when it cannot reach the chain. "I could not check" and "I checked and it is not active" are different answers, and collapsing them is how an RPC outage becomes a silent trust upgrade.

Drop into the official SDK (@x402/core, Stripe Machine Payments)

Every integration built from the Stripe Machine Payments sample (and most others built on @x402/core) hardcodes its facilitator:

import { facilitator } from "@coinbase/x402";           // ← a constant
const client = new HTTPFacilitatorClient(facilitator);

discoverFacilitator() turns that constant into a resolved, verified choice — one line changes:

import { HTTPFacilitatorClient } from "@x402/core/server";
import { discoverFacilitator } from "@ashlar-blue/x402-trust";

const { config, resolution } = await discoverFacilitator("facilitator.example.com", {
  scheme: "exact",
  network: "eip155:8453",     // require support, judged against the LIVE /supported
});
const client = new HTTPFacilitatorClient(config);        // drop-in

resolution.attestationUsable; // and you know whether its TEE claim is checkable

No dependency on @x402/core is taken — the returned config is a plain { url, timeoutMs? } matching core's FacilitatorConfig shape, so your SDK version is the only SDK version involved.

One honest constraint: HTTPFacilitatorClient calls the fixed paths /verify, /settle, /supported. A discovered manifest declaring different endpoint paths cannot be expressed as a FacilitatorConfig, so discoverFacilitator() fails at resolve time (reason: "endpoints") instead of handing you a config that 404s at pay time.

Evidence references

Records point at the evidence that justified them. A bare URI has the trust model of brand reputation — it can be edited or taken down after the fact — so records carry a digest:

import { encodeEvidenceRef, parseEvidenceRef, sameEvidence, canonicalJson } from '@ashlar-blue/x402-trust';

const ref = encodeEvidenceRef({
  alg: 'sha256',
  hex: '...',
  ref: 'https://api.ashlar.blue/evidence/<digest>.json',
});
// "x402ev/1; digest=sha256:...; ref=https://..."

Verify one by fetching the artifact, canonicalizing it (RFC 8785 JCS), hashing, and comparing to the digest. A fetched artifact that mismatches its digest is evidence-invalid and must be a hard negative; an artifact that is merely unreachable should down-weight the record, not revoke it. Link rot and tampering are different failures.

ISDA Common Domain Model (CDM) & Securities Bridge

Parse institutional derivatives and securities lifecycle events (Variation Margin, Bond Coupons, Swap Settlements, Equity DvP) directly into conformant x402 HTTP 402 payment challenges and deterministic SCITT accounting statements with SHA-256 pre-image binding:

import {
  parseIsdaCdmEvent,
  buildIsdaX402Challenge,
  buildIsdaScittStatement,
  verifyIsdaSettlement
} from '@ashlar-blue/x402-trust';

// 1. Parse and validate an incoming ISDA trade lifecycle event
const event = parseIsdaCdmEvent(rawPayload);

// 2. Generate an x402 HTTP 402 payment challenge for RLUSD / XRPL / Flare
const challenge = buildIsdaX402Challenge(event, {
  facilityUrl: 'https://api.ashlar.blue/settle/isda',
  payToAddress: '0x2222222222222222222222222222222222222222',
  assetNetwork: 'xrpl:mainnet'
});

// 3. Emit a canonical SCITT accounting statement bound to the event
const statement = buildIsdaScittStatement(event);

// 4. Verify on-chain settlement receipt against the accounting statement
const verdict = verifyIsdaSettlement(statement, onchainReceipt);
if (!verdict.valid) throw new Error(verdict.error);

Attested Agent Switchboard & Capability Directory

Discover autonomous agents, inspect hardware attestation quotes (Intel TDX / AMD SEV), and route end-to-end encrypted payloads with anti-replay protection and x402 micro-tolls:

import { AshlarSwitchboard } from '@ashlar-blue/x402-trust';

const switchboard = new AshlarSwitchboard();

// 1. Query directory by capability, model, or hardware attestation
const agents = switchboard.searchDirectory({ capability: 'llm-inference' });

// 2. Route an E2E encrypted message to an agent's mailbox
const envelope = switchboard.routeMessage({
  from: 'did:x402:client-agent',
  to: agents[0].did,
  topic: 'task-request',
  ciphertext: 'encrypted_payload_hex...',
  nonce: 'unique_nonce_123',
  signature: 'sender_ed25519_signature...',
  x402Voucher: {
    amountUSD: '0.001',
    rail: 'eip155:8453',
    payer: '0x1111111111111111111111111111111111111111',
    signature: 'voucher_signature...',
  },
});

// 3. Recipient drains pending envelopes from their FIFO inbox
const inbox = switchboard.fetchInbox(agents[0].did);

// 4. Acknowledge and purge processed messages
switchboard.acknowledgeMessages(agents[0].did, [envelope.id]);

Status

0.5.5. Zero-dependency institutional trust, discovery, and A2A switchboard layer for autonomous AI agents and institutional clearing. Published on npm as @ashlar-blue/x402-trust. Requires Node ≥20.

MIT.