x402-trust-layer 5.1.0

package/public/llms.txt

@@ -0,0 +1,132 @@
+# x402 Trust Layer
+
+> 58 paid x402 trust infrastructure APIs for AI agent fleets. Guard, attest, comply and audit every payment — before the money moves.
+
+- Website: https://x402trustlayer.xyz
+- OpenAPI: https://x402trustlayer.xyz/openapi.json
+- Discovery: https://x402trustlayer.xyz/.well-known/x402
+- Skill (agents): https://x402trustlayer.xyz/skill.md
+- Full context: https://x402trustlayer.xyz/llms-full.txt
+- MCP: npx @mimranakb/trust-layer-mcp@1.2.0 (trust_before_x402_fetch, trust_mandate_diff, trust_semantic_settle)
+- npm: x402-agent-suite-preflight
+- GitHub: https://github.com/mimranchohan/x402-trust-layer
+
+## Default buyer flow (3 steps)
+
+1. POST /api/x402/proxy — preflight ($0.08)
+2. x402_check → x402_fetch on external marketplace URL
+3. POST /api/receipt-auditor/verify — settlement proof ($0.05)
+
+## Primary entry points
+
+| Method | Path | Price | Purpose |
+|--------|------|-------|---------|
+
+
+## Tier-1 enterprise
+
+| Method | Path | Price | Purpose |
+|--------|------|-------|---------|
+| POST | /api/merchant-trust/score | $0.06 | Know-Your-Merchant trust score with wash-trading and verification signals. |
+| POST | /api/mandate/compile | $0.08 | Compiles AP2-style signed payment mandate from human intent and guardrails. |
+| POST | /api/mandate/verify | $0.02 | Verifies mandate signature and scopes a proposed payment against it. |
+| POST | /api/rail-optimizer/route | $0.04 | Picks best rail: Visa CLI, Stripe MPP, Circle, Base x402 or Solana x402. |
+| POST | /api/compliance/ledger | $0.12 | SOC2/tax-ready spend reconciliation with policy flags and tamper hash. |
+| POST | /api/dispute/resolve | $0.10 | Visa chargeback dossier or on-chain refund claim builder. |
+| POST | /api/quality-escrow/settle | $0.10 | Quality-gated escrow — release on pass, auto-refund on response mismatch. |
+| POST | /api/quality-escrow/semantic-settle | $0.12 | Schema + intent rubric escrow with optional LLM judge and auto bond slash. |
+| POST | /api/mandate/diff | $0.04 | Compare signed mandate scope to MCP tool trace before payment. |
+| POST | /api/merchant-trust/certify | $0.15 | Certify seller with KYM pass, badge, buyer policy, optional virtual bond. |
+| POST | /api/trust-network/buyer-gate | $0.03 | Verify buyer attestation and tier against certified seller policy. |
+| POST | /api/pipeline/trust-v2 | $0.35 | One-shot: mandate diff + KYM ingest + guard + certified buyer gate. |
+| POST | /api/trust-network/bond/slash | $0.03 | Slash certified seller virtual bond after failed delivery. |
+
+## All 58 paid routes
+
+| Method | Path | Price | Summary |
+|--------|------|-------|---------|
+| POST | /api/a2a/execute | $0.10 | Agent-to-agent x402 orchestration: trust preflight then paid call to seller endpoint |
+| POST | /api/bedrock/preflight | $0.05 | AWS Bedrock / enterprise agent preflight: guard, mandate, and trust bundle before x402 pay |
+| POST | /api/market/buy-advisor | $0.08 | Jupiter-style buy quote — ranks paid APIs for an intent with policy and MPP advice. |
+| POST | /api/seller/audition-coach | $0.06 | Pre-listing QA: audits OpenAPI, discovery manifests and 402 probes. |
+| POST | /api/x402/proxy | $0.08 | All-in-one preflight before any external x402 payment — policy, identity, risk, security grade and optional attestation. |
+| POST | /api/mpp/session | $0.03 | MPP session lifecycle: open, voucher, close — batch settlement on Base/Solana. |
+| POST | /api/attestation/issue | $0.04 | Issues HMAC-signed preflight attestation for partner agent networks. |
+| POST | /api/attestation/verify | $0.02 | Verifies attestation signature, expiry and registry lookup. |
+| GET | /api/attestation/registry | $0.02 | Query trust registry of valid agent attestations. |
+| POST | /api/guard/pre-x402 | $0.05 | Spend governor + identity gate + risk gate in one lightweight call. |
+| POST | /api/agent/verify | $0.04 | ERC-8004 TrustScore on Base mainnet — registration, reputation, wallet binding, agent card, domain. |
+| POST | /api/pipeline/execute | $0.25 | One-shot orchestration: guard, NL plan, facilitator routing and marketplace pick. |
+| POST | /api/payment-intent/compile | $0.15 | Compiles natural-language task + budget into a multi-step x402 execution plan. |
+| POST | /api/facilitator/failover | $0.05 | Ranks x402 facilitators and recommends a healthy failover route. |
+| POST | /api/mpp/session-plan | $0.02 | Estimates MPP batch session savings vs per-call settlement. |
+| POST | /api/spend-governor/check | $0.03 | Enforces per-call and daily USDC spend caps per agent. |
+| POST | /api/identity-gate/check | $0.05 | Wallet identity tier and risk scoring before paid calls. |
+| POST | /api/risk-gate/scan | $0.08 | Probes URL safety, HTTPS and x402 payment requirements. |
+| POST | /api/router/route | $0.02 | Routes capability queries to the best verified x402 marketplace API. |
+| POST | /api/research/brief | $0.20 | Builds a paid-API research pipeline and cost estimate for any topic. |
+| POST | /api/receipt-auditor/verify | $0.05 | Verifies x402 settlement receipts and on-chain transaction alignment. |
+| POST | /api/refund-arbiter/evaluate | $0.08 | Evaluates buyer refund eligibility from verification signals. |
+| POST | /api/budget-allocator/run | $0.03 | Allocates shared USDC pool across agent fleet by priority. |
+| POST | /api/settlement-graph/next | $0.02 | Recommends next paid APIs to call after a settlement receipt. |
+| POST | /api/quality-monitor/probe | $0.03 | Regression-probes up to 10 x402 endpoints and returns quality scores. |
+| POST | /api/evidence-locker/export | $0.10 | Exports tamper-evident compliance bundles for x402 settlements. |
+| POST | /api/agent-escrow | $0.12 | Create, status or release agent-to-agent USDC escrow records. |
+| POST | /api/merchant-trust/score | $0.06 | Know-Your-Merchant trust score with wash-trading and verification signals. |
+| POST | /api/mandate/compile | $0.08 | Compiles AP2-style signed payment mandate from human intent and guardrails. |
+| POST | /api/mandate/verify | $0.02 | Verifies mandate signature and scopes a proposed payment against it. |
+| POST | /api/rail-optimizer/route | $0.04 | Picks best rail: Visa CLI, Stripe MPP, Circle, Base x402 or Solana x402. |
+| POST | /api/compliance/ledger | $0.12 | SOC2/tax-ready spend reconciliation with policy flags and tamper hash. |
+| POST | /api/dispute/resolve | $0.10 | Visa chargeback dossier or on-chain refund claim builder. |
+| POST | /api/quality-escrow/settle | $0.10 | Quality-gated escrow — release on pass, auto-refund on response mismatch. |
+| POST | /api/quality-escrow/semantic-settle | $0.12 | Schema + intent rubric escrow with optional LLM judge and auto bond slash. |
+| POST | /api/mandate/diff | $0.04 | Compare signed mandate scope to MCP tool trace before payment. |
+| POST | /api/merchant-trust/certify | $0.15 | Certify seller with KYM pass, badge, buyer policy, optional virtual bond. |
+| POST | /api/trust-network/buyer-gate | $0.03 | Verify buyer attestation and tier against certified seller policy. |
+| POST | /api/pipeline/trust-v2 | $0.35 | One-shot: mandate diff + KYM ingest + guard + certified buyer gate. |
+| POST | /api/trust-network/bond/slash | $0.03 | Slash certified seller virtual bond after failed delivery. |
+| POST | /api/protocol/pipeline/full-trust | $0.45 | Agent Trust Protocol v4 full pipeline before x402 payment |
+| POST | /api/protocol/passport/issue | $0.06 | Issue Agent Passport DID verifiable credential |
+| POST | /api/protocol/passport/verify | $0.02 | Verify Agent Passport credential signature |
+| POST | /api/protocol/trust-score/v2 | $0.08 | TrustScore v2 with tamper-resistant HMAC proof |
+| POST | /api/protocol/fraud/scan | $0.10 | Graph fraud scan for Sybil and wash trading |
+| POST | /api/protocol/oracle/consensus | $0.12 | Trust oracle quorum consensus |
+| POST | /api/protocol/execution/issue | $0.05 | Proof of Execution task receipt |
+| POST | /api/protocol/execution/verify | $0.03 | Verify Proof of Execution receipt |
+| POST | /api/protocol/reasoning/commit | $0.08 | Commit reasoning audit Merkle tree |
+| POST | /api/protocol/reasoning/disclose | $0.04 | Selective disclosure of reasoning audit leaves |
+| POST | /api/protocol/escrow/create | $0.08 | Create escrow FSM (CREATED) |
+| POST | /api/protocol/escrow/transition | $0.06 | Transition escrow FSM state |
+| POST | /api/protocol/escrow/status | $0.02 | Query escrow FSM status |
+| POST | /api/protocol/replay/bind | $0.02 | Replay-safe payment binding |
+| POST | /api/protocol/replay/verify | $0.02 | Verify and consume replay binding |
+| POST | /api/protocol/zk/prove | $0.15 | ZK-style proof of budget, reputation, or compliance |
+| POST | /api/protocol/credit/score | $0.06 | AI Agent Credit Bureau 300-900 |
+| POST | /api/protocol/compliance/assess | $0.10 | Enterprise AML/KYC compliance assess |
+
+## Free endpoints (no x402 payment)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | /health | Monitoring |
+| GET | /.well-known/x402 | Paid URL catalog |
+| GET | /llms.txt | AI index (this file) |
+| GET | /skill.md | Agent skill file |
+| GET | /api/agentic/validate-urls | Agentic Market URL list |
+| POST | /api/webhooks/register | Fleet webhook registration (beta) |
+| GET | /api/agent/lookup/:wallet | Free ERC-8004 TrustScore lookup (30/hr/IP) |
+| GET | /api/merchant-trust/certified/:host | Certified seller badge lookup |
+| GET | /api/trust-network/catalog | Certified sellers catalog |
+| GET | /api/webhooks/list | List webhooks |
+
+## Networks
+
+Mainnet: Base (eip155:8453), Solana, Polygon (eip155:137) — USDC via Dexter or CDP facilitator.
+Testnet: set X402_TESTNET=1 → Base Sepolia + Solana Devnet via https://x402.org/facilitator
+
+## Agentic Wallet integration
+
+Coinbase Agentic Wallet MCP pays for x402 services. Call Trust Layer guard BEFORE payments-mcp pays:
+POST /api/guard/pre-x402 → then Agentic Wallet discovers and pays downstream.
+
+See: docs/AGENTIC-WALLET.md

package/public/skill.md

@@ -0,0 +1,135 @@
+# x402 Trust Layer Skill
+
+## Product Summary
+
+x402 Trust Layer is the **control plane** between AI agents and the open x402 marketplace. 58 paid HTTP APIs decide whether to pay, whom to trust, which rail to use, and how to audit or dispute settlements. No API keys — USDC micropayments on Base, Solana, and Polygon.
+
+- **Base URL:** https://x402trustlayer.xyz
+- **OpenAPI:** https://x402trustlayer.xyz/openapi.json
+- **Discovery:** https://x402trustlayer.xyz/.well-known/x402
+- **Install skill:** `npx skills add https://x402trustlayer.xyz`
+
+## When to Use
+
+- Before any external `x402_fetch` to an unknown marketplace host
+- Fleet spend policy enforcement (daily/per-call caps)
+- Know-Your-Merchant trust scoring before payment
+- AP2-style signed payment mandates for enterprise agents
+- Receipt verification and SOC2/CFO compliance ledgers
+- Disputes, quality escrow, cross-rail routing (Visa CLI, MPP, USDC)
+- With **Coinbase Agentic Wallet MCP** — always preflight first
+
+## Quick Reference
+
+### Default 3-step buyer flow
+
+```text
+1. POST /api/x402/proxy          ($0.08) — preflight
+2. x402_check → x402_fetch       (external API)
+3. POST /api/receipt-auditor/verify ($0.05) — proof
+```
+
+### Primary entry points
+
+| Path | Price | Use when |
+|------|-------|----------|
+| POST /api/x402/proxy | $0.08 | Default all-in-one preflight |
+| POST /api/guard/pre-x402 | $0.05 | Lightweight allow/deny |
+| POST /api/pipeline/execute | $0.25 | NL task + marketplace routing |
+
+### Tier-1 enterprise
+
+| Path | Price | Purpose |
+|------|-------|----------|
+| POST /api/merchant-trust/score | $0.06 | KYM trust — pay/caution/avoid |
+| POST /api/mandate/compile | $0.08 | Signed AP2 payment mandate |
+| POST /api/mandate/verify | $0.02 | Verify payment within mandate |
+| POST /api/rail-optimizer/route | $0.04 | Visa CLI vs MPP vs Base/Solana |
+| POST /api/compliance/ledger | $0.12 | CFO/SOC2 reconciliation |
+| POST /api/dispute/resolve | $0.10 | Chargeback dossier / refund claim |
+| POST /api/quality-escrow/settle | $0.10 | Pay-on-delivery + auto-refund |
+| POST /api/agent/verify | $0.04 | ERC-8004 TrustScore (Base mainnet) |
+
+## ERC-8004 Agent Verify
+
+```text
+POST /api/agent/verify  { walletAddress, agentId?, chain? }  → trustScore, tier, breakdown
+GET  /api/agent/lookup/:wallet?agentId=1                     → free (30/hr/IP)
+```
+
+Tiers: PLATINUM ≥85 | GOLD ≥70 | SILVER ≥50 | BRONZE ≥30 | UNVERIFIED <30
+
+Pair with guard: `POST /api/guard/pre-x402` + `minAgentTier: "SILVER"`
+
+1. `POST /api/mandate/compile` — human intent → signed scope
+2. `POST /api/merchant-trust/score` — KYM on target host
+3. `POST /api/rail-optimizer/route` — pick best payment rail
+4. `POST /api/x402/proxy` — preflight (spend + identity + risk)
+5. External `x402_fetch` on marketplace URL
+6. `POST /api/quality-escrow/settle` — verify response quality
+7. `POST /api/receipt-auditor/verify` — on-chain proof
+8. `POST /api/compliance/ledger` — audit record
+
+## Agentic Wallet MCP integration
+
+Coinbase `npx @coinbase/payments-mcp` gives agents wallet + x402 pay. **Always call Trust Layer first:**
+
+```text
+User task → POST /api/guard/pre-x402 (Trust Layer)
+         → if allowed: Agentic Wallet MCP discovers + pays external API
+         → POST /api/receipt-auditor/verify (Trust Layer)
+```
+
+Spend limits: configure in Agentic Wallet UI; enforce policy in Trust Layer `policy` object.
+
+## Alchemy Agentic Gateway (x402.alchemy.com)
+
+```text
+1. trust_alchemy_preflight OR POST /api/guard/pre-x402 (allowedHosts: ["x402.alchemy.com"])
+2. Pay via @alchemy/x402 (USDC on Base)
+3. trust_receipt_verify from PAYMENT-RESPONSE tx hash
+4. (enterprise) POST /api/compliance/ledger
+```
+
+Demo: `npm run demo:alchemy` (~$1.10) | `npm run demo:alchemy:enterprise` (~$1.32)  
+Alchemy skill: `npx skills add alchemyplatform/skills --yes`
+
+## MCP tools (@mimranakb/trust-layer-mcp v1.2.0)
+
+| Tool | Maps to |
+|------|---------|
+| trust_agent_verify | POST /api/agent/verify |
+| trust_alchemy_preflight | POST /api/guard/pre-x402 (Alchemy preset) |
+| trust_preflight_proxy | POST /api/x402/proxy |
+| trust_guard_preflight | POST /api/guard/pre-x402 |
+| trust_merchant_score | POST /api/merchant-trust/score |
+| trust_mandate_verify | POST /api/mandate/verify |
+| trust_receipt_verify | POST /api/receipt-auditor/verify |
+
+Setup: `EVM_PRIVATE_KEY` or `SOLANA_PRIVATE_KEY` in env. Run: `npx @mimranakb/trust-layer-mcp@1.2.0`
+
+## npm helper
+
+```bash
+npm install x402-agent-suite-preflight @dexterai/x402
+```
+
+## Idempotency
+
+Paid POST retries: send `Idempotency-Key: <uuid>` with the same body after payment.
+
+## Webhooks (beta)
+
+`POST /api/webhooks/register` with fleetId, url, events[].
+
+## Common Gotchas
+
+- Unpaid POST → HTTP 402. Retry with Payment-Signature after USDC settles.
+- Testnet: `X402_TESTNET=1` + x402.org facilitator.
+- Production requires `ATTESTATION_HMAC_SECRET` (32+ chars).
+
+## Resources
+
+- Full catalog: https://x402trustlayer.xyz/llms-full.txt
+- Integration: docs/INTEGRATE.md on GitHub
+- Agentic Wallet: docs/AGENTIC-WALLET.md on GitHub

package/railway.toml

@@ -0,0 +1,9 @@
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "Dockerfile"
+
+[deploy]
+healthcheckPath = "/health"
+healthcheckTimeout = 120
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 5

package/scripts/docker-entrypoint.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+set -e
+DATA="${DATA_DIR:-/app/data}"
+mkdir -p "$DATA"
+# Railway volumes mount as root; app user needs write access for SQLite
+chown -R app:app "$DATA" 2>/dev/null || true
+exec su-exec app:app "$@"

package/scripts/patch-facilitator-timeout.mjs

@@ -0,0 +1,61 @@
+/**
+ * Dexter facilitator /settle: raise HTTP timeout and cap retries (avoids 55s+ hangs → Railway 504).
+ * Env: X402_FACILITATOR_TIMEOUT_MS (default 25000), X402_FACILITATOR_MAX_RETRIES (default 1).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.join(root, "..", "node_modules", "@dexterai", "x402", "dist", "server");
+const targets = ["index.js", "index.cjs"].map((f) => path.join(pkgRoot, f));
+
+const timeoutDefault =
+  "(Number(process.env.X402_FACILITATOR_TIMEOUT_MS)||25e3)";
+const maxRetriesDefault =
+  "(Number(process.env.X402_FACILITATOR_MAX_RETRIES)||1)";
+
+/** @type {{ from: string; to: string }[]} */
+const replacements = [
+  {
+    from: "this.timeoutMs=n?.timeoutMs??1e4",
+    to: `this.timeoutMs=n?.timeoutMs??${timeoutDefault}`,
+  },
+  {
+    from: "this.timeoutMs = config?.timeoutMs ?? 1e4",
+    to: `this.timeoutMs = config?.timeoutMs ?? ${timeoutDefault}`,
+  },
+  {
+    from: "this.maxRetries = config?.maxRetries ?? 3",
+    to: `this.maxRetries = config?.maxRetries ?? ${maxRetriesDefault}`,
+  },
+];
+
+let patched = 0;
+for (const file of targets) {
+  if (!fs.existsSync(file)) continue;
+  let src = fs.readFileSync(file, "utf8");
+  if (src.includes("X402_FACILITATOR_TIMEOUT_MS")) {
+    patched += 1;
+    continue;
+  }
+  let changed = false;
+  for (const { from, to } of replacements) {
+    if (src.includes(from)) {
+      src = src.replaceAll(from, to);
+      changed = true;
+    }
+  }
+  if (!changed) {
+    console.warn(`[patch-facilitator-timeout] pattern not found in ${path.basename(file)}`);
+    continue;
+  }
+  fs.writeFileSync(file, src);
+  patched += 1;
+}
+
+if (patched === 0) {
+  console.warn("[patch-facilitator-timeout] no files patched — check @dexterai/x402 version");
+  process.exit(0);
+}
+console.log(`[patch-facilitator-timeout] patched ${patched} file(s), timeout 25s, maxRetries 1`);