One engine for x402 assurance, five ways to run it.
Settlens runs one catalog of deterministic checks across four stages, Assess, CI, Monitor and Evidence, and reaches your engineers, pipelines and AI agents through a CLI, a GitHub Action, a container image, an HTTP API and an MCP server.
active-authorizedGET http://127.0.0.1:4402/bypass
- pass
- 25
- fail
- 1
- warn
- 1
- skip
- 0
- critical
security.invalid_ signature_ fail_ closed The endpoint returned HTTP 200 after an invalid payment authorization.
- medium
transport.invalid_ payment_ status Expected HTTP 400 or 402 for invalid payment, received HTTP 200.
- scope
- settlementCalls 0 · privateKeysUsed 0
- sha256
- verify-report · d5c00c1f…8fdae09d
- canonical
- settlens-stable-json-v2
- ed25519
- signature valid · report matches
In short
Settlens runs one catalog of deterministic x402 checks in four stages, Assess, CI gate, Monitor and Evidence, through a CLI, a GitHub Action, a container image, an HTTP API and an MCP server. It never settles or sends a valid payment and holds no wallet.
How the platform fits together
Every surface calls the same engine. By default the engine only reads: it requests the paid resource and the facilitator's capabilities, then writes reports you can verify.
Stage by stage
What each stage does, where it runs and what it leaves behind. Verify and the agent preflight reuse the same engine outside the four-stage loop.
| Stage | What it does | Runs from | Output |
|---|---|---|---|
| Assess | Passive scan of the 402 handshake, PAYMENT-REQUIRED, every advertised requirement, the resource binding, drift and your policy. Optional facilitator scan and authorized fail-closed probe. | settlens scan, facilitator and check; the container; the HTTP API and MCP scan_endpoint (passive only) | JSON, HTML and SARIF reports with a SHA-256 integrity block |
| CI gate | Runs your configured targets on pull requests and fails the job when a check fails at or above the fail-on severity. | GitHub composite Action (settlens check) | Exit code 1 at the threshold, SARIF for code scanning, report artifacts |
| Monitor | Compares each passive scan with the stored baseline and alerts on checks that get worse (pass or skip to warn or fail, warn to fail), on new failing or warning checks and on checks that disappear (coverage lost). | settlens monitor on a schedule (cron or CI) | Regression list, optional webhook POST, non-zero exit at the threshold |
| Evidence | Binds a report's SHA-256 digest to an ed25519 signing identity and a timestamp. | settlens evidence keygen, attest and verify; MCP verify_attestation | Attestation JSON anyone can verify offline |
| Verify | Recovers the EIP-3009 / EIP-712 signer of a captured exact EVM authorization and checks recipient, amount, asset and validity window, with no RPC. Checks every signer of a Solana transaction. | settlens verify-payment; MCP verify_payment_signature and verify_solana_transaction | Verified or not, with the reasons |
| Agent preflight | Evaluates a PAYMENT-REQUIRED header against the URL the agent requested and its spending policy, option by option. | MCP evaluate_payment_requirements, local or remote; the free x402 checker in a browser | pay, review or do_not_pay, the reasons and the acceptable options |
Integration surfaces
Pick the surface that matches who is asking: an engineer, a pipeline, an isolated host, a service or an AI agent.
-
CLI
scan, facilitator, check, monitor, verify-payment, verify-report, evidence and mcp. Exit code 1 when a finding meets the fail-on threshold, 2 on a usage or configuration error.
-
GitHub Action
Inputs: config, output, formats, fail-on, allowed-hosts. Writes JSON, HTML and SARIF to a report directory and exposes it as an output.
-
Container image
The Dockerfile pins node:24-alpine by digest, installs the locked production dependencies without install scripts and runs the CLI as the unprivileged node user.
-
HTTP API
POST /api/scan runs a passive scan of a public URL, optionally with its facilitator, and returns the JSON report. Private and loopback destinations are refused.
-
MCP server
settlens mcp serves all eight tools over stdio. The remote endpoint at settlens.com/mcp serves the six offline tools publicly; the two network tools need a bearer token.
Availability
Settlens lives in a private repository and is not distributed on npm. Pilot participants get the CLI, the GitHub Action and the Dockerfile; the HTTP API and the remote MCP network tools need a bearer token. Request a pilot to get access, or see pricing.
Self-testing vs independent assurance
Your own tests prove the paths you expected. Independent assurance applies fixed, published criteria and produces evidence that someone else can check.
| Question | Typical in-house tests | Settlens |
|---|---|---|
| Validates the 402 challenge with the official @x402/core schema | When someone wires it in | |
| Checks the resource binding and, against your policy, the recipient, asset, amount and network of every option | Usually the happy path | |
| Sends an invalid signature to check that the resource fails closed | Rarely: fixtures use valid payments | One, with explicit authorization |
| Asks the facilitator to verify an invalid signature | Rarely | During the authorized probe |
| Detects drift between identical requests | Rarely | |
| Same criteria in a pilot, in CI and in production monitoring | Often separate suites | |
| Tamper-evident, signed result a partner can verify offline | ||
| Knows your business logic and edge cases |
Settlens does not replace your test suite. It adds an outside view with stable check ids from a published catalog, and a report records what was observed during the run. It is not a certification, a full security audit or legal advice; the methodology explains what each result proves.
Deployment and security model
Settlens runs where you run it. The hosted surfaces add authentication, destination checks and rate limits.
-
Runs in your environment
The CLI, the Action and the container run on your machine or CI runner. A scan contacts only the targets and facilitators you configure, and the monitor adds only your optional webhook. Reports stay in your output directory.
-
Passive unless authorized
Scans and monitoring never send a payment signature. The active probe needs
--active,--authorizedand an authorization reference, and is never offered by the HTTP API or MCP. -
Secrets go only where you allow
Custom headers are sent only to hosts on a separate allowlist (--allow-host, SETTLENS_ALLOWED_HOSTS or the Action's allowed-hosts), and their values never reach the report.
-
Hosted endpoints are gated
POST /api/scan and the remote MCP network tools need a bearer token, refuse private and loopback destinations, never follow redirects and are rate limited per IP.
-
Pinned supply chain
Exact dependency versions with a lockfile, install scripts ignored, third-party GitHub actions pinned by commit SHA, container base image pinned by digest, non-root runtime.
-
Your evidence key, no custody
Evidence keys are generated locally with node:crypto and stay with you. Settlens holds no wallet, signs no payment and takes custody of nothing.
What a report does not prove
A passing report means the sampled endpoint behaved as the checks require during the recorded window. Settlens does not check on-chain balances, nonce use, replay or settlement, and a report does not prove the absence of other vulnerabilities. Read the security model and the security policy.
Explore the platform
Each stage has its own page with real commands and output, the free x402 tools run the public offline checks from your browser, and the documentation has the full reference.
-
Assess
x402 testing for paid APIs: scan for x402 V2 conformance, resource binding, drift and your payment policy, then check it fails closed with an authorized probe.
-
CI gate
Run Settlens in GitHub Actions: block merges on high-severity x402 findings and keep JSON, HTML and SARIF reports as build evidence for every run.
-
Verify
Verify captured x402 payments offline: EIP-3009 signer recovery, recipient, amount and time-window binding, Solana signer checks and facilitator checks.
-
Monitor
Schedule passive x402 scans, compare each run with a stored baseline and get a webhook alert when a check regresses, such as a price above your ceiling.
-
Evidence
Sign Settlens reports with ed25519 so customers and auditors can verify offline that a report is intact, who signed it and which digest was attested.
-
MCP server
Give AI agents a preflight check on every HTTP 402, locally over stdio or remotely.
| Topic | Pages |
|---|---|
| Get started | Documentation, Quickstart |
| Use Settlens | CLI, Configuration, GitHub Action, Monitor, Evidence, MCP |
| Reference | Checks, Reports, API |
| Assurance | Methodology, Security model |
Sources
Assess one paid endpoint first
Start with a scoped pilot on one endpoint or facilitator, and get a report your engineers and partners can verify.