Quickstart

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.

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 and describe the endpoints or facilitators you want assessed.

2. Install the locked dependencies

From the repository root:

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 settlens="node $PWD/src/cli.js"

3. Start the demo server

In the first terminal:

$ 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

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 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:

{
  "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, and every field in 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 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.

7. See a finding

Scan the drifting endpoint with a policy that expects Base mainnet and a lower price ceiling:

$ 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:

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.

Next steps

• List your own endpoints and policy in a configuration file and run settlens check.
• Fail pull requests on findings with the GitHub Action.
• Watch production endpoints for changes with Monitor.
• Let an AI agent check a payment request before paying with the MCP server.
• Read what each mode sends, and what a passing report proves, in the methodology.