Documentation menu
Assessment methodology
What a Settlens assessment observes, what it sends in each mode, how results are graded and what a passing report does and does not prove.
In short
Settlens assesses the x402 V2 HTTP payment challenge with passive requests that carry no payment header, an optional facilitator GET /supported check and, only with an owner approval reference, one invalid PAYMENT-SIGNATURE. A passing report shows behavior observed during the scan, not a certification.
On this page
This page describes how Settlens 0.5.0 gathers evidence and what that evidence can support. It applies to every interface: the CLI, the GitHub Action, Monitor, the HTTP API and the network tools of the MCP server.
Scope
Settlens evaluates the x402 V2 HTTP payment challenge exposed by a paid resource, the advertised capabilities of an optional facilitator, and, offline, captured payment authorizations. It combines four kinds of checks:
- Conformance checks derived from the x402 V2 core specification and the V2 HTTP transport.
- Compatibility parsing with the official
@x402/coreSDK, pinned at version 2.28.0, so a result reflects what clients built on that SDK accept. - An operator policy: allowed schemes, networks, recipients, assets and a maximum amount, each checked only when you set it.
- Conservative security checks: transport, binding of the payment to the requested resource, stability across requests and, with authorization, fail-closed behavior.
Every check is documented with its rationale and fix in the check catalog.
Only V2 is assessed. An x402 V1 endpoint sends its requirements in the 402 response body instead of the PAYMENT-REQUIRED header, so it fails transport.payment_required_header (high). See x402 V1 to V2 migration: what changed on the wire.
Modes
Passive scan
The default. Settlens sends ordinary requests without any payment header, 2 by default, with Accept: application/json and the user agent Settlens/0.5.0 authorized-security-assessment. Each request has a 8000 ms timeout, redirects are never followed (a redirect is reported instead), and at most 1 MiB of the body is read, hashed and discarded. The first answer is checked for HTTP 402, the PAYMENT-REQUIRED header, its Base64 JSON encoding, the official SDK schema, the V2 shape, the binding of resource.url to the requested URL, every advertised payment option and your policy. Later samples are compared with the first to detect terms that change between identical requests; known ephemeral fields (recentBlockhash, lastValidBlockHeight) are ignored.
Facilitator scan
With a facilitator URL, Settlens reads GET /supported and checks its status, media type, transport, the SupportedResponse shape, x402 V2 capability, duplicate kinds and signer metadata. When a resource was scanned too, it checks that every scheme and network the resource advertises is supported by the facilitator for the same x402 version. This is passive: /verify is called only by the active probe, and /settle never. Facilitator risks these checks do and do not cover: x402 facilitator security: /verify and /settle.
Authorized active probe
The active probe answers one question: does the resource stay closed when someone presents an invalid payment? It runs only when three conditions hold: --active, --authorized and a non-empty --authorization-ref are given, and the passive scan decoded a V2 PaymentRequired object with at least one payment option. The CLI refuses to start (exit 2) when --active comes without the other two; any other caller that requests the probe without authorization gets a failing safety.active_authorization check instead of a probe. Without a decodable V2 PaymentRequired object, the probe is skipped.
The probe payload is built from the first advertised option and cannot authorize a transfer:
- EVM networks: an all-zero 65-byte signature over an authorization from the zero address, with a zero nonce, the advertised recipient and amount, and a validity window around the current time.
- Solana networks: a transaction field made of 64 zero bytes.
- Other networks: a marker payload,
settlens-intentionally-invalid-authorization.
It is sent once, Base64-encoded in PAYMENT-SIGNATURE. A 2xx answer is a critical failure: the resource serves content for a payment that cannot be valid. An answer other than 400 or 402 is a medium warning. When a facilitator is configured, the same payload is posted to its /verify, which must answer with a well-formed VerifyResponse and isValid: false; isValid: true is a critical failure. The authorization reference is written into the report.
Authorization comes first
Run the active probe only on endpoints you own or are allowed in writing to test. It is one request, with no key and no funds, but it is still traffic the owner must approve. Settlens records the reference you give; it cannot check that the approval exists.
Offline verification
verify-payment and the MCP verification tools check captured authorizations without any network access: EIP-3009 / EIP-712 signer recovery for the EVM exact scheme with the domain rebuilt from the requirement, binding of recipient, amount and asset, and the validity window (strictly validAfter < now < validBefore); for Solana transactions, the ed25519 signature in every signer slot, with empty slots such as the fee payer's before settlement reported as pending. They do not check balances, on-chain nonce use or replay, or settlement. Details: verify-payment.
Result semantics
Each check ends as pass, fail, warn or skip and carries a severity from info to critical. Severity expresses expected impact if the property does not hold, not the likelihood of exploitation. The default CI threshold is high: a run fails when a check of severity high or critical fails. Definitions and counts: How to read a check.
| Severity | Meaning |
|---|---|
| critical | Payment protection can be bypassed. |
| high | A required protocol, binding, policy, reachability or facilitator-coverage property fails. |
| medium | A meaningful transport, signer or stability weakness. |
| low | Hygiene or ambiguity. |
| info | Descriptive evidence. |
Evidence handling
Reports record the sanitized target URL, request header names, response status, duration, size and body digest, the response header names, and check-specific evidence. They omit request header values and response bodies. The JSON report is serialized with the settlens-stable-json-v2 canonicalization (keys in code-unit order, independent of locale; reports made with v1 still verify) and hashed with SHA-256, so verify-report can detect any later change. The digest establishes integrity only; binding a report to a signer and a time is the job of an evidence attestation. Every report also states settlementCalls: 0 and privateKeysUsed: 0.
What a passing report proves
A passing report shows that the sampled endpoint behaved consistently with the tested properties during the recorded window, for the requests Settlens sent. It does not establish:
- the absence of vulnerabilities in code paths the requests did not exercise;
- that real wallet signatures are verified correctly beyond the one invalid payload class the active probe sends;
- on-chain facts: balances, nonce use, replay protection or settlement;
- uptime, rate limiting, economic safety or multi-tenant isolation;
- legal, regulatory or audit certification.
When you cite a result to a customer or partner, cite the exact report (its id and digest), the Settlens version, the configuration scope and, for active runs, the authorization record.
How pilots are run
- Testnet assets and synthetic data.
- One resource endpoint and one facilitator to start with.
- At most two passive samples plus one authorized invalid-signature probe per run.
- No wallet keys, real signatures, settlement, replay or fund movement.
- Testing stops immediately if the owner withdraws authorization or unexpected impact appears.
A pilot succeeds when Settlens produces a reproducible report, surfaces at least one actionable conformance or security fact, causes no impact, leaks no secret, and the owner finds the evidence understandable. Finding a vulnerability is not required.
Questions
Does a passing report mean my x402 endpoint is secure?
No. It means the endpoint behaved as expected for the properties Settlens tested, during the scan. It does not cover untested code paths, on-chain behavior or legal compliance, and it is not a certification.
Why does one invalid request need written authorization?
Because it is still active traffic against someone else's system, and payment endpoints are sensitive. Settlens refuses to send the probe without both the confirmation flag and a traceable approval reference, which it records in the report.
Which x402 version does Settlens assess?
x402 V2, over the V2 HTTP transport, validated with the official @x402/core SDK pinned at the version shown in each report under integrations.officialX402Core.
Sources
Last updated