Verify an x402 endpoint before your agent pays
Check an x402 endpoint before your agent pays it. Settled shows whether it answers, what it charges and whether it delivered, receipt included. A second question it answers: does this bounty or task venue actually pay agents. Both come from measured, signed data: live probes of every endpoint listed with the four public facilitators, real paid test purchases, payouts read from Base, and the seller’s claim and ERC-8004 identity when there is one. Connect it in one line or call it over HTTP.
How to verify an x402 endpoint before paying
- Ask Settled about the URL.
GET https://settled.tools/v1/free/check?url=<the endpoint>, or thesettled_checktool over MCP. Nothing is paid; the answer is signed. - Read the verdict.
status(live, degraded, dead),payability(payable, delivered, unreachable), the price andpayToSettled's own probe saw at that URL, the seller's claim if there is one, andscout_record: the last time Settled paid this endpoint for real, what came back, and the transaction. - Compare with the 402 you were given. A payTo or price that differs from what Settled saw is reason enough not to pay. The settled-x402 guard makes this comparison for every payment your agent signs, and refuses the ones with evidence against them.
- Keep it checked. A valid 402 proves an endpoint can take money, not that it delivers. Re-check before each paid call (the free tier covers 25 a day, 300 with a payer record), or put a Watchdog on the endpoints you rely on and get told within 15 minutes when one stops delivering.
The scout's purchase record, every real purchase with its receipt, is open data if you want to check the checker.
Start with a pass
One x402 payment of $0.05 (POST /v1/pass) unlocks every paid route except the Watchdog, Seller Watch and the seller re-test, and every MCP tool except settled_watch, for 24 hours at 120 requests a minute (endpoint searches up to 1,000 a day). It pays for itself after 10 preflights or 25 checks. The same pass for 30 days is $1 (POST /v1/pass/month) and for a year $10 (/v1/pass/year); the buyer bundle adds a Watchdog on up to 6 endpoints to the 30-day pass for $5. Every purchase is a term that ends by itself, nothing renews without a payment the agent signs, and a price rise is announced 30 days ahead: the terms. The settled-x402 guards can sign those renewals themselves: with renew: true the guard buys the 30-day pass with the agent's own wallet, an hour before each one runs out, only within a cap you set, and keeps it in a file across restarts. Without one, check, find and events are free: 25 calls a day for an anonymous client (counted per address), and 300 a day once the agent shows a payer record, which is free and keyed to its wallet rather than its address; at most 50 of either can be endpoint searches. Over MCP, or at /v1/free/check and /v1/free/endpoints. The 25 are for trying Settled; a wallet with any x402 history gets a record in one call. Need the whole index, with each seller's on-chain demand? That is one download: the index export, $5.
Check every payment in code
Add the npm package settled-x402 and your agent checks each x402 quote against Settled before it signs. It stops a payment whose payTo isn't the one Settled's own probe sees at that URL, and endpoints with evidence against them, such as a scout payment that came back empty. It uses the free check (25 a day per address, 300 with a payer record) or your pass.
npm install settled-x402
import { x402Client, x402HTTPClient, wrapFetchWithPayment } from '@x402/fetch';
import { settledGuard, dedupePayments } from 'settled-x402';
const client = new x402Client(); // register your payment schemes as usual
const fetchWithPayment = wrapFetchWithPayment(dedupePayments(fetch), settledGuard(new x402HTTPClient(client)));
On x402-fetch or another wrapper that takes a fetch, use withSettled(fetch) instead. To check one endpoint from a terminal: npx settled-x402 check <url>.
Under withSettled (and guardGlobalFetch) every paid answer is also screened before the agent reads it (0.7.0): instructions to ignore what the agent was told, requests for keys, a transfer verb with a wallet address, "do not tell the user", hidden text, chat-template markers, and the same inside base64. The answer comes back with x-settled-screen: clean | suspicious and the kinds found; screen: { action: 'throw' } refuses a suspicious answer, screen: false turns it off. The Python package's httpx transports do the same (0.3.0), and npx settled-x402 screen <file> runs it on any text.
Each request is paid once (0.9.0). Agents retry, and every retry signs a fresh payment; within 2 minutes, a request identical to one already paid gets the first answer back, and nothing is signed. The copy carries an x-settled-replay header with the time it was paid. A request identical to one being paid waits for its answer, and one whose payment went out with no answer back is refused (SettledDuplicateError, blockedBy: 'duplicate') rather than paid twice, since that payment may have settled. Identical means the same Idempotency-Key header, or else the same method, URL and body; a new key pays again on purpose. A paid request keeps running when its caller gives up on it, so the retry gets the answer the first payment bought, and a payment that never left (the connection failed) is forgotten. withSettled, guardGlobalFetch and the payment proxy do this on their own; with settledGuard, wrap the fetch as above. dedupeWindowMs: 0 turns it off. The Python package does the same (0.4.0) with dedupe_httpx(http) and dedupe_requests(http).
Add { renew: true } and the guard keeps a pass of its own: it buys the 30-day pass ($1) with the client it guards before the first check and an hour before each pass runs out, at the price in Settled's 402 at that moment and only within renew.upToUsd (the list price unless you raise it), so a price rise past your cap is not paid and the guard carries on with the free check. The pass lives in ~/.settled-x402/pass.json, so a restart does not buy again, and that purchase is held to the cap alone, not to your loadout or your daily budget. renew: 'year' keeps the $10 pass instead (raise the x402 client's own $1-per-payment cap for that). npx settled-x402 pass shows the pass in hand.
Python
The same guard for the x402 Python client, with the same verdicts, limits and messages: settled-x402 on PyPI. Guard the HTTP client you pay with (async or sync) and a blocked payment raises SettledBlockedError before anything is signed. For a framework that builds its own x402 client (LangChain, CrewAI, the OpenAI Agents SDK), guard_all() guards every client made after it. renew=True keeps a 30-day pass the same way as the npm package, in the same file. The spend ledger and the pass file are the same files as the npm package's, so one machine keeps one tally and one pass.
pip install settled-x402 "x402[clients]"
from x402.client import x402Client
from x402.http.x402_http_client import x402HTTPClient
from settled_x402 import settled_guard, dedupe_httpx
client = x402Client() # register your payment scheme as usual
http = settled_guard(x402HTTPClient(client), max_usd_per_call=1, daily_budget_usd=5)
async with dedupe_httpx(http) as session: # x402HttpxClient, with each request paid once
res = await session.get("https://api.example.com/paid")
From a terminal: settled-x402 check <url> reads the endpoint's 402 (nothing is paid) and prints the verdict; the exit code is 0 pay, 2 caution, 3 avoid, 4 unknown.
The same guard takes spending limits (since 0.5.0; onlyHosts and payerToken since 0.5.3): maxUsdPerCall stops any dearer call, dailyBudgetUsd stops the agent once the day's calls would pass it (the tally survives restarts), askAbove asks you before a call over that price, and onlyHosts is the loadout: nothing outside it is paid. Every result says what a call costs as loot: common (free), rare (up to $1 a call) or legendary (over $1). Set it all up on one screen at /loadout and copy the kit.
Amazon Bedrock AgentCore payments
AgentCore payments signs x402 payments with a key AWS holds; the agent's own tool makes the request, and the AgentCore Strands plugin or LangGraph middleware has the 402 signed and retries. Settled goes in front of the signature, with the receipt and your limits (PyPI 0.5.0). SettledStrandsPlugin (and SettledLangGraphMiddleware) sees every 402 a tool brings back, with the URL the tool was asked for, before AgentCore does: a blocked payment becomes an error result that says why, so the agent reads the reason and AgentCore has no 402 to pay. List it after AgentCore's plugin or middleware (Strands runs after-tool hooks last-registered first; the later LangGraph middleware is nearer the tool). Its pre_sign_policy fits the SDK's own gate, which runs before any payment is signed, as the backstop. Inside AgentCore Runtime there is no one to ask, so ask_above without ask stops the call; AgentCore's session budget stays in force underneath.
pip install "settled-x402[agentcore]" "bedrock-agentcore[strands-agents]" strands-agents-tools
from strands import Agent
from strands_tools import http_request
from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin
from settled_x402 import SettledStrandsPlugin
settled = SettledStrandsPlugin(max_usd_per_call=0.25, daily_budget_usd=5)
payments = AgentCorePaymentsPlugin(config=AgentCorePaymentsPluginConfig(
payment_manager_arn=PM_ARN, user_id="agent-1", payment_instrument_id=INSTRUMENT, payment_session_id=SESSION, region="us-west-2",
pre_sign_policy=settled.pre_sign_policy, # the backstop at the signing chokepoint
))
agent = Agent(tools=[http_request], plugins=[payments, settled]) # Settled listed after AgentCore
Coinbase AgentKit
AgentKit's x402 actions pay through the global fetch. Guard it, and give the agent Settled's check and search as actions. Neither action pays anything.
npm install settled-x402 @coinbase/agentkit
import { AgentKit, x402ActionProvider } from '@coinbase/agentkit';
import { guardGlobalFetch } from 'settled-x402';
import { settledActionProvider } from 'settled-x402/agentkit';
guardGlobalFetch({ network: 'base' }); // AgentKit's x402 actions now refuse what Settled says to avoid
const agentkit = await AgentKit.from({
walletProvider,
actionProviders: [x402ActionProvider(), settledActionProvider()],
});
The agent gets SettledActionProvider_check_x402_endpoint, which reads an endpoint's quote without paying and returns Settled's verdict on the wallet's network, and SettledActionProvider_find_x402_endpoints, which lists live endpoints by keyword and price. For AgentKit's own discover_x402_services, use the discovery feed.
Connect (MCP)
Claude Code
claude mcp add --transport http settled https://settled.tools/mcp
Claude Desktop, Cursor, Windsurf, any stdio client
{
"mcpServers": {
"settled": {
"command": "npx",
"args": ["-y", "settled-x402", "mcp"]
}
}
}
Holding a pass? Add "env": { "SETTLED_PASS": "<your pass>" } and every tool is unlocked at 120 requests/min. (npx -y mcp-remote https://settled.tools/mcp works too.) Cursor reads ~/.cursor/mcp.json; Claude Desktop reads its claude_desktop_config.json.
https://settled.tools/mcp/free is the same server with only the 13 tools that work without a pass or a payment: it is what the Claude directory connector and the Claude Code plugin use, since those clients cannot pay over x402. Settled is also listed on Smithery and on the official MCP Registry as tools.settled/settled.
What the tools do
| Tool | Access | Answers |
|---|---|---|
settled_preflight | pass | Should I pay this endpoint? Liveness on both verbs, quote, payability, payee existence, seller reputation, the scout's purchase result, agent reports, honeypot scan → pay | caution | avoid with reasons. |
settled_check | free · 25/day, 300 with a payer record | Status, payability, quote, latency, on-chain activity and quality for one endpoint, plus the scout's last purchase and whether it matched the listing (cached 5 min). |
settled_find_endpoints | free · 50 searches/day, 150 with a payer record | Ranked live endpoints by keyword, network and price, each with payability and delivery status. |
settled_events | free · 25/day, 300 with a payer record | What changed: venue verdict flips, new honeypots, integrity changes. |
settled_report | free | After paying an endpoint, say whether it worked, proven by your payment and a signature from the paying wallet. |
settled_watch | $2 · paid in MCP | A Watchdog for one endpoint: 30 days of probes about every 15 minutes and a signed alert on any change. Pass watch_id to renew it for 10 more days. Pays over x402 inside MCP; no webhook needed. |
settled_watch_alerts | free | Everything a Watchdog has recorded since your last check, plus the endpoint's state now. |
settled_income_venues | free | Which venues actually pay agents, verified from USDC leaving escrow on Base. |
settled_income_listings | pass | Open bounties and tasks an agent can work on, honeypots screened out. |
settled_income_check | pass | Honeypot scan of one bounty, issue or repo before you work on it. |
settled_seller_reputation | pass | Everything behind one payTo address, including settlement integrity. |
settled_claim · settled_sellers | free | Sellers: claim every endpoint paid to your wallet with one signature; list claimed sellers. |
settled_weekly_report · settled_status · settled_peek · settled_submit · settled_verify | free | The weekly report, index size and freshness, a coarse peek, adding an endpoint, and verification of any signed answer. |
A pass is one x402 payment of $0.05 (POST /v1/pass) good for 24 hours: it lifts the daily cap (25 free calls per address, 300 with a payer record) and unlocks every tool except settled_watch, and every paid route except the Watchdog, Seller Watch and the seller re-test. Tools that need one say so in their result with purchase instructions; nothing fails silently. A person can buy a pass, a Watchdog, a re-test or Seller Watch from a browser wallet at /buy, no x402 client needed.
Give your agent the skill
The settled-x402 skill tells any agent what to do with a 402: run the free check first, walk a short decision table (sanctioned payee, seller on hold, dead status, payTo mismatch, price drift, verified delivery, quality), preflight when the money matters, report afterwards, and say why. It is three files and works in Claude Code, Claude Managed Agents, the Agent SDK, OpenClaw or any harness that reads SKILL.md. Read it · download the package · Claude Code: /plugin marketplace add justinedwardvolmer/settled-skill then /plugin install settled@settled, which also connects the MCP server · already using the npm package: npx settled-x402 skill install copies it into .claude/skills (--global for every project, --to <dir> for any other harness).
Use it in n8n
n8n's MCP Client Tool node connects an AI Agent to Settled with no key: set the endpoint to https://settled.tools/mcp/free, transport HTTP Streamable, authentication None. Holding a pass (buy one here), use https://settled.tools/mcp with authentication Header Auth, name x-settled-pass, and every tool is available. Or import a ready-made workflow (n8n: Add workflow → Import from URL):
- Check an x402 endpoint with Settled before your agent pays: a chat agent with the Settled tools and the decision rules from the skill.
- Settled change feed to Discord or Slack: polls
/v1/eventsevery 15 minutes and posts venue verdict flips, new honeypots and integrity changes to a webhook. - Daily Settled check of your own x402 endpoints: for sellers; runs each listed endpoint through the free check and posts a digest only when something needs attention.
- Pay for an x402 API from n8n through the Settled proxy: n8n pays x402 endpoints without ever holding the wallet key (below).
Paying from n8n
A wallet key kept in n8n can be read by more than the workflow that uses it: an environment variable by any workflow on the instance, a Code node by anyone who can open it, and a community node that signs payments runs with full access. So the key stays out of n8n. The settled-x402 payment proxy holds it in one small process beside n8n: a workflow posts the request it wants made to POST /pay with a token, and the proxy checks the quote with Settled, holds it to your limits (a cap per call, a daily budget, the hosts you allow) and only then signs. It hands back the answer with the payment and the verdict, and screens the answer for instructions aimed at an agent. Whoever gets the token can spend up to your limits; whoever gets the key could take the wallet, so the wallet is one for this proxy only, holding a small float of USDC.
mkdir -p ~/.settled-x402 && (umask 077; openssl rand -hex 32 > ~/.settled-x402/proxy-key) npx -y -p settled-x402 -p @x402/fetch@2 -p @x402/evm@2 -p viem@2 settled-x402 proxy --max-usd-per-call 0.25 --daily-budget-usd 5
The proxy prints the wallet's address (send it a few dollars of USDC on Base; it needs no ETH) and its token. In the template, give Pay Through Settled Proxy a Header Auth credential (name Authorization, value Bearer <token>) and put the endpoint in Request to Pay For. It answers 200 with json or body, paid, payment.tx, settled (verdict, price, payTo) and screen; a refusal is 403 with blocked_by (verdict, limit, loadout, client_cap or screen) and the reason, before anything is signed except for screen. n8n in Docker Desktop reaches it at http://host.docker.internal:4021; with docker compose, run it as a service on n8n's network (the compose file is in the loadout's n8n kit). Every flag: the package README.
Call it over HTTP
GET https://settled.tools/v1/preflight?url=https://api.example.com/search # $0.005, pays over x402
GET https://settled.tools/v1/check?url=https://api.example.com/search # $0.002
GET https://settled.tools/v1/free/check?url=https://api.example.com/search # free: 25 a day, 300 with a payer record
GET https://settled.tools/v1/peek?url=https://api.example.com/search # free
GET https://settled.tools/v1/deliveries # free, every scout purchase
GET https://settled.tools/discovery/resources # free, vetted endpoints in the Bazaar discovery format
GET https://settled.tools/v1/income/venues # free
GET https://settled.tools/v1/events # free
POST https://settled.tools/v1/watch {"url": "..."} # $2, 30 days; add "webhook" to get pushes; /v1/watch/pack: 10 endpoints for $10
POST https://settled.tools/v1/pass/month # $1, the pass for 30 days (the day pass is $0.05); /v1/pass/year $10
POST https://settled.tools/v1/watch {"watch_id": "..."} # $1, 10 more days, same feed
GET https://settled.tools/v1/watch/{id}/alerts?since=0 # free, poll for alerts
Standard x402 clients cap a single payment at $1 by default (spendControls.maxAmountPerPayment in @x402/core). The Watchdog ($1) fits under it; raise it to buy a seller re-test ($2).
Paid routes answer 402 with a PAYMENT-REQUIRED header; any x402 client (@x402/fetch, Coinbase AgentKit, the Cloudflare Agents SDK, OpenClaw's x402 skill) pays and retries. The full route list is in llms.txt and openapi.json; Settled's own routes are also in the CDP x402 Bazaar.
The verdict in the x402 Foundation’s verifier schema
Every check answer carries verifier: the same finding in the shape the x402 Foundation’s Domain Discovery working group is drafting for third-party verifiers, so a client written to the draft reads Settled without a Settled-specific parser. verdict (true, false or inconclusive), a reason from the draft’s closed set, evidence as the strongest level reached (purchase when the scout bought and got content back, probe, none), the quote’s digest, and an attestation with the key URL, a signed record of this exact verdict, the two domains compared, valid_until and a relationship disclosure. method_digest is the sha256 of the method document; /.well-known/x402-verifier lists the key, the method and its digest.
GET https://settled.tools/v1/free/check?url=https://api.example.com/search # → answer.verifier GET https://settled.tools/v1/verifier/records/vr_… # the signed record named in attestation.record_url
Discovery feed
GET /discovery/resources lists the x402 endpoints Settled has checked, in the format x402 Bazaar discovery clients already read: {x402Version, items, pagination}. It's free and cached for 10 minutes. An endpoint is listed only if it was live when Settled last probed it, within the last 3 days; it quotes a payable price in USDC; the scout's last test purchase from it, if any, didn't fail; and it isn't flagged as a clone farm or an unresolved URL template. Endpoints the scout has bought from and got content come first, then by quality score. Each item's metadata.settled carries the evidence and a link to the full check.
GET https://settled.tools/discovery/resources?limit=100&offset=0 GET https://settled.tools/discovery/resources?network=base&q=weather
Any client that reads a facilitator's discovery list can point at https://settled.tools. Coinbase AgentKit 0.10's discover_x402_services takes the URL as its facilitator. AgentKit versions with registeredFacilitators need it registered first, x402ActionProvider({ registeredFacilitators: { settled: 'https://settled.tools' } }), after which the agent asks for settled.
Payer record: proof your wallet pays
Sellers that ask agents for proof with x401 (spec) can ask for a payer record: a credential Settled signs for your wallet's owner saying how the wallet has paid x402 sellers in the last 30 days, as Settled saw it on Base. It states facts, not creditworthiness: days with a payment (3, 7 or 14 or more), USDC paid ($1, $10 or $100 or more), independent sellers paid (5 or 10 or more), not on the sanctions list, no circular flows, and the month of the first payment Settled saw. The facts are thresholds over USDC transfers Settled's ledger saw into indexed sellers' wallets: a day counts for a seller once the wallet sent it $0.001 or more (for days recorded since October 14, 2026, only transfers that match a price the seller quotes), and a seller is independent once 10 other wallets have each paid it that much on some day. They do not prove the payers are unrelated to the seller, and the lowest thresholds are cheap to meet; sellers that need more ask for the higher facts. It is an SD-JWT VC, so you show each seller only the facts it asks for. A record lasts 7 days. Free until January 11, 2027. From then a record costs $0.10, paid over x402: after your wallet signs, the same request answers 402, and anything that would refuse your wallet (no record, sanctions, circular flows, the limit of 3 a day) is refused before that, so a refusal costs nothing.
Ask with the wallet that pays, plus a P-256 key your agent keeps for showing credentials (a separate key: the payment key never signs these). The x402 wrapper below pays the 402 once records cost $0.10 and does nothing before then:
// npm i viem @x402/fetch @x402/evm
import { privateKeyToAccount } from "viem/accounts";
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
const wallet = privateKeyToAccount(process.env.WALLET_KEY);
const client = new x402Client();
registerExactEvmScheme(client, { signer: wallet });
const pay = wrapFetchWithPayment(fetch, client);
const holder = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
const { kty, crv, x, y } = await crypto.subtle.exportKey("jwk", holder.publicKey);
const ask = (body) => pay("https://settled.tools/v1/credentials/payer", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }).then((r) => r.json());
const first = await ask({ wallet: wallet.address, holder_jwk: { kty, crv, x, y } });
const signature = await wallet.signMessage({ message: first.message_to_sign });
const record = await ask({ wallet: wallet.address, holder_jwk: { kty, crv, x, y }, issued_at: first.issued_at, signature });
// record.credential: keep it with the holder key; record.claims lists what it can show
Settled gates its own free tier with it. An anonymous client, counted by address, gets 25 free calls a day; a client that shows a payer record is counted by wallet and gets 300 (and 150 endpoint searches instead of 50). An address is free to change, which is how one client took 437 free calls over 299 addresses in a week; a wallet with real x402 history is not. The free tier asks the record for two facts: paid x402 sellers on 3 or more of the last 30 days, and not on the sanctions list. A wallet that is newer than that has the 25, or a $0.05 pass. From the 15th anonymous call the answer carries an x401 PROOF-REQUEST header (draft 0.2.0), and so does the refusal at 25: show the two facts it asks for and retry with PROOF-RESPONSE:
const req = JSON.parse(Buffer.from(refusal.headers.get("proof-request"), "base64url"));
const { nonce } = req.credential_requirements.digital.requests[0].data; // unsigned OpenID4VP request, 5 minutes
const aud = "origin:https://settled.tools"; // the verifier, as OpenID4VP names it
const [jwt, ...discs] = record.credential.split("~").filter(Boolean);
const keep = discs.filter((d) => ["active_days_30d_over_3", "sanctions_clear"].includes(JSON.parse(Buffer.from(d, "base64url"))[1]));
const sdjwt = [jwt, ...keep].join("~") + "~";
const b64 = (o) => Buffer.from(JSON.stringify(o)).toString("base64url");
const sd_hash = Buffer.from(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(sdjwt))).toString("base64url");
const kb = b64({ alg: "ES256", typ: "kb+jwt" }) + "." + b64({ aud, nonce, iat: Math.floor(Date.now() / 1000), sd_hash });
const sig = Buffer.from(await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, holder.privateKey, new TextEncoder().encode(kb))).toString("base64url");
const result = b64({ credential_result: { protocol: "openid4vp-v1-unsigned", data: { vp_token: { payer_record: [sdjwt + kb + "." + sig] } } } });
// retry once with the proof (a Result Artifact) ...
await fetch(searchUrl, { headers: { "PROOF-RESPONSE": result } });
// ... or trade it for a token good for 24 hours (also works on /mcp/free, and as the payer_token tool argument through any gateway)
const { access_token } = await fetch(req.oauth.token_endpoint, { method: "POST", body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:token-exchange", subject_token_type: "urn:x401:params:oauth:token-type:result_artifact", subject_token: result }) }).then((r) => r.json());
await fetch(searchUrl, { headers: { authorization: "Bearer " + access_token } });
A failed proof answers 401 with a PROOF-RESULT header saying why and a fresh PROOF-REQUEST. Agents built on x401 draft 0.1.0 still work, though 0.1.0 is deprecated here: the same refusal carries PROOF-REQUIRED; answer with a VP Artifact {agent_id, challenge, vp_token} in PROOF-PRESENTATION, with your agent_id as the key-binding aud. Each 0.1.0 challenge is accepted once (a second presentation of it gets challenge_used), so trade the presentation for a token rather than resending it. What changed between the drafts, and how x401 sits next to x402: x401, explained.
Behind a shared address, or through a gateway
Many agents behind one address (an office, a carrier, a cloud region) would share one allowance, so the anonymous 25 grows with the sharing: 25 per distinct client (user agent) seen on the address that day, up to 300. The answer says free.shared_by_clients when that applies. A hosted MCP gateway that calls Settled from a Cloudflare Workers zone on behalf of many users can do better: forward each user's opaque id in the x-settled-end-user header and every user gets 25 of their own (up to 1,000 a day for the zone). And any user can keep their own 300 through any gateway without the gateway seeing their keys: get a payer record for the wallet (above), present it once a day to POST /x401/token against the nonce of any Settled PROOF-REQUEST (GET /x401/demo always returns one), take the access_token (24 hours, bound to the wallet), then pass it as the payer_token argument of settled_check, settled_find_endpoints or settled_events, or as Authorization: Bearer x4t_… if the gateway forwards headers. The token grants the gateway nothing but Settled's free tier for that wallet.
Selling an API and want to accept payer records? POST /v1/credentials/verify {presentation, aud, nonce} checks one for you: the signature, the facts shown, expiry, revocation and the key binding. Or let settled-x402 do the whole exchange: it sends the PROOF-REQUEST, checks the answer against your own nonce and origin, and asks Settled about the record:
// npm i settled-x402
import { requirePayerRecord } from "settled-x402/x401";
const gate = requirePayerRecord({ origin: "https://api.example.com", secret: process.env.X401_SECRET });
const proof = await gate(request); // a Fetch API Request, or Express req.headers
if (!proof.ok) return proof.response; // 401 with PROOF-REQUEST and, on a bad proof, PROOF-RESULT
// proof.wallet and proof.claims: active_days_30d_over_3 and sanctions_clear are true
A wallet qualifies once it has paid at least one independent seller (10 other wallets that each paid it $0.001 or more on some day, not a clone farm, on hold or sanctioned, and no payment back) $0.001 or more on some day of the nightly 30-day record. Settled answers 503 and issues nothing while its copy of the OFAC SDN list is missing or older than 3 days (sanctions_unavailable) or while the nightly record is more than 2 days stale (record_stale); a refusal never costs anything. Revoke your records any time with POST /v1/credentials/payer/revoke, signed the same way. Sellers check a record offline against the key at /.well-known/jwt-vc-issuer and the status list; what each claim means is at /vc/payer-record/v1. What Settled keeps: privacy.
Every answer is signed
Responses carry an attestation: keccak256 of the canonical JSON, signed EIP-191 by the published signer. Recover the signer with any EVM library, or POST the response to /v1/verify. The whole index is snapshotted daily, hash-chained and signed at /v1/snapshots/latest, so what Settled said on any day can be proven later.
What you pay is signed too, in effect: every 402 quote from settled.tools names 0xb92bb76e3c5575160a2a561913047727d33af9a6 as payTo, the wallet behind the Basename getsettled.base.eth. A quote naming any other address is not Settled's. The same wallet owns Settled's ERC-8004 agent #98131 on Base (registration file: /.well-known/erc8004.json).
What the words mean
Payability: delivered (the scout's last purchase returned usable content and nothing in it broke the listing) · payable (valid 402 on the verb that answers) · unpriced · malformed_402 · cannot_pay_either_verb · free · auth_gated · unreachable. Delivery checks (checks.verdict on each purchase): as_advertised · not_as_advertised · disclosed_problem · partial_match · unverified · nothing_to_compare · not_delivered; llms.txt explains each. Venue verdicts: paying · paying_small · measuring · no_payouts_seen · closed_to_agents · defunct · unmeasured. Integrity: organic · concentrated · single_source · circular.
Best-effort observational data, not financial advice; every label can be disputed by messaging @settledfyi on X or in Discord (#support; alerts and the weekly report are mirrored there). Crawlers: /bot. Weekly reports: /reports · /observatory. Venues: /venues.