npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

thoughtproof-x402

v2.0.0

Published

Pre-settlement reasoning verification for x402 agent payments. Verifies AI agent decision quality before payment executes.

Readme

thoughtproof-x402

Pre-settlement reasoning verification for x402 agent payments.

x402 moves the money. ThoughtProof verifies the reasoning.

The Problem

x402 processes 119M+ transactions on Base alone. Every one settles without checking whether the agent's reasoning was sound. An agent with a valid wallet can make a catastrophic purchase decision — and the payment executes flawlessly.

thoughtproof-x402 adds the missing verification step between decide and settle:

Agent decides → ThoughtProof verifies → x402 settles

Quick Start

npm install thoughtproof-x402

Express Middleware

Drop in before your x402 paymentMiddleware:

import express from "express";
import { paymentMiddleware } from "@x402/express";
import { thoughtproofMiddleware } from "thoughtproof-x402/express";

const app = express();

// 1. Verify reasoning
app.use(thoughtproofMiddleware({
  thoughtproof: { apiKey: process.env.THOUGHTPROOF_KEY },
  policy: { onUncertain: "deny" },
}));

// 2. Process payment
app.use(paymentMiddleware({ /* x402 config */ }));

// 3. Serve resource
app.get("/api/data", (req, res) => res.json({ data: "verified" }));

Cloudflare Workers / Bun / Deno

Framework-agnostic — works with any Web Fetch API runtime:

import { verifyPayment } from "thoughtproof-x402";

export default {
  async fetch(request: Request): Promise<Response> {
    const verification = await verifyPayment(request, {
      thoughtproof: { apiKey: "tp_..." },
    });

    if (!verification.allowed) {
      return new Response(JSON.stringify(verification.result), { status: 403 });
    }

    const response = Response.json({ data: "verified" });
    for (const [k, v] of Object.entries(verification.headers)) {
      response.headers.set(k, v as string);
    }
    return response;
  },
};

How It Works

  1. Agent sends a payment request (x402 v2 Base64 PAYMENT-SIGNATURE header)
  2. thoughtproof-x402 extracts the agent context (address, resource, amount, reasoning)
  3. Sends to ThoughtProof API for multi-model adversarial verification
  4. If APPROVE (confidence ≥ threshold): adds attestation headers, continues to x402
  5. If DENY or UNCERTAIN: returns 403 with verification details

Migrating from 1.0.0

1.0.0 treated legacy X-PAYMENT as the default request header and called POST /v1/check. 2.0.0 does not.

  • Send an x402 v2 Base64 PAYMENT-SIGNATURE. Amount and network are read from that payload (accepted.amount, accepted.network). Set top-level allowV1: true only if you still accept v1 X-PAYMENT / payment.
  • Call Sentinel at POST /sentinel/verify. Tiers are checkpoint or standard (default standard). fast and deep are rejected. The API key is sent as X-Sentinel-Key.
  • A Sentinel HTTP 402 always denies (allowed: false, verdict DENY) on both Express and standalone, including when onError is "allow". The client does not pay that challenge.

Protocol and Sentinel migration

The default path is x402 v2. Both adapters decode Base64 UTF-8 JSON, read accepted.amount (atomic units), accepted.network, accepted.asset, and accepted.payTo, and extract EVM payer addresses from payload.authorization.from. Other schemes can omit the payer address. Signature/settlement validation stays with your x402 server; decoded fields are untrusted declarations.

PAYMENT-REQUIRED is a 402 response header and is never used as request evidence. Unpaid requests pass through so the x402 server can issue its challenge. Keep that server in the chain: allowed: true here does not prove payment or settlement.

For legacy clients, explicitly set top-level allowV1: true. This enables X-PAYMENT / payment with a version-1 envelope (Base64, or legacy raw JSON). PAYMENT-SIGNATURE always takes precedence; invalid v2 never downgrades to v1. Present but malformed, duplicate, empty, or disabled legacy payment headers are rejected before hooks or route skips, independently of onError (Express: 400; standalone: allowed: false, skipped: false).

The client calls POST /sentinel/verify with claim, string evidence, mode: "action_authorization", and tier. Supply independent evidence through AgentContext.evidence or onBeforeVerify; request bodies are explicitly marked as client declarations, not mandates. Request headers/signatures are not forwarded. Sentinel ALLOW maps to public APPROVE, BLOCK to DENY, and UNCERTAIN stays UNCERTAIN. Results preserve id and structured objections; model count and duration come from meta.models_used and meta.duration_ms.

Backend HTTP errors other than 402 (including 401, 429, and 503) follow policy.onError, whose existing default is "allow". Set onError: "deny" when verification is mandatory. A Sentinel HTTP 402 is always fail-closed: both adapters deny the request (allowed: false, verdict DENY) and never resolve it as allowed, regardless of onError. The client does not pay Sentinel's own x402 challenge using the incoming payment.

USD minAmount / maxAmount cannot value arbitrary atomic tokens. With decoded payments these policies deny unless a custom decide function explicitly handles valuation using trusted asset/network data. No token decimals or USD peg are inferred.

Contract reviewed on 2026-10-07: live OpenAPI, Sentinel source, x402 v2.

Attestation Headers

Verified responses include informational headers (not a signed proof). Sentinel does not promise chain hashes or audit URLs; those legacy fields remain empty:

X-ThoughtProof-Version: 1
X-ThoughtProof-Verdict: APPROVE
X-ThoughtProof-Confidence: 0.92
X-ThoughtProof-Chain-Hash:
X-ThoughtProof-Verifiers: 3
X-ThoughtProof-Audit-URL:
X-ThoughtProof-Duration-Ms: 247
X-ThoughtProof-Timestamp: 2026-04-14T21:00:00.000Z

Parse them on the client side:

import { parseAttestationHeaders } from "thoughtproof-x402";

const proof = parseAttestationHeaders(response.headers);
console.log(proof?.verdict);    // "APPROVE"
console.log(proof?.confidence); // 0.92
console.log(proof?.auditUrl);   // Empty unless supplied by another integration

Configuration

ThoughtProof Client

| Option | Default | Description | |--------|---------|-------------| | apiUrl | https://sentinel.thoughtproof.ai | API endpoint | | apiKey | — | Sentinel key sent as X-Sentinel-Key; no automatic backend payment | | tier | "standard" | "checkpoint" or "standard"; see Sentinel tier discovery for prices | | confidenceThreshold | 0.7 | Minimum confidence to APPROVE | | timeout | 10000 | Request timeout in ms |

Verification Policy

| Option | Default | Description | |--------|---------|-------------| | minAmount | 0 | Skip verification below this USD amount | | maxAmount | Infinity | Auto-deny above this USD amount | | skipRoutes | [] | Glob patterns to skip (e.g., "/health", "/api/*/public") | | requireRoutes | [] | Only verify these routes (takes precedence) | | onUncertain | "deny" | Action on UNCERTAIN: "allow" or "deny" | | onError | "allow" | Action on timeout/error: "allow" or "deny". A Sentinel HTTP 402 always denies. | | decide | — | Custom function: (result, context) => boolean |

Lifecycle Hooks

thoughtproofMiddleware({
  thoughtproof: { apiKey: "..." },
  onBeforeVerify: (context) => {
    // Supply trusted server-side evidence here; decoded payer addresses are unverified.
    context.evidence = lookupServerSideEvidence(context.resource);
    return true;
  },
  onAfterVerify: (result, context) => {
    // Log, emit metrics, update dashboards
    metrics.record("verification", result.verdict, result.durationMs);
  },
  onDeny: (result, context) => {
    // Alert, audit log, notify admin
    alerting.send(`Denied ${context.agentAddress}: ${result.reasoning}`);
  },
});

Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────┐     ┌──────────┐
│  AI Agent   │────▶│ thoughtproof-x402 │────▶│  x402   │────▶│ Resource │
│  (wallet)   │     │   verify reasoning │     │ payment │     │  Server  │
└─────────────┘     └──────────────────┘     └─────────┘     └──────────┘
                            │                       │
                            ▼                       ▼
                    ┌──────────────┐        ┌─────────────┐
                    │ ThoughtProof │        │  Base/ETH   │
                    │     API      │        │  Settlement │
                    └──────────────┘        └─────────────┘

thoughtproof-x402 intercepts the payment flow at the decision layer — after the agent decides to pay, before the money moves.

What ThoughtProof Verifies

  • Decision coherence: Is the agent's stated reasoning internally consistent?
  • Grounding: Are the claims in the reasoning backed by verifiable data?
  • Proportionality: Is the payment amount proportional to the stated purpose?
  • Intent alignment: Does the action match what the agent says it's trying to do?

This is not security (that's identity + permissions). This is not reputation (that's history). This is epistemic verification — checking whether the reasoning is actually sound.

License

MIT

Links