Documentation

Settlens checks that x402 paid resources and facilitators follow the protocol, bind each payment to the right resource, recipient and price, and keep doing so. It verifies payment authorizations offline and signs its evidence. It is passive by default, needs no wallet or payment key, never calls /settle and never holds funds.

The CLI (version 0.5.0) runs on Node.js 20.19 or newer. Its code is in a private repository that pilot participants receive; it is not published on npm.

Start here

• Quickstart

  Get started with Settlens: install the CLI, run the local x402 demo server, scan an endpoint passively, read the JSON and HTML reports and verify them.

• CLI reference

  Settlens CLI reference: scan, facilitator, check, verify-report, verify-payment, monitor, evidence and mcp, with every option, default and exit code.

• MCP reference

  Settlens MCP reference: tool inputs and outputs, resources, the x402_preflight prompt, stdio and HTTP transports, authentication, limits, errors and sessions.

Find a page by task

How the pieces fit

Browse by component

Use Settlens

• CLI reference

  Settlens CLI reference: scan, facilitator, check, verify-report, verify-payment, monitor, evidence and mcp, with every option, default and exit code.

• Configuration

  Settlens configuration reference: targets, defaults, policy, facilitator and headers, generated from the JSON Schema, with examples and validation rules.

• GitHub Action

  Use the Settlens composite GitHub Action: inputs and outputs, complete workflows, secrets and allowed hosts, SARIF, permissions and pinning advice.

• Monitor

  Settlens Monitor: scheduled passive scans compared with the previous run, regression rules, the state file, webhook payload, exit codes and scheduling.

• Evidence

  Settlens Evidence: generate an ed25519 key, attest a report, verify the attestation offline, the attestation format, key management and its limits.

• MCP reference

  Settlens MCP reference: tool inputs and outputs, resources, the x402_preflight prompt, stdio and HTTP transports, authentication, limits, errors and sessions.

Reference

• Check catalog

  The Settlens check catalog: every x402 conformance, binding, policy, stability and facilitator check, with its severity, mode, rationale and fix.

• Reports

  Settlens report formats: the JSON report schema, the HTML report, SARIF for code scanning, and the SHA-256 integrity digest checked by verify-report.

• HTTP API

  Settlens HTTP scan API: POST /api/scan with a bearer token, request fields, the JSON report response, errors, rate limits and destination (SSRF) rules.

Assurance

• Methodology

  How Settlens assesses x402 endpoints: passive scans, the authorized invalid-signature probe, facilitator checks, result semantics and the limits of a report.

• Security model

  Settlens security model: no custody, no payment keys, trust boundaries, threats, residual risks, supply chain, safe testing and vulnerability disclosure.

Conventions in these docs

• settlens stands for node /path/to/settlens/src/cli.js; the CLI reference shows a one-line alias.
• Transcripts are real output. Scans run against the demo server bundled with the repository (npm run demo:server). Report ids, digests, keys and timings differ on every run.
• merchant.example and facilitator.example stand for your own hosts.
• Reference tables (configuration fields, report fields, checks, Action inputs, CLI options) are generated from the Settlens source when this site is built.