HTTP scan API

The Settlens website exposes one scan endpoint for server-to-server use. It runs the same passive scan as settlens scan on a public URL and returns the JSON report, with its integrity digest, in the response body. It never sends a payment signature, never runs the active probe and never calls /settle.

Authentication

Every request needs Authorization: Bearer <token>; the Bearer scheme is required. The token is compared in constant time with the one configured on the server; a missing or wrong token gets 401. A server with no token, a placeholder token or one shorter than 32 characters disables the API and answers 401 to everyone. Tokens are not self-service: ask for one with your pilot request. Call the API from a backend only: it sends no CORS headers, and a token in browser code is a token anyone can read.

Request

POST /api/scan HTTP/1.1
Host: settlens.com
Authorization: Bearer <your API token>
Content-Type: application/json

{ "url": "https://api.merchant.example/v1/weather", "facilitator": "https://facilitator.example" }

The scan is fixed: GET, no custom headers, two samples, an 8000 ms timeout per request and no local policy, so policy checks do not run. To scan with a policy, custom headers or the authorized active probe, use the CLI in your own environment.

curl -sS https://settlens.com/api/scan \
  -H "Authorization: Bearer $SETTLENS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.merchant.example/v1/weather"}' \
  -o report.json

Response

A successful call answers 200 with the complete report: the same schema as the CLI's JSON report, with metadata.source set to settlens-web-api. Findings are part of the report, not HTTP errors: an endpoint that is not an x402 resource still gets 200 and a report with failing checks. Excerpt of a real call against a public page that does not ask for payment:

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
cache-control: no-store

{
  "schemaVersion": 1,
  "reportId": "a01d0965",
  "product": "Settlens",
  "metadata": { "source": "settlens-web-api" },
  "scope": { "targetCount": 1, "activeTargetCount": 0, "settlementCalls": 0, "privateKeysUsed": 0 },
  "summary": { "pass": 3, "fail": 2, "warn": 0, "skip": 1 },
  "targets": [
    {
      "mode": "passive",
      "checks": [
        { "id": "transport.status_402", "status": "fail", "severity": "high",
          "message": "Expected HTTP 402 but received HTTP 200.", "…": "…" }
      ],
      "…": "…"
    }
  ],
  "integrity": {
    "algorithm": "sha256",
    "canonicalization": "settlens-stable-json-v2",
    "digest": "eb165ca0664092eee3f321d0b4643de8b4df02eae3f4a143033d09c315645bad"
  }
}

Save the body as a file and it verifies like any other report: settlens verify-report report.json. Field reference: JSON report.

Errors

Errors are JSON objects with a single error message.

Other destination messages you may see: Only http and https destinations are allowed., Only ports 80 and 443 are allowed., Credentials in the URL are not allowed., Local destinations are not allowed., The destination resolves to a private or non-routable address. and Could not resolve <host>: ….

Limits

• 30 requests per client IP per 60-second window. Requests rejected with 401 count too.
• Request bodies up to 32 KiB; url up to 2048 characters.
• Each scan makes up to two requests to the target (one when the first answer has no PAYMENT-REQUIRED), plus one to /supported when a facilitator is given, each with an 8000 ms timeout and a 1 MiB cap on the body read.

Destination rules (SSRF protection)

The API makes requests from Settlens' server, so it only reaches public destinations. Before any request, the target and facilitator URLs are checked:

• Only http and https, on ports 80 and 443 only, with no credentials in the URL.
• No localhost, and no host name ending in .local or .internal.
• An IP literal, and every address a host name resolves to, must be publicly routable. Refused IPv4 ranges include private networks (10/8, 172.16/12, 192.168/16), loopback (127/8), link-local (169.254/16, which covers cloud metadata services), shared CGNAT space (100.64/10), documentation, benchmarking, multicast and reserved ranges. For IPv6 only global unicast is accepted, without documentation and Teredo prefixes, and an IPv4 address embedded in IPv6 (mapped, NAT64 or 6to4) must itself be public.
• Redirects are never followed, so a public URL cannot bounce the request to an internal one.

The HTTP client resolves the host again when it connects, after the check. That gap is accepted because the API is authenticated, passive and follows no redirects.

What is not an API

/api/pilot receives the website's pilot request form. It is not a public API and has no stability guarantees; use the contact page to reach the team.

Questions