--- title: "Quickstart: your first x402 scan | Settlens" description: "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." url: https://settlens.com/docs/quickstart last_updated: 2026-10-13 --- # Quickstart > **In short:** Install the Settlens CLI (Node.js 20.19 or newer, from the private repository shared with pilot participants), start the bundled demo server and run settlens scan on a local x402 endpoint. It writes JSON, HTML and SARIF reports; verify-report then checks the SHA-256 digest. No wallet is needed. Install the Settlens CLI, scan a local x402 endpoint, read the report and verify its integrity, in about ten minutes and without a wallet. This guide runs Settlens against a demo server on your own machine. Apart from installing dependencies from npm, nothing leaves `127.0.0.1`; no wallet or key is involved, and the demo includes endpoints that are deliberately wrong so you can see real findings. > **No access yet? Start in the browser** > > Paste a `PAYMENT-REQUIRED` header into the [x402 payment request checker](https://settlens.com/tools/x402-checker) to run the offline checks with nothing to install. The steps below run the full passive scan on your machine. ## Requirements - Node.js 20.19 or newer, with npm. Check with `node --version`. - A copy of the Settlens repository (see the next step). - Two terminal windows: one for the demo server, one for the CLI. ## 1. Get access Settlens is developed in a private repository. Pilot participants receive access to it; it is not published on npm. If you do not have access yet, [request a pilot](https://settlens.com/contact) and describe the endpoints or facilitators you want assessed. ## 2. Install the locked dependencies From the repository root: **Install and check the version** ```shell npm ci --ignore-scripts node src/cli.js --version ``` `npm ci` installs the exact versions from `package-lock.json`: the runtime dependencies `@noble/curves`, `@noble/hashes`, `@x402/core`, `nodemailer` and `proper-lockfile`, and `ajv` for the test suite. `--ignore-scripts` stops packages from running install scripts. The version command prints `0.5.0`. The rest of the documentation writes `settlens` for `node src/cli.js`. Define an alias so you can paste the examples as they are: **Alias (run from the repository root)** ```shell alias settlens="node $PWD/src/cli.js" ``` ## 3. Start the demo server In the first terminal: **npm run demo:server** ```text $ npm run demo:server Settlens demo server listening on http://127.0.0.1:4402 secure: http://127.0.0.1:4402/secure missing header: http://127.0.0.1:4402/missing-header drifting price: http://127.0.0.1:4402/drift bypass: http://127.0.0.1:4402/bypass facilitator: http://127.0.0.1:4402/facilitator ``` _Demo endpoints_ | Path | Behavior | What it demonstrates | | --- | --- | --- | | /secure | Answers 402 with a valid PAYMENT-REQUIRED, and 402 again to any payment signature. | A conformant paid resource: every check passes. | | /missing-header | Answers 402 without PAYMENT-REQUIRED. | A failing transport.payment_required_header check. | | /drift | Alternates the price between 10000 and 25000 atomic units on each request. | A stability warning and policy failures. | | /bypass | Answers 200 with content to any PAYMENT-SIGNATURE, valid or not. | The critical finding of the authorized active probe. | | /facilitator | Serves GET /supported and rejects every POST /verify. | A conformant facilitator for scan --facilitator. | The demo advertises the Base Sepolia test network (`eip155:84532`). Set `SETTLENS_DEMO_PORT` to use another port. ## 4. Run your first passive scan In the second terminal: **settlens scan (exit 0; absolute paths shortened)** ```text $ settlens scan http://127.0.0.1:4402/secure Settlens x402 assessment 8ef6b907 Targets 1 · Active 0 · Settlement calls 0 127.0.0.1 GET http://127.0.0.1:4402/secure 13 pass · 0 fail · 0 warn · 0 skip Total: 13 pass · 0 fail · 0 warn · 0 skip Reports: …/reports/settlens-8ef6b907.json …/reports/settlens-8ef6b907.html …/reports/settlens-8ef6b907.sarif ``` Settlens requested the endpoint twice without any payment header, decoded the `PAYMENT-REQUIRED` header, validated it with the official x402 SDK and its own rules, checked that the payment terms point at the URL you asked for and stayed the same across both requests, and ran 13 checks in total. `Settlement calls 0` is literal: Settlens never calls `/settle`. Your report id will differ. ## 5. Read the report The scan wrote three files to `reports/`. Open the **HTML** file in a browser for a readable summary with every check, its message and its evidence. The **JSON** file is the evidence itself; each check looks like this: **One check from settlens-8ef6b907.json** ```json { "id": "binding.resource_url", "title": "Payment requirement is bound to the requested resource", "status": "pass", "severity": "high", "message": "resource.url exactly matches the protected request URL.", "evidence": { "requested": "http://127.0.0.1:4402/secure", "advertised": "http://127.0.0.1:4402/secure" } } ``` Look up any id in the [check catalog](https://settlens.com/docs/checks), and every field in [Reports](https://settlens.com/docs/reports). The **SARIF** file is for code-scanning tools. ## 6. Verify the report The JSON report ends with a SHA-256 digest of its own content. Anyone who receives the file can check it has not been edited: **settlens verify-report** ```text $ settlens verify-report reports/settlens-8ef6b907.json VALID Report content matches its SHA-256 evidence digest. Expected: 646b3d941885b8bf1cb50ff4f55a24b0635b936ba233d24957c235bf1ce4f1ef Actual: 646b3d941885b8bf1cb50ff4f55a24b0635b936ba233d24957c235bf1ce4f1ef ``` Change any value in the file and run it again: the result becomes `INVALID` and the command exits 1. To also prove who produced a report, sign it with [Evidence](https://settlens.com/docs/evidence). ## 7. See a finding Scan the drifting endpoint with a policy that expects Base mainnet and a lower price ceiling: **settlens scan with a policy (exit 1)** ```text $ settlens scan http://127.0.0.1:4402/drift \ --expect-network eip155:8453 --max-amount 5000 Settlens x402 assessment 7093ee3c Targets 1 · Active 0 · Settlement calls 0 127.0.0.1 GET http://127.0.0.1:4402/drift 12 pass · 2 fail · 1 warn · 0 skip FAIL high Networks match the local policy Unexpected networks: eip155:84532. FAIL high Amounts stay within the approved ceiling 1 payment amount(s) exceed 5000. WARN medium Payment requirements remain stable Payment terms changed between identical unauthenticated requests. Total: 12 pass · 2 fail · 1 warn · 0 skip ``` Two high-severity failures meet the default `--fail-on high` threshold, so the command exits 1, which is what fails a CI job. The warning reports that the price changed between two identical requests. ## 8. Optional: the authorized active probe The `/bypass` endpoint serves its content to anyone who sends a `PAYMENT-SIGNATURE` header, valid or not. The active probe sends one deliberately invalid signature to catch exactly this: **Authorized active probe on the local demo** ```shell settlens scan http://127.0.0.1:4402/bypass \ --active --authorized --authorization-ref DEMO-APPROVAL-002 ``` It reports `FAIL critical Invalid payment authorization is denied` and exits 1. Against `/secure`, the same probe passes. > **Only with written authorization** > > Outside this local demo, run the active probe only on endpoints you own or are allowed in writing to test, and put the approval reference in --authorization-ref. ## Next steps - List your own endpoints and policy in a [configuration file](https://settlens.com/docs/configuration) and run [`settlens check`](https://settlens.com/docs/cli#check). - Fail pull requests on findings with the [GitHub Action](https://settlens.com/docs/github-action). - Watch production endpoints for changes with [Monitor](https://settlens.com/docs/monitor). - Let an AI agent check a payment request before paying with the [MCP server](https://settlens.com/docs/mcp). - Read what each mode sends, and what a passing report proves, in the [methodology](https://settlens.com/docs/methodology). ## Sources 1. [x402 V2 HTTP transport](https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md) — x402 Foundation 2. [CAIP-2: Blockchain ID Specification](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md) — Chain Agnostic Standards Alliance