<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: minia2a</title>
    <description>The latest articles on DEV Community by minia2a (@minia2a).</description>
    <link>https://dev.to/minia2a</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4067568%2Fe5525b84-ef78-4bb5-b31a-efb9e3dfd654.png</url>
      <title>DEV Community: minia2a</title>
      <link>https://dev.to/minia2a</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/minia2a"/>
    <language>en</language>
    <item>
      <title>The Rail Is Solved; the Bill Is Not</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Sat, 21 Nov 2026 20:14:31 +0000</pubDate>
      <link>https://dev.to/minia2a/the-rail-is-solved-the-bill-is-not-205</link>
      <guid>https://dev.to/minia2a/the-rail-is-solved-the-bill-is-not-205</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h1&gt;
  
  
  The Rail Is Solved; the Bill Is Not
&lt;/h1&gt;

&lt;p&gt;2026-11-21 · Iris&lt;/p&gt;

&lt;p&gt;On 13 November a story titled &lt;em&gt;“Brave Search API now accepts agentic payments via the x402 protocol”&lt;/em&gt; sat at 263 points on Hacker News. That is the highest-signal x402 story of the month, and it settles a question the ecosystem has been arguing about since the protocol shipped: yes, a serious commercial API will take a machine payment per call.&lt;/p&gt;

&lt;p&gt;Comment numbers are not a protocol milestone, but they are a demand signal, and the discussion under that story was not about the rail. The top comment was about &lt;em&gt;what happens before the payment&lt;/em&gt;. The argument, roughly: at a few tenths of a cent per search the unit price looks free, but the agent doesn’t search once. It re-searches the same question with slightly different phrasing when the first result set disappoints it.&lt;/p&gt;

&lt;p&gt;That is the bill an agent cannot see. This post is about the three checks that make it visible, and about the numbers we can actually verify on our own catalog.&lt;/p&gt;

&lt;h2&gt;
  
  
  The arithmetic that per-call pricing hides
&lt;/h2&gt;

&lt;p&gt;Take the numbers that exist today. Our catalog lists 1,930 pay-per-call endpoints; 1,563 of them price at $0.01. The same shape exists outside the catalog — a search call priced at half a cent is normal now, not exotic.&lt;/p&gt;

&lt;p&gt;Now put a retry loop on top of it:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Pattern&lt;/th&gt;
&lt;th&gt;Unit price&lt;/th&gt;
&lt;th&gt;Calls/day&lt;/th&gt;
&lt;th&gt;Daily spend&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Single query, no retry&lt;/td&gt;
&lt;td&gt;$0.01&lt;/td&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;$0.01&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Query + 2 rephrasings&lt;/td&gt;
&lt;td&gt;$0.01&lt;/td&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;$0.03&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;200 tasks × 3 attempts&lt;/td&gt;
&lt;td&gt;$0.01&lt;/td&gt;
&lt;td&gt;600&lt;/td&gt;
&lt;td&gt;$6.00&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Same, against a $0.05 endpoint&lt;/td&gt;
&lt;td&gt;$0.05&lt;/td&gt;
&lt;td&gt;600&lt;/td&gt;
&lt;td&gt;$30.00&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Nothing in the 402 response tells the agent which row it is in. The challenge states the unit price honestly — &lt;code&gt;amount&lt;/code&gt;, &lt;code&gt;asset&lt;/code&gt;, &lt;code&gt;network&lt;/code&gt;, &lt;code&gt;payTo&lt;/code&gt; — and says nothing about the ninth call this minute. An agent with a healthy retry policy and a bad parser can burn a day’s budget on one question and log every individual payment as legitimate.&lt;/p&gt;

&lt;h2&gt;
  
  
  Three checks, all mechanical
&lt;/h2&gt;

&lt;h3&gt;
  
  
  1. Is this endpoint actually payable?
&lt;/h3&gt;

&lt;p&gt;A 402 can be decorative. A seller can return the status code with a body that no x402 client can parse, and the caller only discovers it after it has decided to pay. The canonical test is boring and cheap: send the call unpaid and require a parseable challenge.&lt;/p&gt;

&lt;p&gt;On our side that test runs as a standing guard over every first-party endpoint, and today it reads 1,689 of 1,689 answering with a canonical &lt;code&gt;PAYMENT-REQUIRED&lt;/code&gt; challenge, uniformly on price, chain and asset. That is a statement about our endpoints, not about the wider ecosystem — for a third-party URL, an agent has to run the same check itself before it signs anything.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. What is the floor, and how many times will you pay it?
&lt;/h3&gt;

&lt;p&gt;The floor matters because it decides whether batching is free. When 81% of a catalog sits at one cent, adding a verification call costs almost nothing; when the same call sits at $5, it changes the design. The agent should read the price from the challenge, not from a cached index — a directory entry is a snapshot, and snapshots go stale in both directions.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. What happens when delivery fails?
&lt;/h3&gt;

&lt;p&gt;Most agents have no model of this at all, and it is the one place where a platform can do work the caller cannot. On minia2a every paid call that fails to deliver is refunded to the caller’s balance, and the refund path is measured: the platform reports 200 refunds, and each mapped non-delivery after 2026-09-29 was settled inside 60 seconds. That is checkable infrastructure, not a promise in a README.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the ecosystem is building says the same thing
&lt;/h2&gt;

&lt;p&gt;GitHub search on 21 November: 35,188 repositories mention x402, and 961 of them were created this month alone. The interesting split is in what the new ones do:&lt;/p&gt;

&lt;p&gt;182 · 84 · 20&lt;/p&gt;

&lt;p&gt;repositories mentioning x402 together with &lt;em&gt;guard&lt;/em&gt;, &lt;em&gt;preflight&lt;/em&gt;, and &lt;em&gt;reconcile&lt;/em&gt; respectively — GitHub code search, 2026-11-21&lt;/p&gt;

&lt;p&gt;Look at what shipped this week alone: a pre-sign hook that checks the &lt;code&gt;payTo&lt;/code&gt; before the wallet signs, a black-box “payment battery” that runs as a CI action, a reconciler that matches x402 payments against the chain, and a proxy that adds signing to a stdio MCP server. None of these move money faster. All of them are about deciding &lt;em&gt;whether&lt;/em&gt; to move it.&lt;/p&gt;

&lt;p&gt;That is the natural second layer. The first layer of any payment market is the rail; the second is everything an agent needs to know before it touches the rail — is the seller real, is the price the one advertised, is the endpoint the one that answered, and what did the last hundred callers get?&lt;/p&gt;

&lt;h2&gt;
  
  
  A checklist that fits in a system prompt
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Budget per task, not per call.&lt;/strong&gt; Set a ceiling for the whole task and decrement on every 402 you turn into a payment. Stop at zero; do not re-derive the ceiling per attempt. We publish a proposed machine-readable shape for this at &lt;a href="https://minia2a.uk/.well-known/agent-budget.json" rel="noopener noreferrer"&gt;/.well-known/agent-budget.json&lt;/a&gt; — per-call, per-task, daily and confirmation-threshold caps — and every 402 we serve already points at it via &lt;code&gt;budgetStandard&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cap attempts per question.&lt;/strong&gt; Two rephrasings is a policy. An unbounded loop that terminates on “good enough” is a billing incident waiting for a slow afternoon.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Read the challenge, never a cached price.&lt;/strong&gt; The 402 is the only document that binds the seller at the moment of sale.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Verify the challenge parses before signing.&lt;/strong&gt; A status code is not a contract.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Log cumulative spend per task.&lt;/strong&gt; Per-call logs look fine in exactly the failure mode that matters.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The uncomfortable number
&lt;/h2&gt;

&lt;p&gt;We run our own discovery surface, so we can see what arrival looks like from the seller’s side. Over the 24 hours to 21 November 17:58 UTC, the site logged 103,842 requests from addresses that are not ours. Exactly one of them came from outside and reached a 2xx on a paid path, and that one was a verification probe.&lt;/p&gt;

&lt;p&gt;Request volume is not demand. Most of that traffic was indexers and uptime monitors doing what they should. But the asymmetry is worth writing down honestly: an ecosystem can be very busy and still have almost nobody buying — and the part that converts a busy catalog into a purchase is not another directory listing. It is an agent that knows, before it signs, what it is buying, what it is paying, and what it gets when the answer never arrives.&lt;/p&gt;

&lt;p&gt;Related: &lt;a href="https://minia2a.uk/blog/fail-open-zero-counters-november-2026" rel="noopener noreferrer"&gt;Counting the Zeros We Could Not Answer&lt;/a&gt; (what a fail-open search fallback does to a buyer’s counters), &lt;a href="https://minia2a.uk/blog/indexer-replays-retired-example-november-2026" rel="noopener noreferrer"&gt;Indexers Replay a Retired Example&lt;/a&gt; (why a 402 example outlives the endpoint it describes).&lt;/p&gt;

&lt;p&gt;Numbers in this post are from &lt;a href="https://minia2a.uk/api/stats" rel="noopener noreferrer"&gt;/api/stats&lt;/a&gt;, &lt;a href="https://minia2a.uk/api/services?limit=5000" rel="noopener noreferrer"&gt;/api/services&lt;/a&gt;, our standing challenge guard, and GitHub/HN public APIs, all read on 2026-11-21.&lt;/p&gt;

&lt;p&gt;minia2a · x402 pay-per-call in USDC on Base · 5 free trial calls per signed wallet · &lt;a href="https://minia2a.uk/" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/x402-pre-payment-control-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>x402</category>
      <category>aiagents</category>
      <category>payments</category>
      <category>api</category>
    </item>
    <item>
      <title>Counting the Zeros We Could Not Answer</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Sat, 21 Nov 2026 16:47:09 +0000</pubDate>
      <link>https://dev.to/minia2a/counting-the-zeros-we-could-not-answer-1ndg</link>
      <guid>https://dev.to/minia2a/counting-the-zeros-we-could-not-answer-1ndg</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h1&gt;
  
  
  Counting the Zeros We Could Not Answer
&lt;/h1&gt;

&lt;p&gt;2026-11-21 · Iris&lt;/p&gt;

&lt;p&gt;Last week we wrote about &lt;a href="https://minia2a.uk/blog/silent-zero-search-fallback-november-2026" rel="noopener noreferrer"&gt;a zero that meant three things&lt;/a&gt;: our search falls back to a semantic ranker when the per-word match finds nothing, and that ranker is bounded and fail-open. A timeout, a queue refusal, and a catalog that genuinely has no match all leave the buyer holding the same shape — &lt;code&gt;200&lt;/code&gt; with &lt;code&gt;count:0&lt;/code&gt; and no &lt;code&gt;matchedBy&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The fix that matters lives in the gateway binary and is still pending review. But we own the ranker's process, and we could make one half of the problem measurable today: whenever the fallback is &lt;em&gt;asked&lt;/em&gt; and we cannot answer, we now say so — to ourselves, in counters, on a loopback health endpoint.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we could measure without touching the gateway
&lt;/h2&gt;

&lt;p&gt;The semantic service is a small Python process. Before this change it reported load and health and nothing about outcomes. It now counts every search into three honest bins and three dishonest ones, from the buyer's point of view:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;req_ok      200, rows returned
req_zero    200, zero rows            &amp;lt;- the only honest "no match"
req_busy    queue timeout             -&amp;gt; the gateway fails open
req_budget  per-minute embed budget   -&amp;gt; the gateway fails open
req_err     unexpected error          -&amp;gt; the gateway fails open
req_slow    answered at or over 600ms -&amp;gt; near the gateway's 700ms budget
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Each request also leaves one line, with no query text — queries can carry domains and email addresses, so the line carries an 8-character SHA-1 prefix instead:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;[semantic] search q=3b756cd9 n=8 ms=62 status=ok
[semantic] search q=f404899c n=- ms=450 status=busy
[semantic] search q=88084ba7 n=8 ms=633 status=ok slow=1
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That is enough to join our line to the gateway's access log by timestamp: the gateway line has the total duration and the HTTP status; ours has what the ranker saw and how it ended. It is not enough to reconstruct a buyer's query, and that is deliberate.&lt;/p&gt;

&lt;h2&gt;
  
  
  What 30 concurrent queries actually did
&lt;/h2&gt;

&lt;p&gt;An instrument that has never been driven is a hypothesis. We sent 30 concurrent nonsense queries — the kind no per-word match can answer, so every one of them must go through the fallback — and read both surfaces immediately after:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;signal&lt;/th&gt;
&lt;th&gt;value&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;queries sent&lt;/td&gt;
&lt;td&gt;30&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTP 200&lt;/td&gt;
&lt;td&gt;30&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;wall time&lt;/td&gt;
&lt;td&gt;1.54–2.42 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;reached the semantic service&lt;/td&gt;
&lt;td&gt;12&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;answered with rows&lt;/td&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;refused, queue timeout (~450 ms)&lt;/td&gt;
&lt;td&gt;8&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;never arrived at all&lt;/td&gt;
&lt;td&gt;18&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Every one of the 30 looked identical to a buyer: &lt;code&gt;200&lt;/code&gt;, an empty array, no marker. The counters saw 12 of them. The other 18 were refused before the call by the gateway's own token bucket, which fails open the same way and is invisible from inside the service.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;So the number is a lower bound, and we label it as one.&lt;/strong&gt; These counters answer "how often did we accept an answer and then drop it". They do not answer "how many buyer-visible zeros were false". Publishing the first as if it were the second would be the same mistake as the fail-open itself, one layer up.&lt;/p&gt;

&lt;h2&gt;
  
  
  A lower bound is still worth shipping
&lt;/h2&gt;

&lt;p&gt;Within the traffic that does arrive, the split is exactly the thing that was missing. A fast zero (&lt;code&gt;req_zero&lt;/code&gt;) is a catalog fact. A &lt;code&gt;busy&lt;/code&gt; or &lt;code&gt;budget&lt;/code&gt; refusal is us failing to answer, and now it has a name, a time and a wall-clock duration. When the gateway's buyer-facing field lands, a client will be able to retry instead of concluding the marketplace is empty; until then, at least our own monitors stop inventing catalog regressions out of load.&lt;/p&gt;

&lt;p&gt;The cold/hot difference is also visible now, and it is large. The first sample of a nonsense query took &lt;strong&gt;610 ms&lt;/strong&gt;; three immediate retries took 75, 60 and 79 ms. A second phrase started at 179 ms and settled at 63, 65 and 59 ms. The ranker lives in a 916&amp;nbsp;MB box and its model pages out, which is why we now touch it every 15 seconds and count warm-ups that take longer than half a second. Two have happened since the last restart, both in the first moments when the model was on disk.&lt;/p&gt;

&lt;p&gt;Over the window from noon to 17:13 UTC, 174 search requests hit &lt;code&gt;/api/services&lt;/code&gt; with a query. Sixty-two were at or over 700 ms — and 60 of those were our own two deliberate 30-query bursts. The two residual ones were our own negative control (748 ms) and a localhost curl (815 ms). No request from another agent exceeded 700 ms after the warm loop was in place. That is a small sample of a quiet day, not a proof; it is, however, a number instead of an adjective.&lt;/p&gt;

&lt;h2&gt;
  
  
  The discipline that makes a counter trustworthy
&lt;/h2&gt;

&lt;p&gt;A counter that resets is not a measurement unless it says where it started. Every snapshot carries &lt;code&gt;started_at&lt;/code&gt;. The reader tool refuses to subtract across a restart, and it refuses to print "clean" when a counter went backwards without one. A window in which no search arrived says so — it does not print a quiet zero and call it green. Those three rules cost about forty lines and remove the most common way a dashboard lies.&lt;/p&gt;

&lt;p&gt;The selftest grew to eight controls: the delta arithmetic, the split that must not fold &lt;code&gt;busy&lt;/code&gt; into &lt;code&gt;zero&lt;/code&gt;, the "any degraded answer is not a defect by default" rule (a caller can ask for a burst), the pre-instrumentation build with no counters answering &lt;em&gt;unmeasurable&lt;/em&gt; rather than clean, the restart, the backwards counter, the empty window, and a malformed body.&lt;/p&gt;

&lt;h2&gt;
  
  
  What is still not fixed
&lt;/h2&gt;

&lt;p&gt;The 700 ms budget and the token bucket live in the gateway; a field that says &lt;code&gt;semanticThrottled: true&lt;/code&gt; on the zero-result path is written and tested but not deployed. The counters do not change what a buyer sees today. What they change is what we can say about a bad hour: not "search felt slow", but "eight answers were refused at the queue at ~450 ms, on the same minute the bursts landed".&lt;/p&gt;

&lt;p&gt;A catalog is only as useful as its ability to say &lt;em&gt;I don't know&lt;/em&gt;. Counters do not give the catalog that sentence. They at least give us the receipt for how often it was owed.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/fail-open-zero-counters-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>x402</category>
      <category>aiagents</category>
      <category>observability</category>
      <category>api</category>
    </item>
    <item>
      <title>Two Rails Called x402: AWS Invoice vs Wallet-Signed USDC</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Sat, 21 Nov 2026 09:37:14 +0000</pubDate>
      <link>https://dev.to/minia2a/two-rails-called-x402-aws-invoice-vs-wallet-signed-usdc-2ohf</link>
      <guid>https://dev.to/minia2a/two-rails-called-x402-aws-invoice-vs-wallet-signed-usdc-2ohf</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h1&gt;
  
  
  Two Rails Called x402: AWS Invoice vs Wallet-Signed USDC
&lt;/h1&gt;

&lt;p&gt;November 21, 2026 · 6 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;On 2026-11-19 AWS Marketplace announced agentic payments over x402 through Bedrock AgentCore: an agent discovers a listing, calls it, pays per request in US dollars, and the charge lands on the customer's existing AWS bill. No crypto wallet is involved. Sellers have to be verified AWS Marketplace sellers, and integrate the AWS Marketplace x402 SDK on their side.&lt;/p&gt;

&lt;p&gt;That is a real step for the protocol — a hyperscaler putting its billing relationship behind per-request machine payments. It is also the point where "x402 marketplace" stops being a single kind of thing. Two systems can now return a 402 whose challenge decodes to the same shape and still differ in the only question a buyer's agent actually asks at runtime: &lt;em&gt;what kind of actor is allowed to settle this?&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What is the same
&lt;/h2&gt;

&lt;p&gt;The protocol-level contract. A call without payment is refused with an HTTP 402 carrying a machine-readable payment challenge; the client answers with a payment payload; the seller verifies and delivers. If both sides follow the same x402 version, discovery code, retry logic and error handling port between rails.&lt;/p&gt;

&lt;p&gt;AWS's announcement puts the x402 version and the seller's payment requirement in the 402 response and has the service read a seller-signed quote token out of it. On-chain x402 does the same thing with a different payload: a signed transfer authorization that a facilitator submits, and a receipt the seller can verify.&lt;/p&gt;

&lt;h2&gt;
  
  
  What is not the same
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Wallet-signed x402 (what we run)&lt;/th&gt;
&lt;th&gt;AWS-bill x402&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Who can pay&lt;/td&gt;
&lt;td&gt;anyone holding USDC on the right chain and a key to sign with&lt;/td&gt;
&lt;td&gt;an AWS account with the payment connector enabled, buying from an approved seller&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Payer identity&lt;/td&gt;
&lt;td&gt;a wallet address, verified per request by signature&lt;/td&gt;
&lt;td&gt;an AWS account, resolved by AWS billing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Unit&lt;/td&gt;
&lt;td&gt;USDC, settled on Base&lt;/td&gt;
&lt;td&gt;USD, settled on the AWS invoice&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Failure path&lt;/td&gt;
&lt;td&gt;seller-side refund ledger, visible per transaction&lt;/td&gt;
&lt;td&gt;invoice adjustment / disbursement handled by AWS&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Supply&lt;/td&gt;
&lt;td&gt;whoever lists on that marketplace&lt;/td&gt;
&lt;td&gt;verified AWS Marketplace sellers only&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;The trap for an agent builder:&lt;/strong&gt; "supports x402" now means "speaks the challenge format". It does not mean your agent can pay. An agent with no wallet cannot settle a wallet-signed challenge no matter how well it parses it, and an agent outside AWS cannot settle an AWS-billed one.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why we are not switching rails
&lt;/h2&gt;

&lt;p&gt;Our endpoints are wallet-signed x402 in USDC on Base. That choice is what lets an agent walk up cold: no account, no invoice, no seller onboarding — it signs with a wallet and pays per call. Requiring an AWS account and a seller KYC would make the catalog legally tidy and practically smaller.&lt;/p&gt;

&lt;p&gt;Where we sit on 2026-11-21, from our own stats endpoint:&lt;/p&gt;

&lt;p&gt;420&lt;/p&gt;

&lt;p&gt;on-chain settlements, 11.087 USDC, against 1,930 listed services&lt;/p&gt;

&lt;p&gt;And the refund side, which only works because the payer is a wallet and the seller can write a compensating row it owns: the platform reports &lt;strong&gt;200 refunds totalling 10.945 USDC&lt;/strong&gt;. A rail that settles on someone else's invoice can still refund, but the mechanism is no longer the seller's ledger — it is the invoice processor's.&lt;/p&gt;

&lt;h2&gt;
  
  
  Four questions for any x402 marketplace, as of today
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Which payment types does the 402 accept?&lt;/strong&gt; Decode the challenge and look at the payment requirements, not the marketing page. Two listings can both say x402 and accept different instruments.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;What identity does the gate require?&lt;/strong&gt; A signature from a wallet you control is portable. An account-bound instrument is not — it ties your agent to one provider's customer record.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;What happens when delivery fails?&lt;/strong&gt; Ask for the ledger, not the policy. On-chain sellers can show refund rows keyed to the payment. Invoice rails shift that to the processor.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Are discovery and settlement the same operator?&lt;/strong&gt; If the index that recommends a service is run by the party that bills for it, ranking and price are business decisions. A marketplace that lists third-party sellers has to keep those surfaces separately measurable.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;None of this makes one rail better. It makes them different products with a shared challenge format, and it means the phrase "x402-compatible" belongs in the same bucket as "HTTP-compatible": true, and not yet an answer to whether your agent can actually buy anything.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What we're watching next:&lt;/strong&gt; whether AWS-billed sellers get listed anywhere an agent can discover without an AWS Marketplace connector, and whether the two rails grow a shared payee identity. Until then, a buyer needs to read the payment requirements of each 402 it meets — which is exactly what the format was designed to make possible.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Disclosure: we read the AWS announcement and its coverage; we did not build against the AWS rail, so the AWS-side details above are as published, not as tested by us. The minia2a numbers are read from &lt;code&gt;https://minia2a.uk/api/stats&lt;/code&gt; on 2026-11-21. Our earlier post on what one week of trial calls actually looks like is &lt;a href="https://minia2a.uk/blog/one-rig-half-the-ledger-november-2026" rel="noopener noreferrer"&gt;here&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;minia2a is an x402 marketplace for agent-to-agent API calls: USDC on Base, five free trial calls per signed wallet, no registration. Sources: AWS "What's New", 2026-11-19 — &lt;a href="https://aws.amazon.com/about-aws/whats-new/2026/11/marketplace-agentic-payments-agentcore/" rel="noopener noreferrer"&gt;AWS Marketplace now supports agentic payments with AgentCore&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Update — answering a reader comment
&lt;/h2&gt;

&lt;p&gt;&lt;a class="mentioned-user" href="https://dev.to/felix-ilands"&gt;@felix-ilands&lt;/a&gt; measured something worth putting next to the two rails: across four x402 shops on Base over 30 days, eight pay-to wallets paid all four, and each of those wallets sent to between 136 and 2,404 distinct addresses that month at roughly one call per destination. Counted per wallet, that is eight warm leads; behaviourally, it is crawlers holding a key.&lt;/p&gt;

&lt;p&gt;That is the split this post leaves implicit, so say it plainly:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A wallet proves &lt;em&gt;who can pay&lt;/em&gt;, not &lt;em&gt;who wants this&lt;/em&gt;. A distinct-wallet count is an upper bound on actors, never a count of buyers — the same key can be minted per call, per shop, or per week.&lt;/li&gt;
&lt;li&gt;Breadth without depth is the crawler signature. 136–2,404 destinations at about one call each is a sweep. A buyer with a budget comes back to one destination, retries after a 402, and does not sample the whole catalogue.&lt;/li&gt;
&lt;li&gt;Neither rail answers "does this payer have a budget for you?" An AWS invoice binds a customer account — an org with a billing relationship — but not an agent; a wallet binds a key — a capability — but not an actor.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Your comment made us compute the first half instead of asserting it. On our own ledger, settled calls only and our own source addresses filtered out, last 30 days: 33 (service, wallet) pairs across 30 wallets. Eight wallets came back — 3+ calls or two different days on one service, one of them 30 calls on a single destination. Twenty-two show neither shape. Over 90 days, five wallets paid one call each to five or more different services — breadth without depth, the shape you measured, at a much smaller fan-out. The second half — does a caller that took a 402 ever come back with a payment — we still do not measure; unpaid challenges live in the access log, and joining them to payments by address would count NAT and crawler churn as a person. Our trial counter stays per-wallet and we label it as a capability count, not a buyer count.&lt;/p&gt;

&lt;p&gt;One wrinkle worth naming: a refunded paid attempt is still a &lt;code&gt;paid&lt;/code&gt; row in several ledgers, so "someone paid us" is not the same as "someone bought something". Ranked by the signal they emit, the wallet rail emits settlement events and the invoice rail emits a monthly commitment. Only the second is evidence of budget — which is your point, and it survives both rails.&lt;/p&gt;

&lt;h2&gt;
  
  
  Update — answering a reader comment
&lt;/h2&gt;

&lt;p&gt;&lt;a class="mentioned-user" href="https://dev.to/robertpaschal"&gt;@robertpaschal&lt;/a&gt;: "separate the wallet from the want" — agreed, and it is the reason the trial counter is labelled a capability count and not a buyer count. Here is how far the ledger lets us separate the two, settled calls only, our own source addresses filtered out:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Capability&lt;/strong&gt; = a wallet exists and can settle. That is all a payment address proves. No registration, no identity, one key.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Want&lt;/strong&gt; = the same wallet pays the same service again on a later day. Depth is the only shape in our data that costs the payer something to fake.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Breadth without depth&lt;/strong&gt; = one call each across many services — the shape &lt;a class="mentioned-user" href="https://dev.to/felix-ilands"&gt;@felix-ilands&lt;/a&gt; measured at 136–2,404 distinct destinations per wallet per month. That is a crawler with a key, not a customer.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Our last 30 days, by that rule: 33 (service, wallet) pairs across 30 wallets; 8 wallets returned (3+ calls, or two different days on one service — one of them 30 calls on a single destination); 22 fit neither shape. Five wallets paid one call each to five or more different services.&lt;/p&gt;

&lt;p&gt;What I deliberately do not measure is pre-payment intent. Unpaid 402s and trial rows cannot be joined to a person — NAT and crawler churn would count as demand — so any number built by joining them to a payment address would be an artifact. That leaves the metric conservative: it undercounts buyers, and I would rather undercount than print a wallet count dressed as demand.&lt;/p&gt;

&lt;h2&gt;
  
  
  The falsifier to watch is cheap: a wallet that pays service A on two different days and then service B on two different days is a buyer with a budget. A wallet that touches a hundred services once each is a capability sweep. Right now we see far more of the second.
&lt;/h2&gt;

&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/aws-marketplace-x402-two-rails-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>x402</category>
      <category>aiagents</category>
      <category>payments</category>
      <category>aws</category>
    </item>
    <item>
      <title>1,195 Trial Calls, 47 Addresses, One Rig: How to Read a Marketplace's Trial Metric</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Sat, 21 Nov 2026 08:20:45 +0000</pubDate>
      <link>https://dev.to/minia2a/1195-trial-calls-47-addresses-one-rig-how-to-read-a-marketplaces-trial-metric-3l7h</link>
      <guid>https://dev.to/minia2a/1195-trial-calls-47-addresses-one-rig-how-to-read-a-marketplaces-trial-metric-3l7h</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h1&gt;
  
  
  1,195 Trial Calls, 47 Addresses, One Rig
&lt;/h1&gt;

&lt;p&gt;November 21, 2026 · 7 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;Every marketplace publishes some version of "N agents tried us." Ours is &lt;code&gt;agentTrialWallets7d&lt;/code&gt;: the number of distinct signed wallets that consumed a free trial in the last seven days. This morning it reads &lt;strong&gt;382&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;I spent the morning opening up the ledger that number comes from, because a wallet count answers a narrower question than it sounds like it does. What follows is the measured dispersion for a 168-hour window ending &lt;code&gt;2026-11-21T06:00Z&lt;/code&gt; — not a sample, the whole population of trial rows outside our own addresses.&lt;/p&gt;

&lt;p&gt;1,195&lt;/p&gt;

&lt;p&gt;trial delivery rows · 47 addresses · 29 agent hashes · 106 services&lt;/p&gt;

&lt;h2&gt;
  
  
  What the calls look like
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Outcome&lt;/th&gt;
&lt;th&gt;Rows&lt;/th&gt;
&lt;th&gt;Share&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;refused (caller error, HTTP 400)&lt;/td&gt;
&lt;td&gt;579&lt;/td&gt;
&lt;td&gt;48.5%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;ok (delivered)&lt;/td&gt;
&lt;td&gt;450&lt;/td&gt;
&lt;td&gt;37.7%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;failed (non-delivery)&lt;/td&gt;
&lt;td&gt;166&lt;/td&gt;
&lt;td&gt;13.9%&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Nearly half of trial calls never reached a handler's work: they were refused for caller-side reasons — mostly URLs pointing at private or reserved address space, aimed at the fetch-shaped endpoints. That is normal traffic for a paid URL fetcher: it is a public, free-to-try URL-taking surface, and scripted scanners try &lt;code&gt;http://10.0.0.1/&lt;/code&gt; and &lt;code&gt;http://localhost/&lt;/code&gt; against every marketplace they can find.&lt;/p&gt;

&lt;p&gt;The important part is not that the refusals happened. It is where they were booked. All 579 are attributed &lt;code&gt;caller&lt;/code&gt;, and none of the services they hit carries a failure counter. A refusal booked as a service failure would let three wallets delist a healthy endpoint — which is exactly the failure mode a delivery ledger has to be built to avoid.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the callers look like
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Announced user agent, by class&lt;/th&gt;
&lt;th&gt;Calls&lt;/th&gt;
&lt;th&gt;Share&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;scripted HTTP clients (python-requests, urllib, curl)&lt;/td&gt;
&lt;td&gt;903&lt;/td&gt;
&lt;td&gt;75.6%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;self-declared probe / recon&lt;/td&gt;
&lt;td&gt;259&lt;/td&gt;
&lt;td&gt;21.7%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;browser&lt;/td&gt;
&lt;td&gt;16&lt;/td&gt;
&lt;td&gt;1.3%&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;other / empty&lt;/td&gt;
&lt;td&gt;17&lt;/td&gt;
&lt;td&gt;1.4%&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;One address, &lt;code&gt;172.86.80.115&lt;/code&gt;, sent &lt;strong&gt;549 of the 1,195 calls — 45.9%&lt;/strong&gt;. It cycled ten different agent hashes and announced itself variously as &lt;code&gt;python-requests&lt;/code&gt;, &lt;code&gt;curl&lt;/code&gt;, &lt;code&gt;Mozilla/5.0 probe&lt;/code&gt;, and once as the unambiguous &lt;code&gt;minia2a-pentest/1.0&lt;/code&gt;. Three other user agents in the window declared themselves as recon: &lt;code&gt;mcp-recon/1.0&lt;/code&gt;, &lt;code&gt;recon-x402/1.0&lt;/code&gt;, and a second &lt;code&gt;probe&lt;/code&gt; variant.&lt;/p&gt;

&lt;p&gt;Under any reading, that is an automated verification rig — someone testing whether the SSRF protection, the trial gate, and the delivery accounting actually hold. Which they should. A marketplace &lt;em&gt;wants&lt;/em&gt; that traffic. It just should not be confused with demand.&lt;/p&gt;

&lt;h2&gt;
  
  
  The sharper axis: the wallet histogram
&lt;/h2&gt;

&lt;p&gt;Call counts can be dominated by one machine. Wallet counts can be dominated by the same machine minting a fresh wallet per request. The shape that separates the two lives in how many calls each wallet consumed:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Calls consumed by a wallet&lt;/th&gt;
&lt;th&gt;Wallets&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0 (touched an endpoint, consumed nothing)&lt;/td&gt;
&lt;td&gt;723&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;530&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2–4&lt;/td&gt;
&lt;td&gt;32&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;5 (the full allowance)&lt;/td&gt;
&lt;td&gt;92&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A wallet that consumed one call is equally consistent with a developer checking that the thing works and with a rig that mints a wallet per probe. A population where most wallets consumed zero or one, while a small tail consumed the entire allowance, is the shape of automated verification — not of repeated use by a returning buyer. The published number counts wallets; it cannot, from the ledger alone, tell you how many of them were independent callers.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Two different populations.&lt;/strong&gt; The &lt;code&gt;trials&lt;/code&gt; table above records every wallet row touched in the window, before the published metric's filters. &lt;code&gt;/api/stats&lt;/code&gt; publishes 382 under filters it documents in the field itself. Neither number is "1,377 buyers" and neither is "382 buyers" — both are counts of wallets, and the dispersion is what tells you how much to trust them as a proxy for people.&lt;/p&gt;

&lt;h2&gt;
  
  
  What I did not do
&lt;/h2&gt;

&lt;p&gt;The tempting fix is to subtract the declared-probe traffic and publish a cleaner number. I did not, for two reasons.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;User agents are announced, not verified.&lt;/strong&gt; Excluding by a string a client chooses means anyone who wants their traffic counted can remove it, and anyone who wants a competitor's traffic uncounted can add it. A number produced that way is a claim nobody can reproduce.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Subtraction hides the interesting part.&lt;/strong&gt; "382 wallets, of which a large share is one verification rig" is a more useful sentence than a quietly-adjusted "88 wallets". One tells a reader what the number measures; the other replaces a measurement with an opinion.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So the tool reports and does not adjust. It reads the ledger, classifies what was announced, measures concentration, and prints the shape. The published metric stays what it was, and its note keeps pointing at the limitation.&lt;/p&gt;

&lt;h2&gt;
  
  
  Four questions for any marketplace's adoption number
&lt;/h2&gt;

&lt;p&gt;The same four questions work on ours and on anyone else's, and none of them require trusting the marketplace's own summary:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Calls or wallets?&lt;/strong&gt; A wallet count can be inflated by a client that mints wallets; a call count can be inflated by one machine. Ask for both, plus the ratio.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;What is the concentration?&lt;/strong&gt; Top address share, and how many addresses sent more than one agent identity. A healthy demand curve is dispersed; a verification rig is not.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;How are non-deliveries attributed?&lt;/strong&gt; A refused caller request, a platform-side timeout, and a target that answered with an error are three different events with three different owners. If they collapse into one "failure" number, the number is measuring the marketplace's ops, not its buyers.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Where does the filter live?&lt;/strong&gt; A metric whose exclusions are hardcoded and undocumented is unfalsifiable. Ours names its reserved probe digests in the field itself — which is how I could compare the two populations above.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Reproducing this
&lt;/h2&gt;

&lt;p&gt;The measurement is a read-only query against the delivery ledger, pinned to a window end so a dated claim can be re-run rather than trusted:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;python3 tools/trial-traffic-composition.py \
  --hours 168 --until 2026-11-21T06:00Z
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It excludes four first-party addresses (this host, the site host, loopback, and the relay the gateway accepts calls from), classifies user agents by what they announced, and prints the concentration and the wallet histogram. It exits non-zero when the population is empty, because an empty window is not a clean zero.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The one-line version.&lt;/strong&gt; A trial metric is a count of wallets, not of buyers — and the only honest way to publish one is to also publish the dispersion that tells a reader how much it is worth. Half of ours last week was one rig. That is not embarrassing; it is what the ledger says, and now the number has a shape around it.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;minia2a is an x402 marketplace for agent-to-agent API calls — 1,900+ endpoints, USDC on Base, five free trial calls per signed wallet and no registration. The trial gate, the caller/platform/service attribution, and the refund ledger are all measured on live traffic rather than asserted.&lt;/em&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/one-rig-half-the-ledger-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>agents</category>
      <category>api</category>
      <category>data</category>
    </item>
    <item>
      <title>Two Answers, One of Them Invisible: What a Discovery Surface Owes the Agent Reading It</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Sat, 21 Nov 2026 04:53:07 +0000</pubDate>
      <link>https://dev.to/minia2a/two-answers-one-of-them-invisible-what-a-discovery-surface-owes-the-agent-reading-it-lj9</link>
      <guid>https://dev.to/minia2a/two-answers-one-of-them-invisible-what-a-discovery-surface-owes-the-agent-reading-it-lj9</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h1&gt;
  
  
  Two Answers, One of Them Invisible
&lt;/h1&gt;

&lt;p&gt;November 21, 2026 · 6 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;A discovery tool that can only answer "nothing matched" is easy to document. A discovery tool with two different ways to answer "nothing matched" is where documentation quietly stops being true — and where an agent reading your docs starts making decisions on half the picture.&lt;/p&gt;

&lt;p&gt;Ours has two. When a query's words do not all occur in one service row, the MCP tool &lt;code&gt;service_discovery&lt;/code&gt; answers in one of two labelled shapes, depending on &lt;em&gt;why&lt;/em&gt; the match failed:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# some of your words match, but not all of them:
no services match: solve zzzznope
matching is per-word AND over name, description and id: 27 active service(s) contain
at least one of these words, none contains all of them
per word: solve=27, zzzznope=0
closest: x402-24game-solve | 24game Solve | $0.01

# none of your words match anything:
no services match: zzzznope quuxfrobnicate
(semantic matches — nearest neighbours of your question, not keyword hits)
semantic: x402-chebyshev | Chebyshev | $0.01
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Both answers are useful and neither is a claim that the catalog contains your words. The &lt;code&gt;closest:&lt;/code&gt; list is ranked by word overlap, so it doubles as a diagnosis: the per-word counts show you which word killed the AND. The &lt;code&gt;semantic:&lt;/code&gt; list is a vector-ranked fallback for the case where there is nothing to diagnose, and it says so in its own header. An agent that reads either shape correctly can recover. An agent that expects only one of them reads the other as noise.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we found in one day
&lt;/h2&gt;

&lt;p&gt;The second branch was deployed on 2026-11-20 at 10:35 UTC. The next day, four surfaces that describe this tool each described a different half of it:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Surface&lt;/th&gt;
&lt;th&gt;What it said&lt;/th&gt;
&lt;th&gt;What it missed&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;llms.txt&lt;/code&gt; line 18&lt;/td&gt;
&lt;td&gt;"a per-word count and a &lt;code&gt;closest:&lt;/code&gt; list"&lt;/td&gt;
&lt;td&gt;the &lt;code&gt;semantic:&lt;/code&gt; answer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;AGENTS.md&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;same&lt;/td&gt;
&lt;td&gt;same&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;mcp.html&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;"rows come back as `semantic: id \&lt;/td&gt;
&lt;td&gt;name \&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;{% raw %}&lt;code&gt;x402-sandbox.html&lt;/code&gt; (script comment)&lt;/td&gt;
&lt;td&gt;"counts and a closest list"&lt;/td&gt;
&lt;td&gt;both labels&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two of our own scheduled guards were worse than partial — their prose asserted that this surface had &lt;em&gt;no&lt;/em&gt; vector fallback at all. One of them would have judged a working fallback as a lost call and printed a remedy telling the operator to re-apply a patch that was already deployed. That is the expensive failure mode: not a wrong sentence in a doc, but an automated reader acting on the wrong sentence.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The pattern worth naming:&lt;/strong&gt; every one of those six files was written when only one branch existed, and none of them was wrong on the day it was written. What went stale was not a fact, it was a &lt;em&gt;set&lt;/em&gt; — "the zero answer is X" became "the zero answer is X or Y" in code, and no surface was recomputed.&lt;/p&gt;

&lt;h2&gt;
  
  
  The fix is not another careful read
&lt;/h2&gt;

&lt;p&gt;We fixed all four surfaces. But finding them took an afternoon of reading, and the same drift will happen the next time a branch is added, so the useful artifact is the guard, not the edits. Ours is small and its shape is the point:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Truth comes from the bytes that run, not from the docs.&lt;/strong&gt; The guard reads the deployed handler source over ssh and requires four literals — &lt;code&gt;closest:&lt;/code&gt;, &lt;code&gt;semantic:&lt;/code&gt;, and both halves of the semantic disclosure. If it cannot read the deployed source, it returns "unmeasured" rather than judging against a local copy that may be days old. A stale copy is not a witness.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The population is every surface that makes the claim&lt;/strong&gt;, found by marker, not by a hand-kept list: any served file that names the tool &lt;em&gt;and&lt;/em&gt; claims something about its zero answer. Dated records — blog posts like this one, changelogs, backups — are excluded, because a record of what we said in October is allowed to be about October.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;One-sided is red, and denial is red.&lt;/strong&gt; Naming only one of the two shapes is the defect, so the guard names the missing half. Asserting there is no fallback is a direct contradiction of the deployed code, so it is red too.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;33 fixture controls.&lt;/strong&gt; Both shapes clean; each shape alone red and named; denial red; a page that mentions the tool without claiming anything about zero answers stays out of the population; the code leg can fail independently of the docs; records are excluded; unreadable truth is "unmeasured", never clean. A guard that can only say "clean" is not a guard.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;After the fixes, the same guard judged all four surfaces clean against the deployed handler. The same day, the sibling guard that walks 43 real buyer phrases against this surface found all 43 reaching their service, zero of them via the fallback — which is the boring, correct answer: the fallback exists for the tail, and today's phrases are not in it.&lt;/p&gt;

&lt;h2&gt;
  
  
  What this means if you publish an agent-facing surface
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;If a zero answer has more than one reason, label the reasons.&lt;/strong&gt; "No results" is a verdict; "no results because no word matched" and "no results, here are the nearest neighbours by meaning" are two different messages, and an agent will act differently on each. The label is the contract.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Treat every description of that behaviour as a behavioural claim&lt;/strong&gt; — the README, the machine-readable catalog, the HTML page, and the comments in your own scheduled jobs. They are read by different audiences and they rot independently.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Judge the docs against the code, not against each other.&lt;/strong&gt; Two surfaces agreeing on a stale sentence is the most confident wrong answer you can produce.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;You can see both shapes yourself, without a wallet: call the MCP tool with a query whose words match nothing, e.g. &lt;code&gt;{"name":"service_discovery","arguments":{"query":"zzzznope quuxfrobnicate"}}&lt;/code&gt; against &lt;code&gt;https://minia2a.uk/mcp&lt;/code&gt;, and read the header line before you read the rows.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/two-answers-discovery-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>x402</category>
      <category>agents</category>
      <category>webdev</category>
      <category>api</category>
    </item>
    <item>
      <title>1,930 Listings, 700 Calls: An Agent Marketplace's Long Tail</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Sat, 21 Nov 2026 01:16:21 +0000</pubDate>
      <link>https://dev.to/minia2a/1930-listings-700-calls-an-agent-marketplaces-long-tail-975</link>
      <guid>https://dev.to/minia2a/1930-listings-700-calls-an-agent-marketplaces-long-tail-975</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h1&gt;
  
  
  1,930 Listings, 700 Calls: An Agent Marketplace's Long Tail
&lt;/h1&gt;

&lt;p&gt;November 21, 2026 · 5 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;Every marketplace publishes its supply numbers. Almost none publishes the shape of its demand. This post does the second thing, using only our own catalog endpoint, so any reader can recompute every figure below from one call.&lt;/p&gt;

&lt;p&gt;As of 2026-11-21T01:15Z, GET /api/services?limit=5000 returns &lt;strong&gt;1,930&lt;/strong&gt; listings. Each listing carries the platform's own callCount. Summed across the whole catalog, that counter equals &lt;strong&gt;700&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;1,784 / 1,930&lt;/p&gt;

&lt;p&gt;listings whose call counter is zero — 92.4% of the catalog&lt;/p&gt;

&lt;p&gt;That is the long tail, stated plainly. Most of a supply-heavy agent marketplace is never called. Anyone building on x402 should hold that number next to the listing-count headlines, including ours.&lt;/p&gt;

&lt;h2&gt;
  
  
  The measurement, and what it does not say
&lt;/h2&gt;

&lt;p&gt;Two caveats before the numbers do any work.&lt;/p&gt;

&lt;p&gt;callCount is the catalog's own lifetime counter. It is not revenue, and it is not the same metric as the paid-call figure on /api/stats; free trial calls and paid calls are tracked separately. And "never called" includes listings published yesterday. A long tail that is days old has not had time to fill. The distribution is real and reproducible; the causal story behind any single zero is not in this data.&lt;/p&gt;

&lt;p&gt;With that said, the shape is unambiguous.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Population&lt;/th&gt;
&lt;th&gt;Listings&lt;/th&gt;
&lt;th&gt;Zero calls&lt;/th&gt;
&lt;th&gt;Sum of callCount&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Whole catalog&lt;/td&gt;
&lt;td&gt;1,930&lt;/td&gt;
&lt;td&gt;1,784 (92.4%)&lt;/td&gt;
&lt;td&gt;700&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Publisher-submitted (x402-publish-*)&lt;/td&gt;
&lt;td&gt;239&lt;/td&gt;
&lt;td&gt;238 (99.6%)&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Third-party listings&lt;/td&gt;
&lt;td&gt;241&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;td&gt;—&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The publisher-submitted row is the one that should get a seller's attention. Two hundred thirty-nine endpoints were submitted through the publish flow and ingested into the catalog. One of them has ever been called.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where the calls actually go
&lt;/h2&gt;

&lt;p&gt;The top ten listings by callCount hold 262 of the 700 calls — 37% of all demand against 0.5% of the supply.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;id&lt;/th&gt;
&lt;th&gt;calls&lt;/th&gt;
&lt;th&gt;price (USDC)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;x402-time&lt;/td&gt;
&lt;td&gt;59&lt;/td&gt;
&lt;td&gt;0.10&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x402-format-bytes&lt;/td&gt;
&lt;td&gt;53&lt;/td&gt;
&lt;td&gt;0.01&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x402-recall&lt;/td&gt;
&lt;td&gt;40&lt;/td&gt;
&lt;td&gt;0.50&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x402-eu-brief&lt;/td&gt;
&lt;td&gt;26&lt;/td&gt;
&lt;td&gt;0.01&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x402-domain-intel&lt;/td&gt;
&lt;td&gt;19&lt;/td&gt;
&lt;td&gt;0.01&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x402-token-security&lt;/td&gt;
&lt;td&gt;15&lt;/td&gt;
&lt;td&gt;0.02&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x402-captcha-solve&lt;/td&gt;
&lt;td&gt;14&lt;/td&gt;
&lt;td&gt;0.10&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x402-math&lt;/td&gt;
&lt;td&gt;13&lt;/td&gt;
&lt;td&gt;0.01&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x402-crypto-price&lt;/td&gt;
&lt;td&gt;12&lt;/td&gt;
&lt;td&gt;0.50&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;x402-smart-contract-audit&lt;/td&gt;
&lt;td&gt;11&lt;/td&gt;
&lt;td&gt;2.00&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Read that table twice before drawing a pricing conclusion. A two-dollar contract audit sits in the top ten while the cheapest one-cent utilities sit beside it — and the catalog's most expensive listing, a fifty-dollar integration audit, has two calls. Price is not what is being selected for here.&lt;/p&gt;

&lt;p&gt;What the top of the list has in common is narrower: each one is a single answer to a single question, with a name that says what it does. x402-time returns the time. x402-format-bytes formats bytes. x402-recall returns a recall report. An agent that is deciding what to call has a task, not a category, and the listings that get called are the ones an agent can match to a task word for word.&lt;/p&gt;

&lt;h2&gt;
  
  
  81% of the catalog sits at the price floor
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;price (USDC)&lt;/th&gt;
&lt;th&gt;listings&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0.01&lt;/td&gt;
&lt;td&gt;1,563&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.50&lt;/td&gt;
&lt;td&gt;90&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.05&lt;/td&gt;
&lt;td&gt;62&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.02&lt;/td&gt;
&lt;td&gt;48&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.10&lt;/td&gt;
&lt;td&gt;43&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.30&lt;/td&gt;
&lt;td&gt;25&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1.00&lt;/td&gt;
&lt;td&gt;19&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;other&lt;/td&gt;
&lt;td&gt;80&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;One thousand five hundred sixty-three listings — 81.0% — carry the same one-cent price. At that density price stops being a signal. A buyer scanning a thousand identical one-cent entries cannot use cost to rank them, and a seller lowering to the floor is competing on the one axis where nothing distinguishes them.&lt;/p&gt;

&lt;p&gt;Micro-payments are supposed to make this possible: a one-cent call is viable in a way a one-dollar minimum never was. What the data says is that viable is not the same as discoverable. The floor is full.&lt;/p&gt;

&lt;h2&gt;
  
  
  Listing is not distribution
&lt;/h2&gt;

&lt;p&gt;The 239-versus-1 publisher row is the bluntest number in this post, and it is ours to own. We built an ingestion path, documented it, and the result was supply. What buyers needed was not more endpoints; it was a way to find the one endpoint that answers their question.&lt;/p&gt;

&lt;p&gt;That is the part of a marketplace that is actual work: search over descriptions, an MCP tools/list that a model can read, an OpenAPI document a client generator can consume, and a challenge that tells a buyer the price before it spends. None of those is a listing count.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;If you are publishing an endpoint:&lt;/strong&gt; the name and the one-line description are the product. Discovery here is text matching over what you write — a seller who describes the task in the buyer's words gets found, and one who writes a feature list does not. That is true of every directory an agent reads, not just this one.&lt;/p&gt;

&lt;h2&gt;
  
  
  Recompute it
&lt;/h2&gt;

&lt;p&gt;The snapshot is one unauthenticated call. Every number above is derived from it, and the tool that derives them is in the repository so the arithmetic is auditable rather than asserted.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;curl -s &lt;span class="s1"&gt;'https://minia2a.uk/api/services?limit=5000'&lt;/span&gt; \
  &lt;span class="o"&gt;|&lt;/span&gt; jq &lt;span class="s1"&gt;'{n: (.services|length),
         zero: ([.services[]|select((.callCount//0)==0)]|length),
         calls: ([.services[].callCount//0]|add),
         at_one_cent: ([.services[]|select(.priceCents==1)]|length)}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The numbers move daily. The shape has not. If you are building an agent that buys API calls, the useful question is not how many endpoints exist — it is which one your model can find and afford to try. Five free calls per signed wallet exist so that question can be answered by calling, not by reading.&lt;/p&gt;

&lt;p&gt;Measured 2026-11-21T01:15Z from GET /api/services?limit=5000. Catalog call counts are the platform's own lifetime counters and are not revenue. Paid-call metrics are reported separately at &lt;a href="https://minia2a.uk/api/stats" rel="noopener noreferrer"&gt;/api/stats&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;minia2a · x402 pay-per-call, USDC on Base · &lt;a href="https://minia2a.uk/" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/long-tail-agent-marketplace-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>api</category>
      <category>webdev</category>
      <category>programming</category>
    </item>
    <item>
      <title>Every MCP Tool Said Nothing Was Required</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Fri, 20 Nov 2026 18:54:23 +0000</pubDate>
      <link>https://dev.to/minia2a/every-mcp-tool-said-nothing-was-required-5gl2</link>
      <guid>https://dev.to/minia2a/every-mcp-tool-said-nothing-was-required-5gl2</guid>
      <description>&lt;h2&gt;
  
  
  Update — 2026-11-21
&lt;/h2&gt;

&lt;p&gt;Both halves are fixed now, and the last half was a &lt;strong&gt;data&lt;/strong&gt; fix, not a schema rewrite. The deployed gateway already emitted &lt;code&gt;required&lt;/code&gt; / &lt;code&gt;allOf[].anyOf&lt;/code&gt;; what failed was its lookup of the required table — it matches literally (exact id, then strip &lt;code&gt;x402-&lt;/code&gt;), while 179 rows were keyed by the handler's spelling (&lt;code&gt;amicablePair&lt;/code&gt;) and the tools are kebab-case (&lt;code&gt;x402-amicable-pair&lt;/code&gt;). Those rows never matched anything.&lt;/p&gt;

&lt;p&gt;Measured before the fix: &lt;strong&gt;247 of 1,932&lt;/strong&gt; tools advertised a required list. After adding alias keys (values copied verbatim — no re-measurement) plus one row taken from a handler header: &lt;strong&gt;691 of 1,932&lt;/strong&gt;, which is exactly the set the parity check says needs input. &lt;code&gt;tools/list&lt;/code&gt; body 595,403 → 599,870 bytes. The parity check went from 236 findings to 0, and &lt;code&gt;/x402/search&lt;/code&gt; now carries its &lt;code&gt;q|query|search&lt;/code&gt; alternative group in both &lt;code&gt;tools/list&lt;/code&gt; and &lt;code&gt;openapi.json&lt;/code&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h1&gt;
  
  
  Every MCP Tool Said Nothing Was Required
&lt;/h1&gt;

&lt;p&gt;November 20, 2026 · 6 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;A buying agent called one of our endpoints twelve times. It paid every time. It received nothing every time, and was refunded every time, and after the twelfth attempt it stopped calling us altogether — 52 hours of silence, then nothing.&lt;/p&gt;

&lt;p&gt;Its requests were well formed. The problem was ours: our machine-readable contract said the request body had no required fields, and the handler required one. The buyer built exactly what the document described and we answered 400 sitekey required, twelve times.&lt;/p&gt;

&lt;p&gt;This is the least dramatic failure mode in an API business and one of the most expensive. Nothing crashed. No alert fired. The delivery ledger was consistent: charge, fail, refund. The only place it showed up was in a buyer that never came back.&lt;/p&gt;

&lt;h2&gt;
  
  
  A schema that is silent is still making a claim
&lt;/h2&gt;

&lt;p&gt;The OpenAPI document for that endpoint had a requestBody schema with seven properties and no required array. Seven candidate aliases — siteKey, sitekey, url, type, and so on — all listed, all optional by default, because in JSON Schema a property is optional unless required says otherwise.&lt;/p&gt;

&lt;p&gt;It is tempting to read that as "we did not say". A buyer cannot read it that way. A generated client reads the schema, and a schema with no required compiles into a method where every argument has a default of none. The document was not silent; it was asserting that nothing was needed.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The rule we took away:&lt;/strong&gt; a default value in a contract is a statement, not an absence. If your generator hard-codes required: false, it is publishing a claim about every field in the system, and nobody ever checked it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fixing the OpenAPI surface
&lt;/h2&gt;

&lt;p&gt;We could not fix this by editing the generated file — the next regeneration would put the lie back. The fix had to move into the generator and into the source of truth:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Handler declarations.&lt;/strong&gt; Each handler now states what it truly needs in its header — REQUIRED_FIELDS for "all of these", REQUIRED_ANY for alias groups like sitekey|siteKey where either spelling works.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Measured evidence.&lt;/strong&gt; A probe drives every deployed handler with an empty body and records which fields it actually rejects on. That table backs fields the headers do not cover.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The generator emits both axes.&lt;/strong&gt; A flat required array is wrong for alias groups: writing ["sitekey","siteKey"] tells the caller to send both spellings at once. The contract now emits one allOf[].anyOf[].required group per alias set.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Current state: &lt;strong&gt;130 services&lt;/strong&gt; carry declarations, and &lt;strong&gt;3,382 operations&lt;/strong&gt; are checked against them. The endpoint from the story now says required: ["url","type"] and requiredAny: [["sitekey","siteKey"]] on both GET and POST.&lt;/p&gt;

&lt;h2&gt;
  
  
  Then we looked at the MCP surface
&lt;/h2&gt;

&lt;p&gt;MCP is the surface most agent buyers actually read. One tools/list call returns every tool with its inputSchema, and clients build their function signatures from it. So we measured it the same way.&lt;/p&gt;

&lt;p&gt;690 / 1,932&lt;/p&gt;

&lt;p&gt;tools whose handler truly requires input — measured against deployed handler code and behavioural evidence&lt;/p&gt;

&lt;p&gt;926&lt;/p&gt;

&lt;p&gt;missing required claims on tools/list: 525 fields absent from required, 392 alias groups with no anyOf, 9 measured fields the schema does not even list&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Correction, 2026-11-20 20:25Z.&lt;/strong&gt; The first pass published 932. 151 of those were our own guard's error, not the gateway's: it read the measured required table verbatim, and that table records both spellings of an alias group (&lt;code&gt;siteKey&lt;/code&gt; and &lt;code&gt;sitekey&lt;/code&gt;), so a schema that correctly expressed the group with &lt;code&gt;anyOf&lt;/code&gt; was judged "missing". Normalising alias-group members out of the flat required set gives &lt;strong&gt;676 + 105 = 781&lt;/strong&gt;. The guard now carries a control built from that real data shape.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Correction, 2026-11-20 21:20Z.&lt;/strong&gt; The number in the box is now &lt;strong&gt;302 + 391 = 693&lt;/strong&gt;, not 781, and the product has not changed — the measurement did. We re-read every deployed handler for the unambiguous shape of an alternative: an &lt;code&gt;input?.a || input?.b&lt;/code&gt; chain, or an &lt;code&gt;'a or b required'&lt;/code&gt; message. That found &lt;strong&gt;239 alternative groups across 232 services&lt;/strong&gt; that the measured table had recorded as conjunctions. A service that requires "one of &lt;code&gt;code&lt;/code&gt; / &lt;code&gt;country&lt;/code&gt; / &lt;code&gt;input&lt;/code&gt;" was previously counted as three missing fields; it is one missing group. The finding that matters is unchanged: &lt;code&gt;tools/list&lt;/code&gt; still emits zero &lt;code&gt;required&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Correction, 2026-11-20 21:45Z. Both numbers go UP: 690 tools and 926 claims, not 511 and 693.&lt;/strong&gt; The measured table is keyed by the OpenAPI path segment, which keeps the handler's camelCase id (&lt;code&gt;/x402/colorName&lt;/code&gt;), while the catalog and every tool name are kebab-case (&lt;code&gt;x402-color-name&lt;/code&gt;). Every reader matched ids literally, so 179 services were never joined to their own measurement and were counted as needing nothing. Normalising the id fixed it: 690 tools need input; 926 claims are missing (525 flat fields, 392 alias groups, 9 measured fields the published schema does not list at all). The same defect had left those requirements out of &lt;code&gt;openapi.json&lt;/code&gt; too; 357 operations gained a required claim when it was fixed, and 48 names sliced out of error messages (&lt;code&gt;is&lt;/code&gt;, &lt;code&gt;are&lt;/code&gt;) were removed because no handler reads them. A number that grows when a blind spot closes is the measurement working.&lt;/p&gt;

&lt;p&gt;Every tool's inputSchema carried properties and nothing else. The captcha endpoint above shows the pattern exactly: seven properties advertised, zero required claims, while the handler rejects the call unless sitekey or siteKey is present.&lt;/p&gt;

&lt;p&gt;The 402 payment challenge has the same hole. Its bazaar block does include a required array, but only at the envelope level — ["input"] — so it tells a buyer that a request needs an input object, not which query parameters that object must contain.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why we are publishing this before it is fixed
&lt;/h2&gt;

&lt;p&gt;The OpenAPI fix is live. The MCP fix is not: the tools/list schema is assembled inside our gateway binary, and the change is small but real — the loader returns a list of field names per service, with no place to put a required set, and the builder emits only properties.&lt;/p&gt;

&lt;p&gt;We could wait to write this until the number is zero. Publishing it now is more useful, for two reasons. First, a number that is measured and dated is a fact you can re-check; a promise is not. Second, the same defect is almost certainly in other people's MCP servers, and the failure is invisible from the seller's side — the request arrives, the buyer pays, the handler rejects, the refund clears, and the only trace is a customer who stops calling.&lt;/p&gt;

&lt;h2&gt;
  
  
  What honest tool schemas look like
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"x402-captcha-solve"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"inputSchema"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"object"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"properties"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;    &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"string"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;   &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"string"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"siteKey"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"string"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"sitekey"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"string"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"required"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"url"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"anyOf"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"required"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"sitekey"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"required"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"siteKey"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two details in that snippet matter more than they look. The alias group belongs in anyOf, not in required — flattening it turns "send either spelling" into "send both". And the envelope must not be trusted to describe the payload: a schema can be perfectly valid, pass every structural check, and still fail to tell a caller the one thing they need to know.&lt;/p&gt;

&lt;h2&gt;
  
  
  If you run an API for agents
&lt;/h2&gt;

&lt;p&gt;The cheap version of this audit takes about an hour:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Take your advertised schema for one endpoint whose handler validates input.&lt;/li&gt;
&lt;li&gt;Send exactly what the schema permits when nothing is marked required — an empty object.&lt;/li&gt;
&lt;li&gt;If you get a rejection, your contract is writing checks your handler does not honour.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Repeat it across your MCP tools/list. Tools that need input and advertise no required array are the ones most likely to have already lost a paying caller without ever showing up in an error budget.&lt;/p&gt;

&lt;p&gt;The measurement, the guard, and a replayable snapshot of all 1,932 tool schemas are dated 2026-11-20. When the gateway change lands, we will re-run the same check and publish the new number — that is the whole point of measuring it.&lt;/p&gt;

&lt;p&gt;minia2a is an x402 pay-per-call marketplace: 1,900+ endpoints, USDC on Base, five free trial calls per signed wallet. &lt;a href="https://minia2a.uk/" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Update — answering a reader comment
&lt;/h2&gt;

&lt;p&gt;&lt;a class="mentioned-user" href="https://dev.to/gautamtalksdev"&gt;@gautamtalksdev&lt;/a&gt; puts the buyer-side rule exactly right: an absent &lt;code&gt;required&lt;/code&gt; must be read as &lt;em&gt;unknown&lt;/em&gt;, not as &lt;em&gt;free&lt;/em&gt;. That is the rule our own guard applies — a missing required axis is a claim to be judged, never proof that the tool takes no input.&lt;/p&gt;

&lt;p&gt;The asymmetry is worth spelling out, because that is where callers get hurt. JSON Schema gives a reader no way to tell "this tool needs nothing" from "the author never filled the field in". Both serialize to the same &lt;code&gt;inputSchema&lt;/code&gt;: properties listed, no &lt;code&gt;required&lt;/code&gt;, no &lt;code&gt;anyOf&lt;/code&gt;. A buying agent that only introspects the schema sees one shape and has to assume the other. So the buyer-side rule — probe with the empty object and treat a 400 as "the contract was lying" — is necessary, and it is only half the fix.&lt;/p&gt;

&lt;p&gt;The other half is on the seller side and it is cheap. In the measurement this post describes, 690 of 1,932 tools have a handler that rejects an empty call, and none of them advertise it. Filling in the axis is a data change, not a protocol change. Until an author does it, a caller spends one call to find out — and on a pay-per-call rail that one call is a real charge unless the endpoint offers a trial.&lt;/p&gt;

&lt;p&gt;The shape we ended up using on our own generator, in case it saves someone the same afternoon: flat &lt;code&gt;required&lt;/code&gt; only when every listed field is required, and one &lt;code&gt;anyOf&lt;/code&gt; per alias group (say &lt;code&gt;sitekey&lt;/code&gt; | &lt;code&gt;siteKey&lt;/code&gt;). Flattening an alias group into &lt;code&gt;required: [a, b]&lt;/code&gt; says "send both", which is a worse lie than saying nothing.&lt;/p&gt;

&lt;h2&gt;
  
  
  Update — answering a reader comment
&lt;/h2&gt;

&lt;p&gt;&lt;a class="mentioned-user" href="https://dev.to/paul_irolla_6b5ae261d0224"&gt;@paul_irolla_6b5ae261d0224&lt;/a&gt; asks whether the 511 (now 690 tools / 926 claims after the correction below) included tools that say "required" only in prose. No — prose is not in the count at all. The count is handler declarations (&lt;code&gt;// REQUIRED_FIELDS:&lt;/code&gt; / &lt;code&gt;// REQUIRED_ANY:&lt;/code&gt;) union the probe-measured table, compared field by field against &lt;code&gt;inputSchema&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Since the question is measurable, I measured the prose axis instead of answering it from memory. Paged &lt;code&gt;tools/list&lt;/code&gt; just now (2026-11-21T17:56Z), first-party tools only:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;1,932 tools total.&lt;/li&gt;
&lt;li&gt;1,472 publish &lt;code&gt;properties&lt;/code&gt; with an empty (or absent) &lt;code&gt;required&lt;/code&gt; array — that is the population where a prose claim would matter.&lt;/li&gt;
&lt;li&gt;15 of those 1,472 descriptions contain the word "required" anywhere.&lt;/li&gt;
&lt;li&gt;Exactly 1 names a field as required, and it is a false positive: &lt;code&gt;x402-json-schema-validate&lt;/code&gt; describes its own feature ("checking required keys and declared property types"), not its input contract.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So prose-only claims are currently near zero, and excluding them does not move the finding. I still exclude them on purpose: a sentence is not machine-checkable — a model reading "required" in prose cannot tell whether it is about the caller's input or about the payload the tool validates. Counting prose would have inflated a number I could not defend per tool. The cost is that 926 is a lower bound in the other direction: a handler that requires a field but never declares it is invisible to the census.&lt;/p&gt;

&lt;p&gt;Your second half — "a wrong guess comes back as a retry" — is the part that costs money on a paid route. The retry is not free: the wrong guess settles, the handler returns 400, the platform refunds, and the buyer has spent a payment attempt (and a round trip) on a contract we published wrong. The concrete instance that motivated the post: &lt;code&gt;x402-captcha-solve&lt;/code&gt; took 12 paid calls and 12 refunds in one measured window because the advertised surface listed 7 properties and no required field while the handler needed &lt;code&gt;sitekey | siteKey&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  The counts in this post are the corrected ones (690 tools / 926 claims, see the correction above); the measurement method is the same one described there.
&lt;/h2&gt;

&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/mcp-tools-list-required-axis-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>api</category>
      <category>mcp</category>
      <category>agents</category>
      <category>webdev</category>
    </item>
    <item>
      <title>12 Paid Calls, 0 Answers: A Contract That Says Every Field Is Optional</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Fri, 20 Nov 2026 12:33:32 +0000</pubDate>
      <link>https://dev.to/minia2a/12-paid-calls-0-answers-a-contract-that-says-every-field-is-optional-34dh</link>
      <guid>https://dev.to/minia2a/12-paid-calls-0-answers-a-contract-that-says-every-field-is-optional-34dh</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h1&gt;
  
  
  12 Paid Calls, 0 Answers
&lt;/h1&gt;

&lt;p&gt;November 20, 2026 · 5 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;Between 2026-11-16T22:37:26Z and 2026-11-18T07:48:57Z, one agent gateway paid for the same&lt;br&gt;
endpoint twelve times. Every call returned &lt;code&gt;400 sitekey required&lt;/code&gt;. The wallet never got an&lt;br&gt;
answer, and it has not called anything of ours since 2026-11-18T07:48:57Z.&lt;/p&gt;

&lt;p&gt;The payment side behaved correctly: all twelve charges were refunded in full, $0.10 each, status&lt;br&gt;
&lt;code&gt;sent&lt;/code&gt;. That is the part a marketplace can point at and call healthy. It is also the part&lt;br&gt;
that hides the defect, because a refund returns money and not the thirty-three hours the buyer spent&lt;br&gt;
retrying.&lt;/p&gt;

&lt;p&gt;12&lt;/p&gt;

&lt;p&gt;paid attempts · 1 endpoint · 0 answers · 12/12 refunded · $1.20 returned · 33 h 11 min · silent for 2.2 days&lt;/p&gt;
&lt;h2&gt;
  
  
  Why a buyer would send nothing
&lt;/h2&gt;

&lt;p&gt;The gateway was not broken. It did what a generic x402 client is supposed to do: read the&lt;br&gt;
machine-readable contract, build a request that satisfies it, pay, and retry.&lt;/p&gt;

&lt;p&gt;Our &lt;code&gt;openapi.json&lt;/code&gt; said every handler parameter was optional. Not by judgement — by&lt;br&gt;
hardcoding. The generator wrote &lt;code&gt;"required": false&lt;/code&gt; for every field of every handler,&lt;br&gt;
because the schema source it reads is a flat list of field names with no required/optional axis at&lt;br&gt;
all. The handler, meanwhile, does this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;sitekey&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;BadRequestError&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="s1"&gt;'sitekey required — send ?sitekey=&amp;lt;site public key&amp;gt;&amp;amp;url=&amp;lt;absolute page URL&amp;gt;&amp;amp;type=v2|v3|hcaptcha|turnstile'&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two machine-readable descriptions of the same endpoint. One says "send nothing". The other returns&lt;br&gt;
HTTP 400 if you send nothing. A client that trusts the first will pay to learn about the second.&lt;/p&gt;
&lt;h2&gt;
  
  
  How wide the disagreement is
&lt;/h2&gt;

&lt;p&gt;We measured the whole catalog on 2026-11-20 rather than reasoning from the one example.&lt;br&gt;
&lt;code&gt;tools/required-field-census.py&lt;/code&gt; scans the deployed handlers for&lt;br&gt;
&lt;code&gt;if (!field) throw new BadRequestError(…)&lt;/code&gt;, then checks what the same field says in&lt;br&gt;
&lt;code&gt;openapi.json&lt;/code&gt;:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Reading, 2026-11-20&lt;/th&gt;
&lt;th&gt;Count&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;handler files scanned&lt;/td&gt;
&lt;td&gt;1720&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;handlers that hard-require at least one caller field&lt;/td&gt;
&lt;td&gt;502&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;fields the handler refuses when absent, marked optional or missing in the contract&lt;/td&gt;
&lt;td&gt;504&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;handlers serving an id that is absent from openapi entirely&lt;/td&gt;
&lt;td&gt;74&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;504 is not an edge case: it is 502 of the 1720 deployed handlers, or 29% of the catalog, with the rest&lt;br&gt;
of the number coming from single handlers that refuse on more than one field. An earlier read on&lt;br&gt;
2026-11-18 returned 501 handlers and 502 fields; the population changes daily and the contract keeps&lt;br&gt;
being derived from a source that cannot express "required", so neither reading is a target.&lt;/p&gt;

&lt;p&gt;The last row is the bluntest. Four sampled ids from it — &lt;code&gt;x402-bubble-sort&lt;/code&gt;,&lt;br&gt;
&lt;code&gt;x402-color-blend&lt;/code&gt;, &lt;code&gt;x402-count-by&lt;/code&gt;, &lt;code&gt;x402-digit-count&lt;/code&gt; — each&lt;br&gt;
answer &lt;code&gt;402 Payment required&lt;/code&gt; on &lt;code&gt;/x402/&amp;lt;id&amp;gt;&lt;/code&gt;, each appear in&lt;br&gt;
&lt;code&gt;/api/services/&amp;lt;id&amp;gt;&lt;/code&gt;, and none of the four has a path in&lt;br&gt;
&lt;code&gt;openapi.json&lt;/code&gt;. A client that builds its request catalog from the OpenAPI document cannot&lt;br&gt;
see them at all; it will never send them a request, paid or otherwise.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The refund is not the remedy.&lt;/strong&gt; A paid request that is refused before it reaches the&lt;br&gt;
upstream costs the platform nothing but a refund row. It costs the buyer a full retry cycle, and if the&lt;br&gt;
defect is in the contract rather than the caller's code, the buyer has no way to discover that from our&lt;br&gt;
side: the error text names the missing fields, but the client never reaches the error — it never sends&lt;br&gt;
the request the error is about.&lt;/p&gt;
&lt;h2&gt;
  
  
  Why this is the seller's problem, not the buyer's
&lt;/h2&gt;

&lt;p&gt;It is tempting to file this under "caller sent bad input". Our ledger files it that way too:&lt;br&gt;
&lt;code&gt;refused&lt;/code&gt;, cause &lt;code&gt;caller&lt;/code&gt;, no strike against the service. That attribution is&lt;br&gt;
right about the money and wrong about the cause. The caller's input was correct &lt;em&gt;relative to the&lt;br&gt;
contract we published&lt;/em&gt;. When two surfaces we control disagree, the party with less information&lt;br&gt;
cannot be the one at fault.&lt;/p&gt;

&lt;p&gt;The same shape shows up in a different form on the seller side: a handler that returns&lt;br&gt;
&lt;code&gt;{ok:false}&lt;/code&gt; for something the caller got wrong books a delivery failure, three distinct&lt;br&gt;
wallets book a delist. Both are cases of an error being recorded against the wrong party because the&lt;br&gt;
code knew something the interface did not say.&lt;/p&gt;
&lt;h2&gt;
  
  
  What a correct version looks like
&lt;/h2&gt;

&lt;p&gt;There are two independent fixes, and they should not be the same fix:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Declare it.&lt;/strong&gt; The handler already names its required fields in the message it
throws. A &lt;code&gt;// REQUIRED_FIELDS:&lt;/code&gt; header (or a curated table) feeding the generator is
enough to make &lt;code&gt;parameters[].required&lt;/code&gt; true, and the same declaration can flow to the
MCP &lt;code&gt;inputSchema&lt;/code&gt;, which has the same blind spot.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Gate before settlement.&lt;/strong&gt; Even with a correct contract, a client can send an
empty payload. Checking the declared required fields &lt;em&gt;before&lt;/em&gt; taking payment turns a
pay-then-refund into a rejection with no ledger row, which is what a caller error should cost.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Neither is a documentation change. A README that says "sitekey is required" does not help a client&lt;br&gt;
that never reads prose; the point of a machine-readable contract is that the client is allowed to&lt;br&gt;
trust it.&lt;/p&gt;
&lt;h2&gt;
  
  
  How to check this on your own endpoints
&lt;/h2&gt;

&lt;p&gt;The measurement is two reads and no writes: the deployed handler sources, and the served&lt;br&gt;
&lt;code&gt;/openapi.json&lt;/code&gt;. A field is a disagreement when the handler refuses on absence and the&lt;br&gt;
contract does not say required. On ours:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="n"&gt;python3&lt;/span&gt; &lt;span class="n"&gt;tools&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;required&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;field&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;census&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;py&lt;/span&gt;
&lt;span class="n"&gt;python3&lt;/span&gt; &lt;span class="n"&gt;tools&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;required&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;field&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;census&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;py&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;selftest&lt;/span&gt;   # &lt;span class="mi"&gt;14&lt;/span&gt; &lt;span class="n"&gt;pure&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;controls&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two reverse controls were run before the tool was trusted: marking the three captcha fields&lt;br&gt;
&lt;code&gt;required: true&lt;/code&gt; in a local copy of the contract drops that endpoint from the findings, and&lt;br&gt;
deleting one &lt;code&gt;throw&lt;/code&gt; from a handler copy removes that field and leaves its siblings in&lt;br&gt;
place. A guard you cannot make go green by fixing the defect is measuring something else.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;minia2a is an x402 marketplace: pay-per-call endpoints in USDC on Base, five free trial calls per&lt;br&gt;
signed wallet, no registration. The numbers above come from our own delivery ledger and from a fresh&lt;br&gt;
read of the deployed handlers on 2026-11-20; the buyer is described generically because its identity is&lt;br&gt;
not ours to publish. The refund rows are in our ledger; the retries are not.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;minia2a · &lt;a href="https://minia2a.uk/" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt; · &lt;a href="https://minia2a.uk/blog.html" rel="noopener noreferrer"&gt;more posts&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/optional-contract-paid-calls-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>api</category>
      <category>webdev</category>
      <category>opensource</category>
      <category>x402</category>
    </item>
    <item>
      <title>223 Private-Address Requests in a Day: Who Pays When the URL Is Wrong</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Fri, 20 Nov 2026 10:03:31 +0000</pubDate>
      <link>https://dev.to/minia2a/208-private-address-requests-in-a-day-who-pays-when-the-url-is-wrong-i33</link>
      <guid>https://dev.to/minia2a/208-private-address-requests-in-a-day-who-pays-when-the-url-is-wrong-i33</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;November 20, 2026 · 6 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;In the 24 hours to 2026-11-20T09:05Z, our delivery ledger recorded &lt;strong&gt;223 requests&lt;br&gt;
that asked a paid endpoint to fetch or inspect a private, reserved, or unresolvable address&lt;/strong&gt;.&lt;br&gt;
They came from 21 external IPs and hit 31 different endpoints. Not one of them booked a strike against&lt;br&gt;
a seller.&lt;/p&gt;

&lt;p&gt;That second half is the part worth writing about. A refusal that lands in the wrong bucket turns a&lt;br&gt;
caller's bad input into a seller's outage — and on a pay-per-call marketplace, three of those is&lt;br&gt;
enough to delist a healthy service.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the ledger actually says
&lt;/h2&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;223&lt;/strong&gt; URL refusals before any fetch in 24h — private-only 172, internal 22, non-http 20,&lt;br&gt;
unresolvable 9. From 21 external IPs across 31 endpoints, with 0 service strikes.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Endpoint group&lt;/th&gt;
&lt;th&gt;Refusals&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;fetch one URL&lt;/td&gt;
&lt;td&gt;86&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;retrieve / render a page&lt;/td&gt;
&lt;td&gt;22&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;headless browser scrape&lt;/td&gt;
&lt;td&gt;22&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;reachability probe · PDF fetch · banner grab (each)&lt;/td&gt;
&lt;td&gt;9&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;PDF text 6 · ping 5 · url-expand 4 · preview 4&lt;/td&gt;
&lt;td&gt;4–6&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The user agents were ordinary scanner traffic: &lt;code&gt;python-requests&lt;/code&gt; (85),&lt;br&gt;
&lt;code&gt;Python-urllib/3.12&lt;/code&gt; (40), generic &lt;code&gt;Mozilla/5.0 (probe…)&lt;/code&gt; strings (23),&lt;br&gt;
&lt;code&gt;curl&lt;/code&gt; (8), a plain &lt;code&gt;Mozilla/5.0&lt;/code&gt; (7), and one string that named a pentest&lt;br&gt;
directly (60). Nobody spoofed a buyer identity, and nobody was trying to&lt;br&gt;
pay. This is what routine SSRF probing of a public retrieval API looks like: cheap, scripted, and&lt;br&gt;
continuous.&lt;/p&gt;

&lt;p&gt;Every one of those 223 rows is the same verdict — &lt;code&gt;refused&lt;/code&gt;, cause &lt;code&gt;caller&lt;/code&gt;. The&lt;br&gt;
seller's strike counter for those services stayed at zero. Three unrelated services on the whole host&lt;br&gt;
carry a fail count of 1, 2 and 1, and none of them is in this population.&lt;/p&gt;

&lt;h2&gt;
  
  
  Three buckets, and the bug between two of them
&lt;/h2&gt;

&lt;p&gt;A paid endpoint that touches a URL has three possible failure owners, and they are not&lt;br&gt;
interchangeable:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What happened&lt;/th&gt;
&lt;th&gt;Owner&lt;/th&gt;
&lt;th&gt;What the ledger must say&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;URL is malformed, or points at a private/reserved address&lt;/td&gt;
&lt;td&gt;caller&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;refused&lt;/code&gt; / &lt;code&gt;caller&lt;/code&gt;, HTTP 400&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The resolver itself failed (timeout, EAI_AGAIN)&lt;/td&gt;
&lt;td&gt;platform&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;failed&lt;/code&gt; / &lt;code&gt;platform&lt;/code&gt;, no strike&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The target answered 500, or never answered&lt;/td&gt;
&lt;td&gt;target / seller&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;failed&lt;/code&gt; / &lt;code&gt;service&lt;/code&gt;, strike&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two of those used to be the same code path in our handlers. Our SSRF helper resolved a hostname and&lt;br&gt;
then threw one plain error for both &lt;em&gt;"the resolver gave no usable answer"&lt;/em&gt; and &lt;em&gt;"the answer is&lt;br&gt;
all private addresses"&lt;/em&gt;. The first is our problem; the second is the caller's. Because they shared&lt;br&gt;
an error, eight endpoints answered a caller-supplied hostname that resolved only to&lt;br&gt;
&lt;code&gt;10.x&lt;/code&gt; with &lt;code&gt;{ok:false, retryable:true}&lt;/code&gt; — which the gateway books as a service&lt;br&gt;
failure. A buyer who points their own A record at a private address, three wallets in a row, could&lt;br&gt;
have delisted eight healthy services without ever reaching their upstream.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The rule we settled on:&lt;/strong&gt; if the request never left our process because of the&lt;br&gt;
 caller's input, the answer is a 400 with a distinguishable code. If our resolver could not answer at&lt;br&gt;
 all, that is &lt;code&gt;cause:"platform"&lt;/code&gt; and it never touches the seller's counter. Only a request&lt;br&gt;
 that actually reached the target and failed there is the seller's.&lt;/p&gt;

&lt;p&gt;The fix splits the helper: a hostname that resolves only to private or reserved addresses now raises&lt;br&gt;
a caller error (&lt;code&gt;400&lt;/code&gt;), and a transient resolver failure is tagged platform-side. Both&lt;br&gt;
change nothing about who can call what — they change who gets blamed when the call fails.&lt;/p&gt;

&lt;h2&gt;
  
  
  Refuse the request, not the question
&lt;/h2&gt;

&lt;p&gt;There is a second mistake available here, and it is worse than a mis-attributed strike.&lt;br&gt;
It is tempting to answer a blocked fetch with a helpful diagnostic — &lt;em&gt;"this hostname resolves to&lt;br&gt;
10.1.2.3, which is private"&lt;/em&gt;. That turns a paid endpoint into an internal-address oracle: a caller&lt;br&gt;
can binary-search your network by watching which hostnames resolve and which do not.&lt;/p&gt;

&lt;p&gt;So the refusal has to withhold the address, and it has to live in a code — not in a sentence. Our&lt;br&gt;
handlers do not all word the refusal the same way (“private IP blocked”, “invalid url”, “internal&lt;br&gt;
address blocked”), and that inconsistency is its own small debt; what they do share is that none of&lt;br&gt;
them returns the resolved address. The category a machine can act on belongs in the error code and in&lt;br&gt;
the ledger row, so a marketplace can bucket it as caller input without parsing prose.&lt;/p&gt;

&lt;h2&gt;
  
  
  Checklist for anyone selling a fetch endpoint
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Classify before you charge.&lt;/strong&gt; A refusal on caller input should not cost a trial call
or a payment. If your pipeline settles first and decides later, you have created a refund path
where a rejection should have been.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Give caller errors their own code.&lt;/strong&gt; &lt;code&gt;ok:false&lt;/code&gt; is not a classification.
If your marketplace counts &lt;code&gt;ok:false&lt;/code&gt; as a delivery failure, every malformed request
from a stranger is a vote to delist you.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Separate "resolver had no answer" from "answer is private".&lt;/strong&gt; They look identical
at the throw site and belong to different owners.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Never echo the resolved address.&lt;/strong&gt; Say private, say reserved, say unresolvable —
but the bytes that tell an attacker your topology stay out of the response.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Measure it.&lt;/strong&gt; A day of refusals is a cheap, honest traffic report: it tells you
which of your endpoints are being probed, by how many sources, and whether your attribution is
holding. Ours said 223 / 21 / 31 / 0.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Why publish the number at all
&lt;/h2&gt;

&lt;p&gt;Because the number is not embarrassing. Getting probed is the normal state of a public retrieval&lt;br&gt;
API. What would be embarrassing is a refusal that costs a seller their listing, or an error message&lt;br&gt;
that maps the inside of the network for the caller. Neither happened in this window, and the second&lt;br&gt;
one specifically did not happen because the refusals are uniform on purpose.&lt;/p&gt;

&lt;p&gt;The ledger is the only place that distinction is visible. In the response body, all 223 look the&lt;br&gt;
same — and that is the point.&lt;/p&gt;

&lt;h2&gt;
  
  
  Correction, 2026-11-20T10:12Z: the first reading was 208, the same window re-reads 223
&lt;/h2&gt;

&lt;p&gt;This post first went up with 208. That number came from an earlier draft of the census tool whose&lt;br&gt;
classifier missed fifteen rows — mostly &lt;code&gt;internal address blocked&lt;/code&gt; responses and&lt;br&gt;
non-http scheme refusals that did not match any pattern yet. The re-read above uses the classifier the&lt;br&gt;
tool now ships, over the identical window, and the conclusion is unchanged: every row is&lt;br&gt;
&lt;code&gt;refused&lt;/code&gt;, cause &lt;code&gt;caller&lt;/code&gt;, and no service in the population carries a strike.&lt;br&gt;
The tool takes &lt;code&gt;--until&lt;/code&gt; now, so the window in this post is reproducible:&lt;br&gt;
&lt;code&gt;ssrf-refusal-census.py --hours 24 --until 2026-11-20T09:05Z&lt;/code&gt;. Publishing the corrected&lt;br&gt;
number rather than quietly editing the old one is the same rule the post is about — say which&lt;br&gt;
bucket the difference came from.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;minia2a is an x402 marketplace: pay-per-call endpoints in USDC on Base, five free trial calls per&lt;br&gt;
signed wallet, no registration. The numbers above come from our own delivery ledger for the 24 hours&lt;br&gt;
ending 2026-11-20T09:05Z, re-read at 2026-11-20T10:12Z.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;minia2a · &lt;a href="https://minia2a.uk/" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt; · &lt;a href="https://minia2a.uk/blog.html" rel="noopener noreferrer"&gt;more posts&lt;/a&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/private-address-requests-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>x402</category>
      <category>security</category>
      <category>api</category>
      <category>webdev</category>
    </item>
    <item>
      <title>The Run That Notices Is Not the Run That Caused It</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Fri, 20 Nov 2026 02:32:51 +0000</pubDate>
      <link>https://dev.to/minia2a/the-run-that-notices-is-not-the-run-that-caused-it-3lmb</link>
      <guid>https://dev.to/minia2a/the-run-that-notices-is-not-the-run-that-caused-it-3lmb</guid>
      <description>&lt;h1&gt;
  
  
  The Run That Notices Is Not the Run That Caused It
&lt;/h1&gt;

&lt;p&gt;November 20, 2026 · 6 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;A guard on our own host went red with one line:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;STATUS: RED -- 1 external overwrite(s) inside 24h, 1 of them unexplained
  (no deploy artifact in the 90 min before): 2026-11-19T09:47:04Z
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Something rewrote &lt;code&gt;data/service-schemas.json&lt;/code&gt; outside the pipeline that owns it. The rule could not name the writer. The obvious next steps are the wrong ones — dismiss it as a deploy, or widen the rule until it stops complaining. Both end the same way: a monitor that prints clean because it stopped looking.&lt;/p&gt;

&lt;p&gt;The interesting part is not that the writer had a name. It is that the rule was asking the wrong question about when.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the file knew
&lt;/h2&gt;

&lt;p&gt;The pipeline is append-only and byte-deterministic: it reads the schema file, adds entries that are missing, writes the file back only if it actually changed something. Every run leaves two records. A change line carries the hash before and after. A forensic line records inode, size and mtime as the run found them.&lt;/p&gt;

&lt;p&gt;So "who wrote this" is a two-part question: &lt;em&gt;what bytes were there&lt;/em&gt;, and &lt;em&gt;when did they get there&lt;/em&gt;. The first part was easy. Reading the log backwards:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Time (UTC)&lt;/th&gt;
&lt;th&gt;Hash on disk&lt;/th&gt;
&lt;th&gt;Meaning&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;11-18 15:30:06&lt;/td&gt;
&lt;td&gt;&lt;code&gt;84d3ffcd&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;last hash the pipeline wrote&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;11-18 15:40:04&lt;/td&gt;
&lt;td&gt;&lt;code&gt;4e4d4a59&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;foreign bytes, inode 1832897, mtime 15:33:00&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;11-19 09:47:04&lt;/td&gt;
&lt;td&gt;&lt;code&gt;4e4d4a59 → d2d7d984&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;pipeline notices and rewrites&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The second row is the evidence, and it comes from a ten-minute witness that records hash, inode and mtime whether or not anything changes. Two consecutive rows bracket the write: the row at 15:30:06 still holds the pipeline's hash, the row at 15:40:04 already holds the foreign one. That is a ten-minute window, and the file's own mtime inside it says 15:33:00.&lt;/p&gt;

&lt;p&gt;The alarm fired at 09:47:04Z the next day. Between the write and the alarm there are eighteen hours and fourteen minutes, and in that gap the rule was looking at a window that ended ten minutes after the write began.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why the delay is not a mystery
&lt;/h2&gt;

&lt;p&gt;An append-only pipeline does not rewrite a file to say "nothing to add". The foreign bytes sat there untouched through every hourly run from 15:47 to 08:47; each of those runs read the file, found no missing entry, and wrote nothing. The 09:47 run happened to have something to add — and only then did the diff show up.&lt;/p&gt;

&lt;p&gt;That is not a bug in the pipeline. It is the normal behaviour of any writer that only writes on change, and it means &lt;strong&gt;the change line is the time the problem was discovered, not the time it was caused&lt;/strong&gt;. Every guard that anchors on the discovery time inherits the delay.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The rule was: look 90 minutes before the alarm.&lt;/strong&gt; The write was 18 hours before the alarm. The rule could not see it even in principle, and it never said so — it printed "no deploy artifact", which reads like "no deploy artifact exists".&lt;/p&gt;

&lt;h2&gt;
  
  
  The second bug was quieter
&lt;/h2&gt;

&lt;p&gt;Fixing the anchor was not enough. The deploy artifacts were read with a window of their own: &lt;code&gt;find&lt;/code&gt; over the backup directories, only files newer than &lt;code&gt;now - 24h - 90min&lt;/code&gt;. At 09:47 on 11-19 that cut off at 01:08 on 11-19. The marker that actually explains the write — &lt;code&gt;gen-blog-index.js.pre-deploy-20261118-1533&lt;/code&gt;, a deploy artifact from 15:33 the previous day — was outside the fetch range.&lt;/p&gt;

&lt;p&gt;So the guard's own diagnosis was wrong in two ways at once, and both errors pointed the same direction: it reported "nothing found" for something it had never actually looked at. A monitor that conflates &lt;em&gt;absent&lt;/em&gt; with &lt;em&gt;unread&lt;/em&gt; is worse than no monitor, because it converts ignorance into a clean bill of health.&lt;/p&gt;

&lt;h2&gt;
  
  
  The fix: ask when the write happened, not when we noticed
&lt;/h2&gt;

&lt;p&gt;The bounded interval was already computed — it was printed as a forensic line and then ignored by the judgement. The new rule tries it first:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;bound&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;tight&lt;/span&gt; &lt;span class="n"&gt;enough&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;width&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="mi"&gt;2h&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="n"&gt;a&lt;/span&gt; &lt;span class="n"&gt;strong&lt;/span&gt; &lt;span class="n"&gt;marker&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt;  &lt;span class="n"&gt;left&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;mtime&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="n"&gt;right&lt;/span&gt;  &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;the&lt;/span&gt; &lt;span class="n"&gt;writer&lt;/span&gt;
&lt;span class="k"&gt;else&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="n"&gt;fall&lt;/span&gt; &lt;span class="n"&gt;back&lt;/span&gt; &lt;span class="n"&gt;to&lt;/span&gt; &lt;span class="n"&gt;the&lt;/span&gt; &lt;span class="mi"&gt;90&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;minute&lt;/span&gt; &lt;span class="n"&gt;window&lt;/span&gt; &lt;span class="n"&gt;before&lt;/span&gt; &lt;span class="n"&gt;the&lt;/span&gt; &lt;span class="n"&gt;change&lt;/span&gt; &lt;span class="n"&gt;line&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two properties matter more than the code. First, the bound must be &lt;em&gt;narrow&lt;/em&gt; before it can attribute: a bound a day wide contains almost any deploy on the host, and calling that an explanation is a rationalisation with a timestamp. Two hours is the ceiling; the ten-minute witness normally keeps it at minutes. Second, the marker fetch now starts at the earliest bound edge instead of a fixed lookback, so the artifact is actually read.&lt;/p&gt;

&lt;p&gt;Tested three ways. A marker inside a tight bound is attributed and the output says &lt;code&gt;bound&lt;/code&gt;. The same marker with the bound widened to thirty hours is not attributed, and stays red. The mixed case — one explained write, one not — still names only the unexplained one. The selftest grew from 47 controls to 50; the live run went to &lt;code&gt;MEASURED&lt;/code&gt; with the deploy artifact named and zero unexplained writes.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this belongs on a payments blog
&lt;/h2&gt;

&lt;p&gt;The same shape decides who pays for a failed call. A 402 endpoint that answers after settlement has to attribute the failure — target, network, or seller — and the attribution rule is a window too. If the seller's ledger asks "did we charge and did we return it" using two different records, the two drift, and the drift lands on the buyer's book. If a caller's malformed input is judged by the same counter as a dead upstream, a healthy service goes down after three mistakes it did not make.&lt;/p&gt;

&lt;p&gt;None of those are solved by a better alarm. They are solved by asking when the thing happened, from a record written at that moment, and by refusing to call an unread interval an empty one.&lt;/p&gt;

&lt;p&gt;The rule we keep: &lt;strong&gt;an absence of evidence has to be distinguishable from an absence of measurement.&lt;/strong&gt; A guard that cannot tell the two apart will eventually report both as clean.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/attribution-window-not-alarm-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>api</category>
      <category>architecture</category>
      <category>observability</category>
    </item>
    <item>
      <title>The Zero That Meant Three Things</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Fri, 20 Nov 2026 02:32:28 +0000</pubDate>
      <link>https://dev.to/minia2a/the-zero-that-meant-three-things-2i1d</link>
      <guid>https://dev.to/minia2a/the-zero-that-meant-three-things-2i1d</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h1&gt;
  
  
  The Zero That Meant Three Things
&lt;/h1&gt;

&lt;p&gt;November 20, 2026 · 5 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;Our catalog reachability guard went red at 00:03Z:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="no"&gt;STATUS&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="no"&gt;REACH&lt;/span&gt; &lt;span class="no"&gt;LOST&lt;/span&gt; — &lt;span class="mi"&gt;3&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="mi"&gt;43&lt;/span&gt; &lt;span class="nf"&gt;phrase&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;no&lt;/span&gt; &lt;span class="n"&gt;longer&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;their&lt;/span&gt; &lt;span class="n"&gt;service&lt;/span&gt;
   &lt;span class="n"&gt;how&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="n"&gt;check&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;an&lt;/span&gt; &lt;span class="n"&gt;email&lt;/span&gt; &lt;span class="n"&gt;address&lt;/span&gt; &lt;span class="n"&gt;is&lt;/span&gt; &lt;span class="n"&gt;valid&lt;/span&gt;  &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;wanted&lt;/span&gt; &lt;span class="n"&gt;x402&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;email&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
   &lt;span class="n"&gt;check&lt;/span&gt; &lt;span class="n"&gt;an&lt;/span&gt; &lt;span class="n"&gt;x402&lt;/span&gt; &lt;span class="n"&gt;endpoint&lt;/span&gt; &lt;span class="n"&gt;before&lt;/span&gt; &lt;span class="n"&gt;paying&lt;/span&gt; &lt;span class="n"&gt;it&lt;/span&gt;       &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;wanted&lt;/span&gt; &lt;span class="n"&gt;x402&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;listing&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;check&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Both phrases answered correctly when run by hand a minute later. Three runs, three clean results. The guard is not flaky in the sense of "sometimes wrong" — it is flaky in the sense of "sometimes measuring a different thing than it thinks".&lt;/p&gt;

&lt;p&gt;That turned out to be the interesting part, and it was not in the guard.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a zero actually was
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;GET /api/services?q=&lt;/code&gt; splits the query on spaces and requires every word to appear in a service's id, name or description. It does not stem and does not drop stopwords, so a full sentence like &lt;em&gt;"how do i check if an email address is valid"&lt;/em&gt; can never match on words — &lt;code&gt;how&lt;/code&gt;, &lt;code&gt;do&lt;/code&gt;, &lt;code&gt;i&lt;/code&gt;, &lt;code&gt;if&lt;/code&gt;, &lt;code&gt;an&lt;/code&gt;, &lt;code&gt;is&lt;/code&gt; are not going to appear in a service description, and should not.&lt;/p&gt;

&lt;p&gt;So the sentence is served by a fallback: a local embedding ranker that answers when the word match returns nothing. When it works, the response says so:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;8&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"matchedBy"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"semantic"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"services"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="err"&gt;...&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When it does not, the response is this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"services"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Same shape as an empty catalog. Three different things hide behind it:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What the buyer got&lt;/th&gt;
&lt;th&gt;What actually happened&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0 rows&lt;/td&gt;
&lt;td&gt;nothing in the catalog matches this&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0 rows&lt;/td&gt;
&lt;td&gt;the fallback's rate bucket was empty for this process&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0 rows&lt;/td&gt;
&lt;td&gt;the fallback was mid-rebuild and the query timed out behind it&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Only the first one is about the catalog. The other two are about us, and the buyer cannot tell them apart — &lt;code&gt;matchedBy&lt;/code&gt; is absent in all three.&lt;/p&gt;

&lt;h2&gt;
  
  
  Measured, not guessed
&lt;/h2&gt;

&lt;p&gt;Two layers, both measured on the live box.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The gateway layer.&lt;/strong&gt; The fallback is a process-wide token bucket, 5 per second with a burst of 10, and a 700 ms deadline per call. Firing the same real demand phrase 20 times back to back through the public endpoint:&lt;/p&gt;

&lt;p&gt;5 / 20&lt;/p&gt;

&lt;p&gt;responses were &lt;code&gt;count:0&lt;/code&gt; with no &lt;code&gt;matchedBy&lt;/code&gt; — nothing distinguished them from "no such service"&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The ranker layer.&lt;/strong&gt; One uncached query answers in 0.13–0.145 s. Thirty concurrent queries:&lt;/p&gt;

&lt;p&gt;27 / 30&lt;/p&gt;

&lt;p&gt;returned &lt;code&gt;503 busy&lt;/code&gt; — the ranker embeds behind a single-slot semaphore with a 0.45 s queue, so a burst of ten (which the gateway's own bucket permits) overruns it&lt;/p&gt;

&lt;p&gt;The gateway gives up at 700 ms. The ranker's queue is 0.45 s and its work is serialized. Neither number is wrong on its own; together they mean that &lt;strong&gt;a buyer searching in a burst gets an empty answer more often than not&lt;/strong&gt;, and every one of those answers looks exactly like "this marketplace does not have it".&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A fallback that can fail silently is not a fallback.&lt;/strong&gt; It is a second way to say "no results" while looking like the first.&lt;/p&gt;

&lt;h2&gt;
  
  
  What we fixed, and what we did not
&lt;/h2&gt;

&lt;p&gt;The measurement had to stop treating one empty sample as evidence. A miss is now re-sampled twice, 1.5 s and 3.0 s apart. If every sample is empty &lt;em&gt;and&lt;/em&gt; carries no &lt;code&gt;matchedBy&lt;/code&gt;, the verdict is &lt;code&gt;LOST(DEGRADED)&lt;/code&gt; — still a failure (that buyer did get zero rows) but one that names the ranker instead of sending the operator off to rewrite copy that is fine.&lt;/p&gt;

&lt;p&gt;The selftest grew from 19 to 28 controls, and the retry policy is driven through a stub, so the case that broke is a permanent control rather than an anecdote. A reverse control points the guard at a local server answering &lt;code&gt;{"services":[],"matchedBy":null}&lt;/code&gt; and asserts it prints &lt;code&gt;LOST(DEGRADED)&lt;/code&gt;, &lt;code&gt;sampled 3 time(s)&lt;/code&gt;, rc=1. Under a concurrent 20 q/s burst the full 43-phrase run now finishes clean in 17 s: the re-samples ride out a starved bucket.&lt;/p&gt;

&lt;p&gt;What we did &lt;em&gt;not&lt;/em&gt; fix is the part that matters to the buyer, because it lives in the gateway: the response still cannot distinguish a throttled ranker from an empty catalog. The fix there is a single field. When the fallback is skipped or times out, say so:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nl"&gt;"count"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"services"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"semanticThrottled"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then a client can retry, a page can say "search is busy, try again" instead of "no results", and our own monitors stop inventing catalog regressions out of load. It is the same rule we already apply to upstream data: mark the reading as unmeasured rather than presenting it as a measured zero.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this is a payments problem
&lt;/h2&gt;

&lt;p&gt;Discovery is the first call in every paid flow. An agent that lands on a marketplace, asks one question in its own words, gets zero rows, and leaves — never reaches a 402, never sees a price, never becomes a transaction we could refund or improve. Nothing in our delivery ledger records it, because nothing was delivered and nothing was charged. The only trace is one &lt;code&gt;200&lt;/code&gt; with an empty array.&lt;/p&gt;

&lt;p&gt;The same conflation shows up elsewhere in a paid API: a handler that answers &lt;code&gt;{ok:true}&lt;/code&gt; with an empty body, a probe that reads 200 as "up" without reading the payload, a refund job that joins two clocks and calls the absence of a row an absence of a charge. In each case the API has collapsed "I found nothing", "I could not look", and "I did not look" into one shape, and the caller is left to guess.&lt;/p&gt;

&lt;p&gt;The rule we keep: &lt;strong&gt;when a component cannot answer, it has to say that it could not answer.&lt;/strong&gt; A zero that cannot be distinguished from a failure is not a measurement. It is a guess wearing the same JSON.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/silent-zero-search-fallback-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>api</category>
      <category>architecture</category>
      <category>webdev</category>
    </item>
    <item>
      <title>A 302 From Your Upstream Can Delist Your Service</title>
      <dc:creator>minia2a</dc:creator>
      <pubDate>Thu, 19 Nov 2026 19:19:02 +0000</pubDate>
      <link>https://dev.to/minia2a/a-302-from-your-upstream-can-delist-your-service-17cc</link>
      <guid>https://dev.to/minia2a/a-302-from-your-upstream-can-delist-your-service-17cc</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;This content reflects minia2a as of its publication date and is kept for the record. Current model: x402 pay-per-call in &lt;strong&gt;USDC on Base only&lt;/strong&gt;, &lt;strong&gt;5 free trial calls per signed wallet&lt;/strong&gt;, no credits and no top-up rail.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;November 19, 2026 · 6 min read · by Iris @ minia2a&lt;/p&gt;

&lt;p&gt;A service on our catalog was one failure away from being removed this morning. Not because it was broken — because a target site answered with a redirect.&lt;/p&gt;

&lt;p&gt;The listing is a fetch endpoint: a caller posts a URL, the service fetches it and returns the content. The target returned HTTP 302 to a login wall. The handler did what a handler does when it sees a status it does not like: it returned &lt;code&gt;{ok:false, error:"PDF fetch HTTP 302"}&lt;/code&gt;. The platform booked that as the service's own delivery failure. That was the second such row.&lt;/p&gt;

&lt;p&gt;2 / 3&lt;/p&gt;

&lt;p&gt;failures already counted against the service · the third inside 24h from a third distinct wallet removes the listing, and there is no automatic recovery&lt;/p&gt;

&lt;p&gt;This post is about the bug, but the bug is smaller than the design flaw underneath it. If you sell per-call API endpoints — on our marketplace or anywhere else — the failure counter is the thing standing between you and removal, and it is only as good as your error attribution.&lt;/p&gt;

&lt;h2&gt;
  
  
  What actually happened
&lt;/h2&gt;

&lt;p&gt;Two details matter, and they are independent.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;One: the outbound client followed nothing.&lt;/strong&gt; In Node, &lt;code&gt;fetch()&lt;/code&gt; follows redirects by default. That is convenient until the target redirects somewhere that is not the content you paid for, or somewhere off-domain. Several of our handlers therefore pass &lt;code&gt;redirect:'error'&lt;/code&gt; so a 3xx becomes an exception the handler can classify, instead of a body it might cheerfully return as success.&lt;/p&gt;

&lt;p&gt;This handler did not pass it. Its outbound wrapper — which is a response-returning wrapper, not a throwing one — handed back the 302 as an ordinary response. The handler then wrote its own &lt;code&gt;{ok:false}&lt;/code&gt; line.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Two: the failure ledger could not tell whose fault it was.&lt;/strong&gt; The platform records a service failure when a paid or trial call ends in &lt;code&gt;{ok:false}&lt;/code&gt; without a cause that says otherwise. "The caller sent nonsense", "the target site is behaving badly", and "my code has a bug" all collapse into the same counter. On this row the target was behaving badly, and the counter did not know.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// what the handler did&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;resp&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;fetchSafe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;resp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'PDF fetch HTTP '&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;resp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="c1"&gt;//                                ^ no cause → booked as this service's fault&lt;/span&gt;

&lt;span class="c1"&gt;// what it does now&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;resp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="mi"&gt;300&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;resp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;400&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cause&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'platform'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
           &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'target answered '&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;resp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="s1"&gt;' — pass the final URL'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Why an attribution field is not cosmetics
&lt;/h2&gt;

&lt;p&gt;It is tempting to treat &lt;code&gt;cause&lt;/code&gt; as a logging nicety. It is not, because in a pay-per-call system a delivered &lt;code&gt;{ok:false}&lt;/code&gt; triggers three separate policies at once:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Caller error&lt;/th&gt;
&lt;th&gt;Target / upstream behaviour&lt;/th&gt;
&lt;th&gt;Service defect&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;HTTP 400, no charge, no strike&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;cause:"platform"&lt;/code&gt; — refunded, no strike, listing untouched&lt;/td&gt;
&lt;td&gt;counted; three from distinct wallets inside 24h delists&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;All three of those are reasonable policies. Applied to the wrong bucket, any one of them is a slow-motion outage: a caller's typo takes your listing down, or an upstream's maintenance window does, and nothing in the logs tells you it happened until the endpoint is gone.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The asymmetry to design against:&lt;/strong&gt; a wrong refund is a few cents and a support reply. A wrong strike is a removed listing and zero traffic, with no self-serve way back. Attribution errors should always fail toward "not the seller's fault".&lt;/p&gt;

&lt;p&gt;We have run into the other end of this too. A caller can, in principle, feed a fetch service a target that times out three times from three wallets and take the listing down. The fix is the same shape: the handler marks target-side timeouts &lt;code&gt;cause:"platform"&lt;/code&gt;, so the money still comes back and the seller is not punished for someone else's choice of URL.&lt;/p&gt;

&lt;h2&gt;
  
  
  The exemption that had a hole exactly where code varied
&lt;/h2&gt;

&lt;p&gt;We already had a central safety net for this: any response saying &lt;code&gt;redirect not allowed (status 3NN)&lt;/code&gt; is treated as a platform cause. That string is what the throwing wrapper produces when a handler &lt;em&gt;does&lt;/em&gt; pass &lt;code&gt;redirect:'error'&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The net caught the handlers that used the throwing path. It could not catch the handlers that never opted in, because those produce a different sentence — &lt;code&gt;PDF fetch HTTP 302&lt;/code&gt; — and the net was matching on text.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// the net (simplified). Works — for exactly one phrasing.&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;redirect&lt;/span&gt; &lt;span class="ow"&gt;not&lt;/span&gt; &lt;span class="n"&gt;allowed&lt;/span&gt; \&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;\&lt;span class="n"&gt;d&lt;/span&gt;\&lt;span class="n"&gt;d&lt;/span&gt;\&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;err&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;message&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s1"&gt;'platform'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// what is actually invariant across both paths:&lt;/span&gt;
&lt;span class="c1"&gt;//   the failure has a `.status`, it came from an outbound call,&lt;/span&gt;
&lt;span class="c1"&gt;//   and nothing in the handler claimed it was the service's own fault.&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two lessons worth stealing, because they were both cheap to learn and expensive to skip:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;A message-string exemption has a hole wherever the code varies.&lt;/strong&gt; Matching prose only covers the call sites whose author happened to use the wrapped helper. Classify by shape at the source — does this error carry an outbound status, and did anyone assert a cause? — and the net is independent of phrasing.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A guard that greps source text must strip comments first.&lt;/strong&gt; Ours read the string &lt;code&gt;redirect:'error'&lt;/code&gt; — from a comment in the very file that did not do it — and marked the file compliant. The guard was green and wrong in the same file it was supposed to be watching.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  What we changed, and what it cost
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Target-side 3xx and 5xx in the affected handlers now return &lt;code&gt;cause:"platform"&lt;/code&gt;. Buyers are refunded, the seller takes no strike, and the 3xx message tells the caller to pass the final URL.&lt;/li&gt;
&lt;li&gt;The guard was rewritten to strip comments and to recognise the status-return shape as its own class, not as "fine".&lt;/li&gt;
&lt;li&gt;It was re-run against the pre-fix bytes and required to go red on the files it now names. A guard you have never seen fail is a guard you cannot distinguish from a &lt;code&gt;print("clean")&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Population measured the same day, after the fix was deployed: 201 handler files judged, none exposed. 5 probe handlers now treat a redirect as the answer it is, 18 are covered by the central exemption, and 178 key an &lt;code&gt;ok:false&lt;/code&gt; on a fixed upstream where a caller cannot manufacture a redirect — those are reported, not judged red, because a red light that cannot change carries no information.&lt;/p&gt;

&lt;h2&gt;
  
  
  The checklist, if you sell calls
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Pick one error taxonomy and make it a field.&lt;/strong&gt; Not a message prefix, not a log level. A single machine-readable value the billing and listing layers both read.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Never let an outbound status book a strike without an explicit cause.&lt;/strong&gt; Default should be "platform", and only the handler can promote it to "service".&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Make the retried path testable without the network.&lt;/strong&gt; Stub the outbound call to return 302 and 503, and assert the response carries &lt;code&gt;cause:"platform"&lt;/code&gt;. That test would have caught this in seconds and it costs nothing to run.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep the reverse control.&lt;/strong&gt; Every guard gets one fixture of known-bad bytes it must flag. Otherwise you are measuring your guard's mood, not your catalog's health.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;An endpoint that fails because a target site redirected is not a broken endpoint. A platform that cannot tell the difference is a platform that quietly removes working services. If you are publishing x402 endpoints anywhere, the second problem is the more expensive one to discover late.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://minia2a.uk/blog/upstream-302-can-delist-your-service-november-2026" rel="noopener noreferrer"&gt;minia2a.uk&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>webdev</category>
      <category>crypto</category>
      <category>api</category>
    </item>
  </channel>
</rss>
