Documentation menu
Check catalog
Every check Settlens can report, grouped by category, with what it verifies, why it matters and how to fix a failure.
In short
Settlens reports 36 checks in 9 categories (transport, schema, binding, freshness, policy, stability, security, safety, facilitator), each with a default severity from low to critical, a mode (passive, offline, active, facilitator) and a fix. The 2 critical checks run only in the authorized active probe.
On this page
Settlens reports 36 checks. This page is generated from the catalog in the Settlens source (src/catalog.js), which a test keeps in sync with every check the code can emit. The MCP server serves the same entries as the settlens://checks resource and through the list_checks tool, so an agent and a human read the same text. Link to a check with its id as the anchor, for example /docs/checks#binding.resource_url.
To run the offline checks on a PAYMENT-REQUIRED header without installing anything, paste it into the x402 payment request checker.
- Checks in the catalog
- 36
- Categories
- 9
- Critical checks
- 2
- Run only with the authorized active probe
How to read a check
Each result in a report has an id, a status, a severity, a message and, when it did not pass, a recommendation. See Reports for the full format.
| Status | Meaning |
|---|---|
| pass | The observed evidence satisfied the check. |
| fail | The observed evidence violated a required property. |
| warn | A risk or instability was observed, but it is not a hard conformance failure. |
| skip | The prerequisite evidence was unavailable, or the check was out of scope for this run. |
| Severity | Meaning | Checks |
|---|---|---|
| critical | Payment protection can be bypassed: content is served, or a payment accepted, without a valid authorization. | 2 |
| high | A required protocol, binding, policy, reachability or facilitator-coverage property fails. | 22 |
| medium | A meaningful transport, signer or stability weakness. | 10 |
| low | Hygiene or ambiguity, such as duplicate entries. | 2 |
| info | Descriptive evidence only. | 0 |
Severity expresses expected impact, not likelihood. For scan, facilitator and check, only failing checks count toward --fail-on; warnings never fail the run. Monitor is different: it alerts on changes, including a check that drops to a warning. A few checks report a lower severity when they degrade: when the active probe cannot complete, security.invalid_signature_fail_closed becomes a medium warning.
Modes
- passive Needs a live, unauthenticated request to the paid resource (settlens scan, settlens monitor, MCP scan_endpoint). Never sends a payment.
- offline Evaluated from the PaymentRequired content alone: runs offline in the MCP tool evaluate_payment_requirements and in every passive scan (policy.acceptable_option only in the agent tools).
- active Runs only with --active --authorized --authorization-ref: one intentionally invalid PAYMENT-SIGNATURE is sent. /settle is never called and no wallet or key is used.
- facilitator Reads a facilitator's GET /supported capabilities (settlens facilitator, scan --facilitator, MCP scan_facilitator).
Transport checks
How the paid resource answers a request without payment: reachability, HTTP 402, the PAYMENT-REQUIRED header and its encoding, HTTPS, redirects and response size.
Endpoint is reachable
transport.reachable high passive
What it verifies. Settlens received an HTTP response from the target URL within the timeout (8000 ms by default). Redirects are not followed.
Why it matters. Every other passive check depends on observing the real response. A failure usually means a DNS, TLS, firewall or URL problem, or an endpoint that is down while agents try to pay it.
How to fix. Confirm DNS, TLS, firewall rules and the configured endpoint URL.
Unauthenticated request requires payment
transport.status_402 high passive
What it verifies. A request without any payment header returns HTTP 402 Payment Required.
Why it matters. x402 signals that payment is needed with HTTP 402. Any other status means the resource is either served for free or not speaking x402, so a paying agent cannot trust the challenge.
How to fix. Protect the resource before executing business logic and return HTTP 402 when no valid payment is attached.
Reference. x402 V2 HTTP transport
Learn more. What is x402? HTTP 402 payments explained
PAYMENT-REQUIRED header is present
transport.payment_required_header high passive
What it verifies. The 402 response carries the PAYMENT-REQUIRED header defined by the x402 V2 HTTP transport.
Why it matters. Clients read the payment terms from this header. Without it an agent has no machine-readable terms to evaluate.
How to fix. Return the Base64-encoded PaymentRequired object in the PAYMENT-REQUIRED header.
Reference. x402 V2 HTTP transport
Learn more. PAYMENT-REQUIRED and x402 V2 headers explained, x402 V1 to V2 migration: what changed on the wire
PAYMENT-REQUIRED decodes as Base64 JSON
transport.payment_required_encoding high offline
What it verifies. The PAYMENT-REQUIRED value is at most 131072 characters, uses only Base64 or Base64URL characters and decodes to valid JSON nested at most 64 levels deep.
Why it matters. A value that cannot be decoded cannot be validated or bound to a payment; clients either fail or interpret it inconsistently.
How to fix. Base64-encode a valid PaymentRequired JSON object in the PAYMENT-REQUIRED header.
Reference. x402 V2 HTTP transport
Learn more. PAYMENT-REQUIRED and x402 V2 headers explained
Response body stays within the evidence limit
transport.response_body_limit medium passive
What it verifies. The 402 response body fits within the 1 MiB processing limit. Settlens stops reading at the limit.
Why it matters. Payment challenges should be small. A very large challenge body wastes agent bandwidth and can mean protected content is returned before payment.
How to fix. Keep payment challenge responses small and return protected content only after verified payment.
Learn more. x402 security: eight failure modes to test
Transport protects payment metadata
transport.https medium passive
What it verifies. The endpoint URL uses HTTPS. Plain HTTP is accepted only for loopback hosts (localhost, 127.0.0.1, ::1) used in local testing.
Why it matters. Over plaintext HTTP a network attacker can rewrite the payment terms, for example the payTo recipient or the amount, before the agent signs.
How to fix. Serve production payment endpoints exclusively over HTTPS.
Learn more. x402 security: eight failure modes to test
Payment endpoint does not redirect unexpectedly
transport.redirect medium passive
What it verifies. Reported as a warning when the endpoint answers with a 3xx redirect. Settlens never follows redirects and records the sanitized Location instead.
Why it matters. A redirect moves the payment challenge away from the URL that was assessed, which weakens the binding between the payment and the resource.
How to fix. Expose the canonical paid resource directly or explicitly include the redirected URL in the assessment scope.
Learn more. x402 security: eight failure modes to test
Invalid payment uses a standard failure status
transport.invalid_payment_status medium active
What it verifies. The response to the intentionally invalid payment is HTTP 400 or 402.
Why it matters. Clients rely on the x402 error mapping to tell malformed payment data (400) from failed verification or settlement (402).
How to fix. Return HTTP 400 for malformed payment data or HTTP 402 when verification/settlement fails.
Reference. x402 V2 HTTP transport
Learn more. x402 security checklist for servers and agents
Schema checks
Whether the decoded PaymentRequired object is valid x402 V2, for the official @x402/core SDK and for Settlens' field-level rules.
Official x402 SDK accepts PaymentRequired
schema.official_x402_sdk high offline
What it verifies. The decoded PaymentRequired object passes the parsePaymentRequired schema of the pinned official @x402/core 2.28.0 SDK.
Why it matters. Clients built on the official SDK reject objects that fail this schema, so agents either cannot pay or disagree about the terms.
How to fix. Align the emitted object with the current official @x402/core V2 schema.
Reference. x402 V2 core specification
Learn more. PAYMENT-REQUIRED and x402 V2 headers explained
PaymentRequired matches the x402 V2 core shape
schema.payment_required high offline
What it verifies. x402Version equals 2, resource is an object whose url is an absolute http(s) URL, and accepts is a non-empty array.
Why it matters. These are the fields every V2 client needs to bind a payment to a resource and to choose a payment option. When they are missing, the remaining content checks cannot run.
How to fix. Emit x402Version 2, a valid resource object and at least one accepted payment requirement.
Reference. x402 V2 core specification
Learn more. PAYMENT-REQUIRED and x402 V2 headers explained, x402 V1 to V2 migration: what changed on the wire
Accepted payment requirements are well formed
schema.payment_requirements high offline
What it verifies. Every accepts entry has a non-empty scheme, a CAIP-2 network, a positive integer atomic amount, a non-empty asset and payTo, and a positive maxTimeoutSeconds. On eip155 networks payTo must be a 20-byte hex address.
Why it matters. Malformed amounts, networks or recipients make it impossible to know what is being paid, to whom and on which chain.
How to fix. Correct invalid scheme, network, amount, asset, payTo or timeout fields before accepting payments.
Reference. x402 V2 core specification
Learn more. PAYMENT-REQUIRED and x402 V2 headers explained
Payment choices are unambiguous
schema.duplicate_requirements low offline
What it verifies. No two accepts entries are identical.
Why it matters. Duplicate choices make client selection non-deterministic and usually reveal a configuration error.
How to fix. Remove duplicate payment choices to avoid inconsistent client selection.
Binding checks
Whether the payment terms are tied to the resource that was actually requested.
Payment requirement is bound to the requested resource
binding.resource_url high offline
What it verifies. resource.url equals the URL that was requested, including path and query (the fragment is ignored). In evaluate_payment_requirements this check is a warning when no resource URL is supplied, because the binding cannot be confirmed.
Why it matters. When the advertised resource differs from the requested one, a payment can be steered to, or reused for, a different resource than the one the agent asked for.
How to fix. Bind the payment requirement to the exact canonical resource URL, including its path and relevant query.
Reference. x402 V2 core specification
Learn more. x402 security: eight failure modes to test
Freshness checks
How long a signed payment authorization stays usable.
Authorization windows are reasonably bounded
freshness.timeout_window medium offline
What it verifies. Every maxTimeoutSeconds value is at most 3600 seconds (one hour).
Why it matters. A long authorization window keeps a signed payment usable for longer, which increases replay and misuse exposure.
How to fix. Use the shortest authorization window compatible with settlement to reduce replay exposure.
Reference. x402 V2 core specification
Learn more. x402 security: eight failure modes to test
Policy checks
Your own rules: the schemes, networks, recipients, assets and amounts you accept. Each check runs only when the matching policy field is set (expected in a config file, the --expect-* and --max-amount options, or the policy argument of the MCP tools).
Guide. AI agent spending policy for x402 payments
Schemes match the local policy
policy.scheme high offline
What it verifies. Every advertised scheme is in the policy's allowed schemes (case-insensitive). Evaluated only when a scheme policy is set. In the agent tools (evaluate_payment_requirements, scan_endpoint) it summarizes the options instead: pass when every option complies, warn when some do not, fail when none does; the decision then rests on policy.acceptable_option.
Why it matters. Restricting schemes keeps the agent on payment flows it knows how to verify.
How to fix. Restore the approved schemes or update the reviewed Settlens policy intentionally.
Networks match the local policy
policy.network high offline
What it verifies. Every advertised CAIP-2 network is in the policy's allowed networks (case-insensitive). Evaluated only when a network policy is set. In the agent tools (evaluate_payment_requirements, scan_endpoint) it summarizes the options instead: pass when every option complies, warn when some do not, fail when none does; the decision then rests on policy.acceptable_option.
Why it matters. Paying on an unexpected chain, for example a testnet instead of mainnet, means paying with the wrong funds or to a merchant that cannot receive them.
How to fix. Restore the approved networks or update the reviewed Settlens policy intentionally.
Recipients match the local policy
policy.recipient high offline
What it verifies. Every advertised payTo is in the policy's allowed recipients (EVM hex addresses case-insensitively, other formats such as Solana base58 exactly). Evaluated only when a recipient policy is set. In the agent tools (evaluate_payment_requirements, scan_endpoint) it summarizes the options instead: pass when every option complies, warn when some do not, fail when none does; the decision then rests on policy.acceptable_option.
Why it matters. A changed recipient is the most direct way to divert payments. An allowlist keeps the agent paying only reviewed merchants.
How to fix. Restore the approved payTo or update the reviewed Settlens policy intentionally.
Assets match the local policy
policy.asset high offline
What it verifies. Every advertised asset (token contract address or mint) is in the policy's allowed assets (EVM hex addresses case-insensitively, other formats such as Solana mints exactly). Evaluated only when an asset policy is set. In the agent tools (evaluate_payment_requirements, scan_endpoint) it summarizes the options instead: pass when every option complies, warn when some do not, fail when none does; the decision then rests on policy.acceptable_option.
Why it matters. The amount is counted in the asset's atomic units: without an asset allowlist, a ceiling meant for USDC can be spent in another token, and a look-alike token can be substituted for the one you reviewed.
How to fix. Restore the approved assets or update the reviewed Settlens policy intentionally.
Amounts stay within the approved ceiling
policy.maximum_amount high offline
What it verifies. Every advertised atomic amount is at most the policy's maxAmount. Amounts are compared in atomic units, so pair maxAmount with an asset policy. Evaluated only when maxAmount is set. In the agent tools (evaluate_payment_requirements, scan_endpoint) it summarizes the options instead: pass when every option complies, warn when some do not, fail when none does; the decision then rests on policy.acceptable_option.
Why it matters. A spending ceiling bounds what an agent can lose to a price change, a misconfiguration or a malicious server.
How to fix. Correct the advertised price or intentionally review and update the approved ceiling.
At least one payment option satisfies the policy
policy.acceptable_option high offline
What it verifies. Agent tools only (evaluate_payment_requirements, scan_endpoint): at least one advertised payment option is well formed and satisfies every policy constraint provided (schemes, networks, pay_to, assets, max_amount). The message counts the rejected options by constraint. The options that pass are returned as acceptable.
Why it matters. An agent pays with one option. One option outside the policy must not block the others, but when none is acceptable the agent has nothing safe to pay with.
How to fix. Do not pay. Ask the merchant for terms within your policy or change the policy deliberately.
Stability checks
Whether the payment terms stay the same across identical requests.
Payment requirements remain stable
stability.payment_requirements medium passive
What it verifies. Repeated identical unauthenticated requests (2 by default) return the same resource, accepts and extensions, ignoring the known ephemeral fields recentBlockhash and lastValidBlockHeight. Skipped when only one sample is available.
Why it matters. Terms that change between identical requests can reveal unintended dynamic pricing, recipient rotation or tampering.
How to fix. Confirm that dynamic pricing or recipient selection is intentional and cryptographically bound to the requested resource.
Learn more. Detecting x402 payment drift
Security checks
Fail-closed behavior, tested only by the authorized active probe.
Invalid payment authorization is denied
security.invalid_signature_fail_closed critical active
What it verifies. With explicit authorization, Settlens sends one intentionally invalid PAYMENT-SIGNATURE (for example an all-zero EVM signature) and expects the resource not to answer with a 2xx status.
Why it matters. A resource that serves content for an invalid signature is a payment bypass: anyone can obtain it without paying.
How to fix. Block resource execution unless cryptographic verification and settlement succeed. Treat this as a potential payment bypass.
Reference. x402 V2 HTTP transport
Learn more. x402 security: eight failure modes to test, x402 security checklist for servers and agents
Facilitator /verify rejects an invalid signature
security.facilitator_rejects_invalid_signature critical active
What it verifies. /verify returns isValid=false for the intentionally invalid, all-zero signature. Settlens never calls /settle.
Why it matters. A facilitator that accepts a forged signature lets anyone obtain paid resources without paying: a critical verification bypass.
How to fix. Cryptographically verify the payment signature before returning isValid. Treat isValid=true for a zero signature as a critical verification bypass.
Reference. x402 V2 core specification
Learn more. x402 facilitator security: /verify and /settle, x402 security: eight failure modes to test
Safety checks
Guards on Settlens' own behavior.
Active probe has explicit authorization
safety.active_authorization high active
What it verifies. An active probe was requested together with the owner-authorization confirmation and a non-empty authorization reference. Otherwise no probe is sent and this check fails.
Why it matters. Active testing sends traffic the endpoint owner must approve. Settlens refuses to probe without a traceable approval.
How to fix. Supply --authorized and --authorization-ref with the owner-approved ticket, email or scope identifier.
Facilitator checks
A facilitator's GET /supported capabilities, its coverage of what the resource advertises and, during an authorized active probe, its answer on /verify.
Guide. x402 facilitator security: /verify and /settle
Facilitator /supported is reachable
facilitator.reachable high facilitator
What it verifies. GET <facilitator>/supported returned an HTTP response within the timeout. Redirects are not followed.
Why it matters. If the facilitator cannot be reached, payments cannot be verified or settled.
How to fix. Confirm the facilitator base URL, authentication and network access.
Facilitator capability response fits the evidence limit
facilitator.response_body_limit high facilitator
What it verifies. The /supported response is at most 1 MiB.
Why it matters. Capability metadata should be small; an oversized response is truncated and cannot be validated.
How to fix. Reduce /supported to the minimum standardized capability metadata.
Facilitator exposes capabilities successfully
facilitator.supported_status high facilitator
What it verifies. GET /supported returned HTTP 200.
Why it matters. Resource servers and clients use /supported to discover which schemes and networks a facilitator can verify and settle.
How to fix. Expose the standardized GET /supported endpoint and return HTTP 200.
Reference. x402 V2 core specification
Facilitator capabilities use a JSON media type
facilitator.content_type medium facilitator
What it verifies. The /supported Content-Type is application/json or another +json media type.
Why it matters. Strict clients refuse to parse capability data served with a non-JSON media type.
How to fix. Return /supported with Content-Type application/json.
Facilitator capability transport is protected
facilitator.https medium facilitator
What it verifies. The facilitator URL uses HTTPS, or loopback HTTP for local testing.
Why it matters. Facilitator traffic carries payment payloads and verification results; over plaintext a network attacker can forge them.
How to fix. Serve facilitator APIs exclusively over HTTPS.
SupportedResponse matches the x402 core shape
facilitator.supported_schema high facilitator
What it verifies. The body has a non-empty kinds array (each with a positive integer x402Version, a scheme and a network, CAIP-2 for V2 kinds), an extensions array of strings and a signers object mapping networks to string arrays.
Why it matters. Malformed capability data makes coverage and signer checks impossible and breaks clients that rely on it.
How to fix. Return kinds, extensions and signers using the standardized SupportedResponse shape.
Reference. x402 V2 core specification
Facilitator advertises x402 V2 capabilities
facilitator.v2_capability high facilitator
What it verifies. At least one supported kind has x402Version 2.
Why it matters. A facilitator without V2 kinds cannot verify or settle x402 V2 payments.
How to fix. Register at least one x402 V2 scheme/network implementation.
Reference. x402 V2 core specification
Facilitator capabilities are unambiguous
facilitator.duplicate_kinds low facilitator
What it verifies. No x402Version, scheme and network combination appears twice in kinds.
Why it matters. Duplicate capability entries usually reveal a configuration error and make capability discovery ambiguous.
How to fix. Remove duplicate kinds from /supported.
Facilitator covers advertised payment requirements
facilitator.requirement_coverage high facilitator
What it verifies. Every scheme/network pair advertised by the resource appears in the facilitator's /supported kinds for the same x402Version. Skipped when /supported is invalid or unavailable.
Why it matters. If the facilitator does not support an advertised option, an agent may sign a payment that can never be verified or settled.
How to fix. Remove unsupported requirements or register their scheme/network implementation with the selected facilitator.
Facilitator publishes signer coverage
facilitator.signer_coverage medium facilitator
What it verifies. Every advertised network has a non-empty signer list in /supported, either for the exact network or for its namespace wildcard (for example eip155:*).
Why it matters. Signer metadata tells clients and auditors which addresses settle payments on each network.
How to fix. Publish signer addresses for every supported network or its CAIP-2 namespace.
Facilitator /verify is reachable
facilitator.verify_reachable medium active
What it verifies. During an authorized active probe, POST <facilitator>/verify with the intentionally invalid payload completed. Reported as a warning only when it could not complete.
Why it matters. Without a /verify answer, Settlens cannot show that the facilitator rejects invalid signatures.
How to fix. Re-run the authorized probe when the facilitator /verify endpoint is reachable.
Facilitator /verify returns a conformant VerifyResponse
facilitator.verify_response_schema high active
What it verifies. The /verify answer to the intentionally invalid payload is a JSON object with a boolean isValid field.
Why it matters. Resource servers decide whether to serve content from isValid; a non-standard answer risks being misread as success.
How to fix. Return the standardized x402 VerifyResponse: { isValid, invalidReason?, payer? }.
Reference. x402 V2 core specification
Next steps
Run these checks against your endpoint with the scan command, set the policy fields in a configuration file, or read how results are interpreted in the methodology.
Sources
Last updated