---
title: "Settlens documentation"
description: "Settlens documentation: install the CLI, run passive x402 scans, gate CI, monitor drift, sign evidence and let AI agents check payments through MCP."
url: https://settlens.com/docs
last_updated: 2026-10-13
---

# Documentation

> **In short:** Settlens documentation covers the CLI, the x402 V2 check catalog, configuration, report formats, the GitHub Action, Monitor, signed evidence, the MCP server and the HTTP scan API. Start with the quickstart: a passive scan of a local demo endpoint, with no wallet or payment key.

Install the Settlens CLI, assess x402 endpoints and facilitators, gate CI, monitor production, sign evidence and connect AI agents.

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](https://settlens.com/contact) receive; it is not published on npm.

## Start here

- **[Quickstart](https://settlens.com/docs/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](https://settlens.com/docs/cli)**

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

- **[MCP reference](https://settlens.com/docs/mcp)**

  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

_What do you want to do?_

| Task | Read |
| --- | --- |
| Check a PAYMENT-REQUIRED header in the browser, with nothing to install | [x402 checker](https://settlens.com/tools/x402-checker) |
| Understand x402 before you start | [Learn x402](https://settlens.com/learn) |
| Try Settlens on a local demo in ten minutes | [Quickstart](https://settlens.com/docs/quickstart) |
| Scan one paid endpoint | [CLI: scan](https://settlens.com/docs/cli#scan) |
| Check a facilitator's GET /supported | [CLI: facilitator](https://settlens.com/docs/cli#facilitator) |
| Assess many endpoints with a policy | [Configuration](https://settlens.com/docs/configuration) |
| Fail a pull request when a check fails | [GitHub Action](https://settlens.com/docs/github-action) |
| Understand a finding and fix it | [Check catalog](https://settlens.com/docs/checks) |
| Verify a captured payment authorization offline | [CLI: verify-payment](https://settlens.com/docs/cli#verify-payment) |
| Prove a report was not edited | [Reports: verify](https://settlens.com/docs/reports#verify-a-report) |
| Get alerted when payment terms change | [Monitor](https://settlens.com/docs/monitor) |
| Sign a report for a partner or auditor | [Evidence](https://settlens.com/docs/evidence) |
| Let an AI agent check a 402 before paying | [MCP server](https://settlens.com/docs/mcp) |
| Run scans from your own backend | [HTTP API](https://settlens.com/docs/api) |
| Know what a passing report proves | [Methodology](https://settlens.com/docs/methodology) |
| Review Settlens' safety guarantees or report a vulnerability | [Security model](https://settlens.com/docs/security) |

## How the pieces fit

_Diagram: Assess, CI gate, Monitor and Evidence form a sequence from first scan to signed evidence. Assess, CI gate and Monitor share one engine: the check catalog, the report formats and the SHA-256 digest. The MCP server uses the same engine so AI agents can check a payment request before paying._

_A finding means the same thing in a local scan, a CI job, a monitor alert and an agent's decision._

## Browse by component

### Use Settlens

- **[CLI reference](https://settlens.com/docs/cli)**

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

- **[Configuration](https://settlens.com/docs/configuration)**

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

- **[GitHub Action](https://settlens.com/docs/github-action)**

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

- **[Monitor](https://settlens.com/docs/monitor)**

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

- **[Evidence](https://settlens.com/docs/evidence)**

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

- **[MCP reference](https://settlens.com/docs/mcp)**

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

### Reference

- **[Check catalog](https://settlens.com/docs/checks)**

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

- **[Reports](https://settlens.com/docs/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](https://settlens.com/docs/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](https://settlens.com/docs/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](https://settlens.com/docs/security)**

  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](https://settlens.com/docs/cli) 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.

> **Get access**
>
> To run Settlens on your own endpoints, [request a pilot](https://settlens.com/contact): we scope one endpoint or facilitator first and share the repository. Building an agent? Start with the [MCP server](https://settlens.com/mcp).