DEV Community: Paul Spread

Four Strategies Around the bStock Delta: Arbitrage, Market Making, Signals, Alerts

Paul Spread — Tue, 29 Sep 2026 09:53:31 +0000

A tokenized stock lives on two markets at once: the token on a crypto exchange, the share on a stock exchange. The gap between them — the delta — supports several working strategies. Here is each one, with its risks.

A decade ago this toolkit belonged to institutions with dedicated market-data feeds and quant desks. Today an AI agent with a wallet can run the same loop — watch, decide, pay for its own data. That is what makes the tokenized-stocks market different from the equity market it mirrors: the tooling is open to anyone with USDC.

One number, four strategies: arbitrage (buy the cheap token, wait for convergence), market making (earn the spread on thin books), signal trading (the delta leads Monday's gap), and alerts as a service (the signal finds you).

1. Delta arbitrage

When the token trades below the share by more than your costs (fees + spread + slippage), buy the token and wait for convergence. Classic setup: a −2% delta on a closed exchange → buy the token → exit at parity. The risks: the delta can widen further (cut it with a stop), convergence can take days, and pool liquidity caps your position size. Enter only when you understand why the gap appeared.

2. Market making

bStock pools are thin — wide spreads mean you get paid for providing liquidity. A market maker earns the spread and fees, and the delta hints where quotes should move: token above the share — expect sellers; below — buyers.

3. Signal trading

Delta is a leading indicator. The token reprices on weekend news before the equity market opens. A trader watching the delta knows about Monday's gap on Saturday — and positions accordingly, with the usual risk that the gap never comes.

4. Alerts as a service

You do not have to trade the delta yourself — monitoring it is a product. Our tracker exposes it over MCP and Telegram: subscribe once, and a message arrives whenever any symbol's delta crosses the 0.5% threshold. The machine watches; you trade when it matters. The subscription settles on Arc in USDC — one on-chain transaction, receipt-verified, 30 days of real-time. The same asset you trade bStocks with pays for the signal.

The main rule

Delta is not free money — it is the price of risk: liquidity, issuer counterparty, rebalancing delays. A strategy works while costs stay below the divergence. Count the costs before entry, not after.

Series finale: the risks of tokenized stocks — what can go wrong.

Links

Agent guide (endpoints, limits, examples): agentbadge.xyz/bstock-guide
All articles in the series: agentbadge.xyz/blog
MCP endpoint: https://agentbadge.xyz/mcp/bstock/tools/get_delta

Not financial advice. These strategies carry real risk — size positions accordingly.

bStocks for Beginners: Tokenized Stocks Without the Magic

Paul Spread — Mon, 28 Sep 2026 07:14:58 +0000

A tokenized stock is a blockchain token whose price follows a real share. AAPLB mirrors Apple, TSLAB mirrors Tesla. Buy the token — get the same price exposure as the share, but on a crypto exchange, around the clock.

This is not a niche experiment — it is a bridge between two markets. For the financial ecosystem, tokenized stocks mean equities that trade when Wall Street sleeps, in sizes that fit any wallet, settled in stablecoins. For traders, they mean a new class of instruments — and a new spread to understand before trading it.

The issuer holds the real shares and issues tokens (AAPLB = Apple × 1.0006) that trade on Binance 24/7, settled in USDC. While the two markets agree, the delta is near zero; when they diverge — nights, weekends, news — the gap becomes an opportunity for some and a risk for others.

How it works under the hood

The issuer holds the real shares (or an equivalent) and issues tokens that mirror their value. The token trades on an exchange (for bStocks — Binance) 24/7, settles in stablecoins, and its price is anchored to the share through a multiplier — for AAPLB it is about 1.0006.

How a token differs from a share

Trading hours. The share trades during the exchange session; the token trades 24/7, weekends included.
Access. The share needs a broker, KYC, minimum lots; the token needs an exchange account and USDC.
Rights. The token usually carries no voting rights and no direct dividends — it is a price tracker, not equity in the company. Read the issuer's terms.
Fractionality. You can hold 0.01 of a share.

Why prices diverge — and what the delta is

Token and share are two different markets with different liquidity. At night the share sleeps while the token keeps trading — their prices drift apart. That gap is the delta.

A concrete picture: news breaks on Saturday. The stock cannot move until Monday's open. The token drops 3% within minutes. That is not the token "breaking" — that is the token market pricing the news before the stock market can. The delta makes this visible.

Where to start

Exchange account → USDC → buy a bStock. From the first trade, watch the delta: it shows how far the token has drifted from the original and hints at both opportunity (convergence trades) and risk (the gap can widen). Monitoring dozens of tokens around the clock is a job for a machine — which is exactly what delta trackers, including ours for AI agents, are for.

Our tracker exposes the delta to AI agents over MCP, and its paid tier runs on Arc — Circle's USDC-native chain — so an agent pays for real-time data the same way it holds collateral: in USDC, on-chain.

Next: strategies people actually run on the delta.

Links

Agent guide (endpoints, limits, examples): agentbadge.xyz/bstock-guide
All articles in the series: agentbadge.xyz/blog
MCP endpoint: https://agentbadge.xyz/mcp/bstock/tools/get_delta

Free vs Real-Time: When the bStock Delta Actually Pays

Paul Spread — Sat, 26 Sep 2026 14:16:57 +0000

The bStock delta tracker has two tiers: free (1 request per minute) and paid (real-time, 5 USDC for 30 days). A fair question from any trader: why pay when free exists?

The answer matters beyond one product. The delta is the health indicator of the whole tokenized-stocks market: the faster participants see divergence, the faster it corrects. A 24/7 market needs 24/7 monitoring — and that is a job for machines, not for humans with refresh buttons.

The free tier is one request per minute — a snapshot for a one-off check or research. The paid tier (5 USDC for 30 days) is real-time: unlimited polling, Telegram alerts at the 0.5% threshold, and an hourly digest.

What the free tier gives

One request per minute is a snapshot. Ask "what is AAPLB's delta" — get an answer. For research, a one-off check, a demo — enough. But between requests there is a minute of blindness. And delta lives exactly in those minutes.

What the paid tier gives

Unlimited requests — poll every second if your strategy needs it.
Telegram alerts — the tracker messages you when a delta crosses the 0.5% threshold. No polling at all; the signal finds you.
Hourly digest — a summary of everything that happened while you were away.
A 30-day ServicePass — one payment, a month of access, proof on-chain.

When the delta turns into money

Three scenarios where a minute of blindness costs more than the subscription:

Weekends. News drops on Saturday — the equity reacts on Monday, the token reacts now. A −3% delta on a closed exchange is advance information about Monday's gap.
Earnings. The report lands after the call — the stock is still in its auction, the token has already repriced.
Thin pools. One large order moves the token an hour before liquidity rebalances — the window opens and closes by itself.

In all three, the edge is not "seeing it eventually" — it is seeing it first.

Agent economics

5 USDC for 30 days of real-time is ~0.17 USDC a day. One caught arbitrage window on a tokenized stock pays for years of subscription. For an agent that trades or alerts on deltas, the paid tier is not an expense — it is infrastructure, like a market data feed.

And the payment itself is on-chain: 5 USDC on Arc, receipt verified in a block, ServicePass issued for 30 days. The agent's data budget is auditable on the same chain it trades on — no card statements, no billing portals, just transactions.

Next — the educational block: what bStocks are, for people new to tokenized stocks.

Links

Agent guide (endpoints, limits, examples): agentbadge.xyz/bstock-guide
All articles in the series: agentbadge.xyz/blog
MCP endpoint: https://agentbadge.xyz/mcp/bstock/tools/get_delta

x402 Payments on Arc Testnet: How an Agent Pays in USDC With No Facilitator

Paul Spread — Fri, 25 Sep 2026 11:15:07 +0000

In classic x402, a facilitator sits between the buyer and the seller: it takes the agent's signature and broadcasts the transaction on its behalf. Convenient — but an extra party to trust, an extra API to wait on, an extra point of failure.
On Arc we skipped it. The scheme is called self-settle — "settle it yourself".

The agent receives the 402 invoice, signs an EIP-3009 authorization (exactly 5 USDC to the treasury) and broadcasts on Arc itself — gas is paid in USDC. The server reads the receipt from the block: the Transfer event reached the treasury — access opens for 30 days.

Why Arc makes this possible

Arc is a blockchain built by Circle — the company behind USDC. Its signature feature: gas is paid in USDC, not in a separate token. A conventional agent would need to hold two assets: USDC for the payment and ETH for gas. On Arc one balance is enough — USDC covers both the payment and the fee.
For the tokenized-stocks market this closes the loop: bStocks settle in USDC on Binance, the agent's gas is USDC, and the data subscription is USDC. One asset for trading, for fees, and for information — that is what a market built for machines looks like.

The flow in 6 steps

The agent requests data → gets a 402 with the invoice: scheme, network, amount, recipient.
It signs an EIP-3009 authorization — the standard for "transfer with authorization": a signature that permits moving exactly 5 USDC from the agent's wallet to the recipient. Nothing more, no wallet access.
It broadcasts the transaction itself (hence "client-broadcast").
It waits for confirmation — seconds.
It retries the request with the transaction hash attached.
The server reads the blockchain: is the tx in a block, did USDC reach the treasury, is the amount right → access for 30 days.

What the server actually verifies

Not a signature — a receipt. The server asks the chain for getTransactionReceipt(txHash) and checks: the transaction is really in a block, it contains a Transfer event from the USDC contract to the treasury address, the amount covers the price. This cannot be forged: either the transaction is in a block or it does not exist.

What this gives the ecosystem

Removing the facilitator removes a point of failure and a trust assumption. Any wallet holding USDC on Arc becomes a payment client: one asset, one signature, one RPC call. For agents, buying data becomes as routine as calling an API.
This is infrastructure for the tokenized-assets ecosystem, not a demo. Real-time delta data is what keeps bStock prices honest — and the agents that buy it settle on Arc in USDC, the same asset the tokens themselves settle in. Every payment is a public, auditable transaction: the market's information layer becomes as transparent as its trading layer.
Next: when the delta actually pays — free tier vs real-time.

Links

Agent guide (endpoints, limits, examples): agentbadge.xyz/bstock-guide
Originally published on the AgentBadge blog: agentbadge.xyz/blog/bstock-arc-x402-payment
MCP endpoint: https://agentbadge.xyz/mcp/bstock/tools/get_delta

Freemium for AI Agents: Free vs Paid Tiers via HTTP 402 on Arc

Paul Spread — Thu, 24 Sep 2026 11:40:57 +0000

Originally published: https://agentbadge.xyz/blog/bstock-freemium-402
Tags: ai, api, webdev, cryptocurrency

Every SaaS has a free tier and a paid tier. But how do you sell the paid tier when the customer is not a person but a program? An agent has no card, cannot fill a checkout form, cannot type a CVV.

We solved it with HTTP 402 Payment Required — a status code that waited three decades for its moment. It is not an error. It is an invoice.

Why does this matter beyond our tracker? Tokenized stocks trade around the clock, and the traders who watch them increasingly delegate monitoring to AI agents. An agent that cannot pay for its own data is a crippled market participant. Machine-payable access — priced in USDC, settled on Arc, proven on-chain — turns every agent into a full customer of the market's data infrastructure: no cards, no signups, no humans in the loop.

Every request passes three doors: a live ServicePass means instant real-time; otherwise the free bucket allows one request per minute (a snapshot); otherwise the server answers 402 with an invoice. One USDC transaction (5 USDC on Arc), an on-chain receipt check — and the agent holds a 30-day ServicePass.

How the gate works

Every request to the tracker passes three checks:

Already paid? If the agent holds a live ServicePass (a 30-day access token) — data flows immediately.
Free allowance? One request per minute is free. A snapshot, not a stream.
Neither? The server answers 402 and attaches an invoice to the response: what, to whom, how much.

Inside the invoice

The 402 response is not just text. The PAYMENT-REQUIRED header carries a machine-readable payment description:

{
  "x402Version": 2,
  "accepts": {
    "scheme": "eip3009-client-broadcast",
    "network": "eip155:5042002",
    "asset": "USDC",
    "amount": "5000000",
    "payTo": "0xcdd2...699d",
    "maxTimeoutSeconds": 345600
  }
}

The agent reads it like a price list: the payment scheme (EIP-3009 — a standardized transfer signature), the network (Arc Testnet), the asset (USDC), the amount (5 USDC — the six zeros are decimals, the amount is in base units), the recipient, and the invoice expiry (4 days).

Why not API keys and billing portals

An API key needs signup, an email, a card, invoices — a human in the loop. 402 + x402 is a programmable paywall: the agent sees the price → signs a transfer → pays → gets access. The whole cycle takes seconds. For a machine, this is the native way to buy things.

And because it runs on Arc — Circle's blockchain where gas itself is paid in USDC — the agent needs exactly one asset in its wallet. One balance covers the payment and the fee. For a market where bStocks themselves settle in USDC, the plumbing finally matches the asset.

One payment pays once

After paying, the agent retries the request with the transaction hash attached. The server checks the blockchain — not a claimed signature, but the real receipt from a block — and opens access. The same hash cannot be presented twice: the server atomically claims it, and a second attempt gets tx_replayed. Even ten parallel requests with the same hash — exactly one gets through.

A paywall a program can read and pay turns data into a first-class on-chain service. More agents able to buy real-time data means more eyes on tokenized markets — tighter deltas, faster convergence, healthier price discovery for everyone who trades them.

Next: the payment itself on Arc — and why gas there is paid in USDC.

Links

Agent guide (endpoints, limits, examples): agentbadge.xyz/bstock-guide
Originally published on the AgentBadge blog: agentbadge.xyz/blog/bstock-freemium-402
MCP endpoint: https://agentbadge.xyz/mcp/bstock/tools/get_delta

Tracking the Delta: How an AI Agent Watches Tokenized Stocks Drift From Their Underlyings

Paul Spread — Wed, 23 Sep 2026 19:13:29 +0000

Picture this: Apple trades at $336.45 on Nasdaq. Tokenized Apple (AAPLB on Binance) trades at $336.44 at the same moment. A penny apart — noise. But on a Saturday night, with Nasdaq asleep, AAPLB can drift to −2%. That is not noise anymore. That is a signal.

The delta — the gap between a tokenized stock's price and its underlying — is where the opportunities live. Humans cannot watch 20+ tokens around the clock. A machine can. So we built a tracker that computes the delta in real time and handed it to AI agents.

Binance streams token prices around the clock; Finnhub/Alpaca supply the equity prices. DeltaEngine computes the delta, the market phase (O/C/P) and the stale flag (15s without updates). The MCP server exposes it to the agent through five tools, and Telegram receives an alert the moment a delta crosses the 0.5% threshold.

What the tracker computes

For every bStock the tracker keeps two prices:

bStockPrice — the token's price on Binance, where tokenized stocks trade 24/7;
underlyingPrice — the real stock's price from market data providers (Finnhub, with an Alpaca fallback).

Delta in percent: (tokenPrice − stockPrice) / stockPrice × 100. Alongside it, three flags a trader actually needs:

phase — is the stock market open (O), closed (C), or in pre-market (P);
stale — the price feed went quiet for more than 15 seconds, so treat the number with care;
inAlert — the delta crossed the 0.5% threshold (configurable).

A live response looks like this:

{"symbol":"AAPLB","underlying":"AAPL","multiplier":1.0006,
 "bStockPrice":336.44,"underlyingPrice":336.45,
 "deltaPct":-0.064,"phase":"O","stale":false,"inAlert":false}

How an agent uses it

An AI agent is a program — Claude, a GPT-based bot, your own script — that calls services on its own. Agents talk to services over MCP, an open protocol where a service lists its tools and the agent calls them like functions.

The tracker is an MCP server with these tools:

get_delta — delta for one symbol;
list_deltas — all symbols at once;
get_quote — current quote;
get_events — event history (threshold crossings, stale feeds);
get_digest — the day's summary.

curl -X POST https://agentbadge.xyz/mcp/bstock/tools/get_delta \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"symbol": "AAPLB"}'

There is also Telegram: subscribe_telegram registers the agent's operator, and the tracker pushes a message whenever a delta crosses 0.5%. No polling needed — the signal finds you.

Freemium: a snapshot for free, the stream for a fee

The first request each minute is free. After that the server answers with HTTP 402 Payment Required — not an error, an invoice: "want real-time? pay". The x402 standard lets the agent pay automatically: 5 USDC on the Arc network buys 30 days of access. No signup, no card, one on-chain transaction — gas paid in USDC too, an Arc specialty. The server verifies the transaction on-chain and opens the door. The same payment cannot be replayed — replay protection is built in.

Why a trader should care

A −0.06% delta is noise. A −2% delta on a closed exchange means "the token was sold off and the equity has not woken up yet". Whoever sees it first captures the convergence. A person cannot monitor every token every second — an agent can, and it pays for its own data feed without a human in the loop.

Next: inside the 402 paywall — how freemium works when the customer is a machine.

Links

Agent guide (endpoints, limits, examples): agentbadge.xyz/bstock-guide
Originally published on the AgentBadge blog: agentbadge.xyz/blog/bstock-delta-tracker-case
MCP endpoint: https://agentbadge.xyz/mcp/bstock/tools/get_delta

Inside an Agent Readiness Scanner: Rules, Evidence and Reproducibility

Paul Spread — Fri, 28 Aug 2026 12:09:49 +0000

Originally published at AgentBadge.

When someone tells you that an API has an 87/100 Agent Readiness score, the first question should not be:

"Is 87 a good score?"

The better question is:

"Why is it 87?"

And the question after that is even more important:

"Can I reproduce the result myself?"

This is the problem AgentBadge is designed to solve.

Agent Readiness should not be an opinion generated by an LLM. It should be a measurable property of a service, calculated from explicit rules and supported by evidence.

The core idea is simple:

Rules → Evidence → Assertions → Score → Report

This article explains what happens inside that pipeline.

1. A scanner should measure, not guess

Imagine two tools scanning the same API.

Tool A says:

"Your API appears to be highly suitable for AI agents."

Tool B says:

"AB-004 passed because https://example.com/openapi.json returned HTTP 200 and contained a valid OpenAPI document."

Which result would you trust?

The second one is much more useful.

It tells you:

what was checked;
what rule was applied;
what evidence was found;
why the rule passed or failed;
and where the evidence came from.

This is the fundamental design principle behind AgentBadge:

Every meaningful score should be explainable through evidence.

The scanner should not ask an AI model:

"How agent-ready does this API feel?"

It should ask deterministic questions such as:

"Does this URL exist?"

"Does it return the expected content type?"

"Does the response contain an OpenAPI document?"

"Does the declared authentication mechanism contain the required information?"

The difference may look subtle, but architecturally it is enormous.

2. Rules are the measurement instrument

A scanner is only as trustworthy as its rules.

Instead of hiding the evaluation logic inside application code, AgentBadge treats rules as explicit, versioned measurement definitions.

A simplified rule might look conceptually like this:

AB-001
Name: OpenAPI discoverability

Given:
  target = https://example.com

Check:
  GET /.well-known/openapi.json

Pass when:
  HTTP status = 200
  AND response is valid OpenAPI

Evidence:
  URL
  HTTP status
  content type
  content hash

Severity:
  medium

The important property is that another implementation should be able to understand the same rule.

The rule is not:

"The API looks well documented."

It is:

"This specific machine-readable artifact was found and passed these specific checks."

That makes the scanner much easier to test, audit and reproduce.

3. Deterministic before intelligent

This leads to one of the most important architectural principles of AgentBadge:

Deterministic before intelligent.

If something can be established deterministically, use deterministic logic.

For example:

Question	Preferred method
Does robots.txt exist?	HTTP request
Does sitemap exist?	HTTP request + parser
Does OpenAPI exist?	HTTP request + schema validation
Is JSON valid?	JSON parser
Does declared endpoint exist in another document?	Exact matching
What does an undocumented endpoint mean?	AI-assisted inference
What does an API capability actually mean?	Human confirmation / assisted review

AI has a role, but it should not become the judge of facts that can be verified directly.

An LLM can help interpret ambiguous documentation.

It should not silently decide that an API supports refunds simply because a paragraph mentions the word "refund."

This is why AgentBadge treats AI as a copilot, not as the authority responsible for the score.

4. Evidence is the missing layer

A score without evidence is difficult to trust.

Consider this finding:

Documentation: 18/25

There is almost nothing you can do with it.

Now consider:

AB-007  OpenAPI discoverability

STATUS: VERIFIED

Evidence:
GET https://api.example.com/openapi.json
HTTP 200
Content-Type: application/json

OpenAPI version:
3.1.0

Confidence:
1.00

Now the developer knows what happened.

They can inspect the same resource themselves.

This creates a chain:

HTTP response → Evidence → Assertion → Rule result → Category score → Overall score

The evidence is therefore not an optional explanation attached to the report.

Evidence is part of the measurement itself.

5. Assertions connect evidence and scoring

A useful internal abstraction is an assertion.

An assertion answers one concrete question.

For example:

{
  "rule_id": "AB-007",
  "status": "VERIFIED",
  "target": "https://api.example.com/openapi.json",
  "evidence": {
    "http_status": 200,
    "content_type": "application/json"
  },
  "confidence": 1.0
}

The important states are intentionally explicit.

VERIFIED

The scanner found direct evidence supporting the assertion.

INFERRED

The scanner has a reasonable interpretation, but the evidence is not sufficient to treat it as fact.

CONFLICT

Two sources disagree.

For example:

Guide says: POST /refund
OpenAPI says: POST /refund-request

MISSING

The expected capability or artifact could not be found.

These states are more informative than a simple pass/fail system.

They tell us not only what the scanner thinks, but also how strongly it knows it.

6. Confidence is not the same as verification

This distinction is important.

A scanner may infer something with high confidence.

That does not automatically make it verified.

For example, an API documentation page might strongly suggest that a service supports refunds.

An LLM may assign a confidence of 0.94 to that interpretation.

But unless there is machine-readable evidence supporting the capability, the assertion should not magically become VERIFIED.

Instead: INFERRED, confidence: 0.94

The user can then: Confirm, Edit, Reject

This is the boundary between automatic fixes and assisted fixes.

Safe, deterministic changes can be automated.

Semantic claims require human confirmation.

7. Reproducibility matters

Now we arrive at the second major property of the scanner.

Suppose you scan https://api.example.com today and receive 76/100.

Someone else runs the same rules against the same captured state and should be able to understand how the result was produced.

That requires more than storing the final number.

The report needs to describe the measurement context.

Conceptually:

{
  "target": "https://api.example.com",
  "ruleset": "agent-readiness-v1.0",
  "scanner_version": "0.1.0",
  "timestamp": "...",
  "assertions": [...],
  "score": {
    "total": 76,
    "categories": {
      "discovery": 18,
      "documentation": 20,
      "authentication": 17,
      "machine_readability": 21
    }
  }
}

This allows the score to be understood as the output of a defined measurement process rather than a mysterious number.

8. Rules must be versioned

Rules change. New standards appear. New machine-readable formats emerge.

Some checks eventually turn out to be too strict or too weak.

Therefore: Agent Readiness v1.0 must not silently become v1.1 while pretending the results are identical.

Each ruleset should have an explicit version.

Now a report can say: Score: 82/100, Ruleset: Agent Readiness v1.2

This gives us an important property:

Same target + same measurement state + same ruleset = reproducible result.

9. Why open rules do not destroy the product

If AgentBadge publishes its rules, can't someone simply copy them?

Yes. And that is intentional.

The goal is not to create a secret scoring algorithm. The goal is to establish a useful measurement standard.

The long-term value comes from the workflow around that standard: open specification, open scanner, GitHub Action, README badge, continuous monitoring, regression alerts, fix workflow, developer adoption.

A competitor can copy AB-001, AB-002, AB-003.

They cannot instantly copy: thousands of repositories displaying the badge, existing GitHub Actions, developer habits, historical scan data, integrations, workflow configuration, trust built around independently verifiable reports.

The moat is not secret rules. It is a standard installed inside the developer workflow.

10. The score should explain itself

A single number is useful for quick comparison. But it should never be the only information available.

Suppose a developer's score changes: 76 to 72.

The product should explain the delta: +8 OpenAPI documentation detected, -12 New authentication issue detected, +0 Discovery unchanged. Result: 76 to 72.

This turns measurement into an improvement loop.

11. From Measure to Prove to Improve

The architecture becomes a simple loop: Measure, Prove, Improve, Measure again.

The score is the beginning of the workflow, not the end.

12. What AgentBadge should never claim

AgentBadge measures Agent Readiness.

It does not certify: API security, business correctness, service reliability, legal compliance, quality of business logic, whether an agent should trust the company.

A high score does not mean "This API is safe." It means "This API satisfied these measurable Agent Readiness criteria."

Don't certify. Measure.

13. What this enables

Once the measurement layer exists, many higher-level products become possible.

A developer can run npx @agentbadge/cli scan https://api.example.com.

A CI pipeline can enforce a minimum score. A README can display the current measurement. A platform can query AgentBadge programmatically. An organization can compare vendors using the same ruleset.

14. The bigger idea

The web has spent years developing tools for measuring websites. Performance has metrics. Accessibility has automated checks. Security has scanners. TLS has analyzers. SEO has crawlers and validators.

The emerging agentic web needs something similar.

AgentBadge's approach is deliberately conservative: Define the rules. Collect the evidence. Show the reasoning. Version the rules. Make the result reproducible.

That is what makes Agent Readiness a measurement discipline rather than another AI-generated checklist.

Read more:

What Is Agent Readiness? — Article 1
Why AI Agents Fail to Use APIs — Article 5
What Does an AI Agent Need to Understand an API? — Article 6
Why Your OpenAPI Spec Isn't Enough — Article 7
How Do You Measure Agent Readiness? — Article 8

Agent Knowledge Layer: agentbadge.xyz/agent-guide

Inside an Agent Readiness Scanner: Rules, Evidence and Reproducibility

Paul Spread — Fri, 28 Aug 2026 06:26:46 +0000

Originally published at AgentBadge.

When someone tells you that an API has an 87/100 Agent Readiness score, the first question should not be:

"Is 87 a good score?"

The better question is:

"Why is it 87?"

And the question after that is even more important:

"Can I reproduce the result myself?"

This is the problem AgentBadge is designed to solve.

Agent Readiness should not be an opinion generated by an LLM. It should be a measurable property of a service, calculated from explicit rules and supported by evidence.

The core idea is simple:

Rules → Evidence → Assertions → Score → Report

1. What the scanner actually does

The scanner does not ask an LLM "is this API good?"

It runs deterministic checks:

Does robots.txt exist?
Does /.well-known/openapi.json return 200?
Is the response valid OpenAPI?
Does the homepage have machine-readable metadata?
Is there an agents.txt file?
Are there llms.txt or llms-full.txt files?
Does the API support content negotiation?
Is there an A2A agent card?

Each check produces evidence. Each piece of evidence becomes an assertion. Each assertion has a status.

AI-assisted inference is used when deterministic checks are insufficient — but it is a copilot, not the judge.

2. Rule structure

Every rule follows the same structure:

AB-001
Name: OpenAPI discoverability

Given:
  target = https://example.com

Check:
  GET /.well-known/openapi.json

Pass when:
  HTTP status = 200
  AND response is valid OpenAPI

Evidence:
  URL
  HTTP status
  content type
  content hash

Severity:
  medium

This is not a prompt. It is a specification.

The rule says what to check, what constitutes a pass, and what evidence to collect.

3. Assertion states

Every assertion has exactly one of four states:

State	Meaning
VERIFIED	Direct evidence found
INFERRED	Reasonable interpretation, insufficient evidence
CONFLICT	Two sources disagree
MISSING	Expected capability or artifact not found

An LLM can be 94% confident that an API supports refunds. Without machine-readable evidence, the assertion stays INFERRED.

Confidence is not the same as verification.

4. Evidence is part of the measurement

Evidence is not an optional explanation attached after the fact.

Each finding includes:

The actual HTTP response (where applicable)
The URL checked
The content type received
A content hash
The timestamp of the check

This means the assertion is not just "OpenAPI exists: yes" — it is "OpenAPI exists: yes, here is the proof."

{
  "rule_id": "AB-007",
  "status": "VERIFIED",
  "target": "https://api.example.com/openapi.json",
  "evidence": {
    "http_status": 200,
    "content_type": "application/json"
  },
  "confidence": 1.0
}

5. Scoring has category floors

The total score is not a simple average.

Some categories are foundational. If Discovery = 0, it does not matter how good the documentation is — agents cannot find the API.

Category floors prevent a high score from hiding a critical zero.

A score of 91/100 with Discovery = 0 is not a good score. It is a misleading one.

6. What confidence means and what it does not

An LLM can analyze an API documentation page and say:

"This API likely supports token-based authentication with rate limiting."

That is a reasonable inference. But without machine-readable evidence (an OpenAPI spec, a response header, a well-known endpoint), it remains INFERRED.

The user can then:

Confirm — "Yes, this is correct, I checked manually"
Edit — "Almost right, but the auth method is different"
Reject — "No, this is wrong"

This creates a feedback loop: automatic fixes for deterministic changes, human confirmation for semantic claims.

7. Reproducibility

If the scanner gives a score of 76/100 for https://api.example.com today, someone else running the same rules against the same captured state should be able to understand how the result was produced.

The report needs to describe the measurement context:

{
  "target": "https://api.example.com",
  "ruleset": "agent-readiness-v1.0",
  "scanner_version": "0.1.0",
  "timestamp": "...",
  "assertions": [...],
  "score": {
    "total": 76,
    "categories": {
      "discovery": 18,
      "documentation": 20,
      "authentication": 17,
      "machine_readability": 21
    }
  }
}

8. Rules must be versioned

Rules change. New standards appear. Some checks eventually turn out to be too strict or too weak.

Agent Readiness v1.0 must not silently become v1.1 while pretending the results are identical.

Each ruleset has an explicit version. A report can say:

Score: 82/100

Ruleset: Agent Readiness v1.2

Same target + same measurement state + same ruleset = reproducible result.

9. Why open rules do not destroy the product

If AgentBadge publishes its rules, can't someone simply copy them?

Yes. And that is intentional.

The goal is not a secret scoring algorithm. The goal is a useful measurement standard.

The long-term value comes from the workflow around that standard:

Open specification → Open scanner → GitHub Action → README badge → Continuous monitoring → Regression alerts → Fix workflow → Developer adoption

A competitor can copy rules. They cannot instantly copy:

thousands of repositories displaying the badge
existing GitHub Actions
developer habits
historical scan data
integrations
trust built around independently verifiable reports

The moat is not "our rules are secret." It is "our standard is installed inside the developer workflow."

10. The score should explain itself

If a developer's score changes from 76 → 72, the product should explain the delta:

+8  OpenAPI documentation detected
-12  New authentication issue detected
+0   Discovery unchanged

Result: 76 → 72

Without a breakdown, a developer who fixed three problems and still sees the score decrease will think the product is broken.

With a breakdown, it becomes: "The scanner found something new. Now I know what to fix."

11. From Measure to Prove to Improve

The architecture is a loop:

MEASURE → PROVE → IMPROVE → Measure again

The score is the beginning of the workflow, not the end.

12. What AgentBadge should never claim

AgentBadge measures Agent Readiness. It does not certify:

API security
business correctness
service reliability
legal compliance
whether an agent should trust the company

A high score means: "This API satisfied these measurable Agent Readiness criteria."

Don't certify. Measure.

13. What this enables

npx @agentbadge/cli scan https://api.example.com

A CI pipeline can enforce a minimum score. A README can display the current measurement. A platform can query AgentBadge programmatically. An organization can compare vendors using the same ruleset.

14. The bigger idea

Performance has metrics. Accessibility has automated checks. Security has scanners. TLS has analyzers. SEO has crawlers and validators.

The emerging agentic web needs something similar.

Don't ask an AI to invent a score.

Define the rules. Collect the evidence. Show the reasoning. Version the rules. Make the result reproducible.

Then let developers improve their systems.

Read more:

What Is Agent Readiness? — Article 1
Why AI Agents Fail to Use APIs — Article 5
What Does an AI Agent Need to Understand an API? — Article 6
Why Your OpenAPI Spec Isn't Enough — Article 7
How Do You Measure Agent Readiness? — Article 8

Agent Knowledge Layer: agentbadge.xyz/agent-guide

How Do You Measure Agent Readiness?

Paul Spread — Wed, 26 Aug 2026 13:11:26 +0000

If Agent Readiness is real, it should be measurable. And the measurement should be reproducible.

You've read about what Agent Readiness is. You've seen why AI agents fail to use APIs and what an agent needs to understand. You know why OpenAPI alone isn't enough.

Now the question shifts from "what" to "how":

How do you objectively determine whether an API is ready for AI agents?

This article introduces a measurement framework for Agent Readiness — one built on deterministic checks, evidence, and reproducibility. Not opinions. Not LLM scores. Measurable properties that any scanner can verify.

The Measurement Problem

Labels like "AI-friendly API", "Agent-ready", and "Optimized for AI" are everywhere. They sound useful. They aren't.

Two auditors can look at the same API and disagree on whether it's "agent-friendly." An LLM can score the same API differently on different runs. A marketing page can claim "AI-optimized" without any way to verify what that means.

The problem isn't that these labels are wrong. The problem is that they're not reproducible. If two people can look at the same API and reach different conclusions, the measurement isn't real — it's an opinion.

If Agent Readiness is a real property of an API, it should be measurable. And the measurement should satisfy a simple requirement:

same URL + same ruleset + same point in time = same result

This is the reproducibility requirement. It's what separates measurement from opinion.

What Should We Measure?

Agent Readiness isn't a single number. It's a set of properties across four categories:

Discovery — Can an agent find the API?
Documentation — Can an agent understand the API?
Authentication — Can an agent authenticate autonomously?
Machine Readability — Can an agent interact machine-to-machine?

But these aren't just checkboxes. Each category contains specific, testable assertions — properties that can be verified with HTTP requests:

Discovery
  ✓ OpenAPI is discoverable
  ✓ llms.txt exists
  ✓ Documented API entry point exists

Authentication
  ✓ Authentication mechanism is declared
  ✓ Required credentials are documented
  ✓ Protected endpoint behavior is understandable

The question isn't "does the API have OpenAPI?" The question is "can we verify that OpenAPI is discoverable?" — and that's a testable property.

Deterministic Before Intelligent

This is the central principle of the measurement framework.

First:

HTTP response → Rule → Evidence → Result

Then, AI can help interpret complex cases. But the AI is a copilot, not the primary engine.

The wrong approach:

URL → LLM → "Looks agent-ready: 76/100"

The right approach:

URL → Deterministic scanner → Evidence → Rules → Score → AI copilot (optional)

This is what distinguishes AgentBadge from an AI auditor. Deterministic checks are reproducible — same input, same output, every time. LLM assessments are not. An LLM might score the same API as 76 today and 82 tomorrow. A deterministic scanner will give you the same result as long as the API hasn't changed.

This doesn't mean AI is useless. AI is excellent at interpreting ambiguous evidence, suggesting fixes, and explaining results. But the measurement itself — the check, the evidence, the score — should be deterministic.

Evidence, Not Opinions

Every assertion in the measurement framework comes with evidence. Not "we think this is true" — but the actual HTTP response that proves it.

Here's what an evidence card looks like:

OPENAPI_DISCOVERABLE
Status: VERIFIED

Evidence:
  GET /openapi.json
  HTTP 200
  Content-Type: application/json
  Valid OpenAPI document

This is the key difference between measuring and certifying. A certification says "this API is agent-ready." An evidence card says "here is the HTTP response that proves OpenAPI is discoverable."

Don't tell developers what to believe. Show them what we measured.

When every assertion includes evidence, the conversation changes. Instead of debating whether an API is "ready," you can point to specific findings: 72 checks run, 58 passed, 14 failed — here's the evidence for each.

Assertions

A scan result is not a magic score. It's a set of assertions — each one testable, each one with a status and evidence:

Assertion	Status	Evidence
OpenAPI discoverable	VERIFIED	`/openapi.json → 200`
Authentication documented	VERIFIED	`securitySchemes` present in spec
Machine-readable errors	MISSING	HTML error response, not structured
Agent guide	MISSING	`404 /agent-guide.json`

This table is the heart of the measurement. Before you look at the score, you look at the assertions. Each assertion tells you something specific about the API — and each one is independently verifiable.

VERIFIED / INFERRED / CONFLICT / MISSING

Every assertion has one of four statuses:

VERIFIED — Direct proof exists. The scanner found the evidence.
MISSING — Not found. The scanner looked and didn't find it.
INFERRED — There are reasonable grounds to believe this is true, but the evidence is insufficient for verification.
CONFLICT — Two sources contradict each other.

Here's a real example of CONFLICT:

OpenAPI spec says:    POST /refund
Agent Guide says:     POST /refund-request

Two sources, same API, different paths. The assertion status is CONFLICT — not VERIFIED, not MISSING. The scanner can't verify which is correct without making a live request, so it flags the contradiction.

The distinction between INFERRED and VERIFIED matters. INFERRED means "this looks right, but we can't prove it." VERIFIED means "here's the proof." An API that claims to have structured errors but returns text/html on error responses isn't VERIFIED — it might be INFERRED or MISSING depending on what the scanner found.

Confidence is not the same thing as verification.

Scoring

Only after assertions are established do we compute a score. The score is derived from the assertions — not the other way around.

Discovery           18/20
Documentation       19/25
Authentication      17/20
Machine Readability 15/20
Verification        10/15
─────────────────────────
Total               79/100

There's a critical rule in the scoring model: category floor. A high total score should not hide a critical zero in a fundamental category.

If Discovery = 0, the API is effectively invisible to agents. No amount of excellent documentation or perfect authentication can compensate for the fact that agents can't find the API. A score of 91/100 with Discovery = 0 is misleading — it suggests the API is nearly ready when it's actually missing the most fundamental layer.

The category floor prevents this. If any critical category is zero, the total score is capped. A high score should reflect actual readiness, not average out a fatal gap.

A high score should not hide a critical zero.

Score ≠ Certification

AgentBadge doesn't say "this API is safe" or "this API is approved for agents."

It says: "Here is what we measured, under this ruleset, at this point in time."

This distinction matters for three reasons:

Trust — Developers can verify the evidence themselves. They don't need to trust a badge; they can check the proof.
Legal risk — Certification implies endorsement. Measurement implies observation. AgentBadge observes and reports; it doesn't endorse.
Reproducibility — Anyone can run the same checks and get the same results. The measurement is transparent, not opaque.

Don't certify. Measure.

Reproducibility

A measurement is only useful if it can be independently verified. The reproducibility formula is:

URL + timestamp + ruleset version + scan artifact + report hash

Example:

Agent Readiness v1.0
Scan: 2026-08-26T14:03:22Z
Ruleset: agentbadge-ruleset@1.0.0
Report hash: a3f7b2c1...
Score: 79/100

Every scan records the URL, the timestamp, the ruleset version, and produces a report hash. The scan artifact is preserved. Another scanner — or another developer — can run the same checks against the same URL with the same ruleset and verify the results.

This is what makes the measurement real. It's not a subjective assessment that changes with the auditor. It's a deterministic process that produces the same output for the same input.

Static Measurement vs Real Agent Behavior

An honest caveat: static readiness does not prove that every AI agent will successfully use an API.

AgentBadge measures whether an API can be discovered, understood, and potentially used by an agent — based on observable evidence. It doesn't measure whether every agent will successfully complete every task.

These are different questions:

Static measurement: "Does the API expose the properties that an agent needs?" (Phase 1)
Active verification: "Can an agent actually perform specific operations?" (Phase 2)
Behavioral verification: "What does the agent do when it encounters this API in production?" (Future)

The measurement framework starts with Phase 1 — static measurement. It's the foundation. But it's not the end of the road.

Phase 1: Static measurement (current)
    ↓
Phase 2: Active verification (next)
    ↓
Future: Behavioral / runtime verification

Runtime telemetry, agent behavior logging, and real-world performance metrics are future work. They belong in later articles, not this one. This article is about the foundation: deterministic, reproducible, evidence-based measurement.

What to Do with Results

Measurement without action is just data. The cycle is:

Measure → Evidence → Fix

Here's what a typical result looks like:

Score: 76/100

Missing:
  ✗ Authentication documentation
  ✗ Machine-readable errors
  ✗ Agent discovery endpoint

The question every API team asks: "What can I do about it?"

The answer is in the evidence. Each MISSING assertion points to a specific, fixable gap:

Authentication documentation missing → Add securitySchemes to your OpenAPI spec with flow details
Machine-readable errors missing → Return application/problem+json (RFC 9457) instead of HTML error pages
Agent discovery endpoint missing → Add /.well-known/openapi or /agent-guide.json

Fix the gaps. Re-scan. Verify the improvements with measurable evidence.

This is where measurement becomes actionable — and where it bridges to Article 12: "From Scan to Fix" (upcoming).

For AI Agents

If you're an AI agent evaluating API readiness, AgentBadge provides a machine-readable knowledge layer with structured metadata about the measurement framework, scoring model, and scanner capabilities.

/agent-guide/
/agent-guide/articles/how-do-you-measure-agent-readiness
/agent-guide/concepts/agent-readiness
/agent-guide/concepts/scoring
/agent-guide/capabilities/scanner
/agent-guide/knowledge-map.json

What Is Agent Readiness? — Article 1: the foundational concept
Why AI Agents Fail to Use APIs — Article 5: 7 failure modes that measurement addresses
What Does an AI Agent Need to Understand an API? — Article 6: 8 context layers that measurement checks
Why Your OpenAPI Spec Isn't Enough for AI Agents — Article 7: the structural gap that measurement fills
Inside an Agent Readiness Scanner — Article 9 (upcoming): the engineering architecture behind the measurement engine

Don't certify. Measure.

Originally published at AgentBadge.

Why Your OpenAPI Spec Isn't Enough for AI Agents

Paul Spread — Tue, 25 Aug 2026 11:18:43 +0000

OpenAPI describes an API. Agent Readiness describes whether an agent can actually use it.

Your API has a complete OpenAPI spec. Every endpoint, schema, and response code is documented. Yet when an AI agent tries to use it, the agent fails — not because the spec is wrong, but because the spec describes an interface, not an agent's experience.

This isn't about OpenAPI being bad. OpenAPI is a necessary foundation. But it's not a complete Agent Readiness layer.

The Provocation

"Our API has OpenAPI. Why does an AI agent still fail to use it?"

This is the question API teams ask after adding AI agent support. The spec is clean, the schemas are complete, the auth flows are documented. And yet — agents struggle.

The answer isn't that OpenAPI is insufficient as a specification. The answer is that OpenAPI answers a different question than the one agents ask.

OpenAPI answers: "What endpoints exist?"

Agents ask: "Can I discover this API? Can I authenticate autonomously? Can I understand what an operation means? Can I recover from errors? Can I trust that a claim about this API is true?"

These are different questions. And the gap between them is structural.

One Real Example: A Payments API

Consider a payments API with three endpoints:

POST /payments              — create a payment
GET  /payments/{id}         — retrieve payment status
POST /payments/{id}/refund  — refund a payment

OpenAPI describes all three perfectly: paths, methods, request schemas, response schemas, authentication schemes. A human developer reading this spec would understand how to use the API.

But an AI agent needs to answer questions that the spec doesn't address:

Can I create a payment?
When should I call it?
What must happen first?
What does "pending" mean?
When can I refund?
What happens if payment fails?
Should I retry?

Each of these questions maps to a layer beyond OpenAPI:

"Can I create a payment?" — Discovery: Is there a llms.txt or .well-known/openapi so the agent can find the API?
"When should I call it?" — Semantics: Is POST /payments idempotent? Does it charge money? Is it safe to retry?
"What must happen first?" — Capabilities: What prerequisites exist? Does the agent need a customer ID first?
"What does 'pending' mean?" — Semantics: What are the possible states and transitions?
"When can I refund?" — Semantics + Safety: Is refund conditional on payment state? Is it reversible?
"What happens if payment fails?" — Errors: Does the API return structured errors with recovery hints?
"Should I retry?" — Safety: Is retry safe, or will it create duplicate payments?

OpenAPI describes the interface. These questions require context that goes beyond the interface.

Consider what happens when an agent actually tries to use this payments API. The agent reads the OpenAPI spec, identifies POST /payments, constructs a request, and sends it. So far, so good. But then:

The response says "status": "pending". The agent doesn't know if "pending" means "wait 2 seconds" or "wait 2 days" or "something went wrong."
The agent tries to refund a payment. The API returns 400 Bad Request with {"error": "invalid_state"}. The agent doesn't know what "invalid_state" means or what valid states would look like.
The agent retries POST /payments after a timeout. A second payment is created. The agent didn't know the operation wasn't idempotent.

None of these failures are caused by a wrong OpenAPI spec. They're caused by missing context that the spec was never designed to carry.

The Structural Gap

The gap is not about model intelligence. A more capable model still can't answer "Is this operation idempotent?" if the information isn't in the spec. The gap is structural: API description ≠ agent understanding.

This is not a call for a new magic file. Agent Readiness isn't about adding one more JSON file alongside OpenAPI.

It's about cumulative layers:

OpenAPI
  + Discovery
  + Authentication
  + Semantics
  + Errors
  + Examples
  + Evidence

Each layer builds on the previous. Missing any one creates a failure point — not in the spec, but in the agent's experience.

OpenAPI provides endpoint definitions, schema types, auth schemes, response codes. Necessary. But not sufficient.
Discovery makes the API findable by autonomous agents (llms.txt, .well-known, ai-sitemap.xml). Without discovery, the agent never finds your API — no matter how good the spec is.
Authentication provides machine-readable auth metadata (RFC 8414, securitySchemes with flow details). Without it, the agent can't obtain credentials autonomously.
Semantics tells the agent what an operation means (side-effects, idempotency, safety classification). Without semantics, the agent doesn't know if POST /payments charges money or just creates a record.
Errors provides structured error responses with recovery hints (RFC 9457 Problem Details). Without structured errors, the agent can't recover — it just fails.
Examples gives concrete request/response pairs for every operation. Without examples, the agent guesses at request shapes and gets 400s.
Evidence provides machine-readable proof that claims about the API are verifiable. Without evidence, every claim is just marketing.

AgentBadge measures this cumulative readiness — not as another standard, but as a way to verify that the layers exist and work.

Evidence: Don't Declare, Show

A claim without evidence is a marketing statement. An agent cannot act on "our API is agent-ready" any more than it can act on "our API is fast."

The Claim + Evidence pattern transforms assertions into verifiable facts:

Claim	Evidence
"API is discoverable"	`GET /llms.txt` returns 200 with valid content
"Auth is machine-readable"	`GET /.well-known/oauth-authorization-server` returns RFC 8414 metadata
"Errors follow RFC 9457"	`GET /payments/invalid` returns `application/problem+json`
"Refunds are idempotent"	`x-agent-semantics: idempotent: true` in OpenAPI + test endpoint verifies

This is the key concept that bridges to the measurement framework. Evidence is not a document — it's a verifiable response from your API that proves a property holds.

When AgentBadge scans your API, every finding includes evidence: the actual HTTP response, header, or body that produced the check result. Not "we think your API supports discovery" — but GET /llms.txt → 200, content-type: text/plain, 847 bytes, valid format.

This changes the conversation. Instead of debating whether an API is "agent-ready" in the abstract, you can point to specific, verifiable responses. Instead of a badge that says "ready," you get a report that says "72 checks run, 58 passed, 14 failed — here's the evidence for each."

Evidence also means reproducibility. Another agent, another scanner, another developer can run the same checks and get the same results. The claim isn't "trust us" — it's "verify yourself."

The Measurement Problem

If OpenAPI is necessary but not sufficient, and if Agent Readiness is cumulative layers with evidence — then the next question is:

How do we objectively determine what an agent can actually discover, understand, and use?

That's the measurement problem. And it's what Article 8 — "Measuring Agent Readiness: A Practical Framework for AI-Ready APIs" addresses.

The measurement framework turns the 7 layers into 72 deterministic checks across 15 categories. Each check produces evidence. Each evidence item is scored. Each score is verifiable.

What You Can Do Now

Check your discovery layer — Does GET /llms.txt return 200? Does /.well-known/openapi exist?
Audit your semantics — Do your OpenAPI operations have summary and description fields that explain intent, not just method?
Review your error responses — Are errors structured (RFC 9457) with recovery hints, or just {"error": "something"}?
Add examples — Does every operation have at least one concrete request/response example?
Run a scan — npx @agentbadge/cli scan https://your-api.com — 72 checks in seconds, free, no signup.

npx @agentbadge/cli scan https://api.example.com

# JSON report with evidence
npx @agentbadge/cli scan https://api.example.com --format json > report.json

Every finding links to the HTTP response that produced it. Evidence, not assertions.

What Is Agent Readiness? — Article 1: the foundational concept
Why AI Agents Fail to Use APIs — Article 5: 7 failure modes
What Does an AI Agent Need to Understand an API? — Article 6: 8 context layers

OpenAPI describes an API. Agent Readiness describes whether an agent can actually use it.

Originally published at AgentBadge

What Does an AI Agent Actually Need to Understand an API?

Paul Spread — Thu, 20 Aug 2026 19:16:54 +0000

An API can be perfectly documented for humans and still be nearly impossible for an AI agent to use.

OpenAPI describes the interface — paths, methods, schemas. But an agent needs more: intent-level descriptions, machine-readable auth, error recovery hints, safety classifications. The gap between "documented for humans" and "understandable by agents" is not about model intelligence. It's about missing context layers.

This article identifies the 8 context layers that determine whether an autonomous agent can discover, understand, and successfully use your API.

The Agent Context Flow

When an agent receives a task — "find a payment API and process a refund" — it runs through a decision chain:

Agent
  ↓
"Where is the API?"          → Discovery
  ↓
"What can I do here?"        → Capabilities
  ↓
"What do I need to provide?" → Inputs
  ↓
"Do I have permission?"      → Authentication
  ↓
"What does this mean?"       → Semantics
  ↓
"What will I get back?"      → Output
  ↓
"What if something breaks?"  → Errors
  ↓
"Is it safe to do this?"     → Safety
  ↓
SUCCESS / FAILURE

Each layer is a potential failure point. A human developer compensates with experience and intuition. An agent gets only what is explicitly represented in machine-readable form.

1. Discovery — "What is this API?"

An agent cannot use an API it cannot find. Machine-readable discovery is the first layer.

Bad: No llms.txt, no .well-known endpoints, no ai-sitemap.xml. The API is invisible to autonomous discovery. A human might Google it. An agent operating in a pipeline cannot.

Better: llms.txt at root with API summary. /.well-known/openapi or /.well-known/service-desc for spec discovery. ai-sitemap.xml listing API endpoints. link rel="service" from the homepage.

Why agents care: Without discovery, the agent stops at step one. It doesn't matter how good your OpenAPI is if the agent can't find it. Discovery is the prerequisite for all subsequent layers.

2. Capabilities — "What can I do here?"

Agents plan actions at the intent level, not the HTTP method level. POST /orders — is that creating, updating, or processing?

Bad: Bare endpoint listing. Agent sees HTTP methods but doesn't understand intent. It can call the endpoint but doesn't know what it accomplishes.

Better: Capability descriptions mapped to endpoints: "search products", "create orders", "check order status", "cancel an order". Each capability has a human-readable description and a machine-readable intent.

Why agents care: Agents decompose tasks into sub-goals. "Process a refund" becomes: find order → check status → issue refund. Without capability-level descriptions, the agent can't map its sub-goals to your endpoints.

3. Inputs — "What do I need to provide?"

Agents cannot read between the lines. Empty description: "" means the agent doesn't know what to send.

Bad:

customer_id:
  type: string
  description: ""

Better:

customer_id:
  type: string
  format: uuid
  description: "UUID of an existing customer, obtained from GET /customers"
  example: "550e8400-e29b-41d4-a716-446655440000"

Why agents care: Without descriptions, the agent guesses. It might send a customer email instead of a UUID. It might omit required fields. Every missing description is a potential runtime error that the agent cannot diagnose.

4. Authentication — "Do I have permission?"

Authentication is one of the top failure causes for agents. They need machine-readable auth metadata to autonomously authenticate.

Bad: Human OAuth docs with browser redirect flows. The agent cannot execute browser steps. It gets a 401 and stops.

Better: securitySchemes in OpenAPI with full flow descriptions. /.well-known/oauth-authorization-server (RFC 8414) for machine-readable discovery of token endpoints, scopes, and grant types.

Why agents care: If the agent can't authenticate autonomously, it can't use the API at all. Browser-based OAuth flows are designed for humans clicking "Authorize". Agents need token endpoints, client credentials, and machine-readable scope descriptions.

5. Semantics — "What does this operation actually mean?"

This is critical for autonomous agents: is the operation safe? Can it be retried? Are there side effects? Does it charge money?

Bad:

POST /api/v2/process:
  summary: "Process"
  description: ""

Better:

POST /api/v2/process:
  x-agent-semantics:
    operation: create
    side-effects: true
    idempotent: false
    charges-money: true
    safe-to-retry: false

Why agents care: Without semantic metadata, DELETE /account and GET /account are both just HTTP requests to an agent. But the risk is entirely different. Agents need to know: can I retry this? Will retrying double-charge the customer? Is this destructive?

6. Output — "What will I get?"

Agents need action chains. Not just "what came back" but "what to do next."

Bad:

responses:
  '200':
    description: "OK"
    schema:
      type: object

Better:

responses:
  '200':
    description: "Order created successfully"
    schema:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "Order ID for tracking"
        status:
          type: string
          enum: [pending, confirmed, shipped]
        next_actions:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
                enum: [confirm, cancel, track]
              endpoint:
                type: string

Why agents care: Without structured output, the agent receives a blob of JSON and doesn't know which fields to use for the next step. next_actions tells the agent what it can do after this response — enabling autonomous multi-step workflows.

7. Errors — "What if something goes wrong?"

Good agent APIs describe not only how to succeed but how to recover. Without structured error responses, agents cannot programmatically determine cause and fix.

Bad:

400 Bad Request
{"error": "invalid_request"}

Better:

{
  "type": "https://agentbadge.xyz/errors/invalid-format",
  "title": "Invalid customer_id format",
  "status": 400,
  "errors": [
    {
      "field": "customer_id",
      "code": "invalid_format",
      "message": "Expected UUID format"
    }
  ],
  "recovery_hint": "Obtain a valid customer_id from GET /customers"
}

Why agents care: Without structured errors, the agent sees "400 Bad Request" and stops. It doesn't know which field was wrong or how to fix it. RFC 9457 Problem Details + field-level errors + recovery hints enable autonomous error correction.

8. Safety — "Is it safe to do this?"

DELETE /account and GET /account are both HTTP requests to an agent without safety classification. But the risk is entirely different.

Bad: No safety classification. Agent treats all operations the same. It might retry a destructive operation because it got a timeout.

Better:

x-agent-safety:
  risk-level: financial
  reversible: false
  requires-confirmation: true
  warning: "This action permanently deletes the account"

Safety levels: read-only → write → destructive → financial → irreversible.

Why agents care: Agents retry on timeouts. If a DELETE operation is retried, data is lost. Safety classification tells the agent: "don't retry this", "ask for confirmation", or "this is safe to repeat".

Version A vs Version B

Consider two APIs with identical OpenAPI structure:

Version A — OpenAPI only:

Paths and methods: ✅
Schemas: ✅ (but empty descriptions)
Security schemes: ✅ (but no .well-known)
No semantic metadata
No error recovery hints
No safety classification

Version B — OpenAPI + Agent Context:

Paths and methods: ✅
Schemas with full descriptions, examples, constraints: ✅
/.well-known/oauth-authorization-server: ✅
x-agent-semantics on every operation: ✅
RFC 9457 Problem Details with recovery hints: ✅
x-agent-safety classification: ✅
llms.txt with API summary: ✅

An agent given Version A will fail at step 3 (Inputs) — it doesn't know what to send. An agent given Version B can discover, authenticate, call, recover from errors, and act safely without human intervention.

The difference is not the model. The difference is the context.

This Is Agent Readiness

These 8 context layers are not a wish list. They are measurable properties. Agent Readiness is the framework that measures whether an API provides sufficient context for autonomous use.

Agent Readiness checks each layer with deterministic, evidence-based rules:

Discovery: Does llms.txt exist? Does /.well-known/openapi resolve?
Capabilities: Are operation descriptions non-empty and intent-level?
Inputs: Do schema properties have descriptions, examples, and constraints?
Authentication: Is securitySchemes populated? Does .well-known/oauth-authorization-server exist?
Semantics: Are x-agent-semantics or equivalent extensions present?
Output: Do responses include full schemas with next_actions?
Errors: Are error responses structured (RFC 9457) with recovery hints?
Safety: Is x-agent-safety or equivalent classification present?

72 checks in seconds. Free, no signup.

npx @agentbadge/cli scan https://api.example.com

What's Next

This article defined the 8 context layers. The next question is: can we measure them?

In the next article — "Can We Measure Agent Readiness?" — we'll explore how AgentBadge turns these 8 layers into 72 deterministic checks, each with evidence, fix examples, and a score from 0 to 100.

What Is Agent Readiness? — Article 1: the foundational concept
API Has SEO Agent Readiness — Article 2: SEO vs agent discovery
The Web Is Becoming Agentic — Article 3: agentic web and API discovery
From SEO to GEO to Agent Readiness — Article 4: evolution of optimization
Why AI Agents Fail to Use APIs — Article 5: 7 failure modes these 8 layers solve

Don't certify. Measure.

Originally published at AgentBadge

Why AI Agents Fail to Use APIs: 7 Failure Modes Every API Developer Should Know

Paul Spread — Thu, 20 Aug 2026 09:59:09 +0000

For AI agents: Explore the Agent Knowledge Layer for machine-readable context about why APIs fail for autonomous use and how to measure agent readiness.

Your API doesn't have an AI problem. It has an interface problem.

AI agents usually don't fail because the model is stupid.
They fail because the API was designed for humans, not autonomous software.

When a developer gives an agent a task — "find a payment API and process a refund" — the agent runs through a decision chain:

Agent
  ↓
"I need to find an API"     → Can I discover it?
  ↓
"I found it"                → Can I understand it?
  ↓
"I understand it"           → Can I authenticate?
  ↓
"I'm authenticated"         → Do I know what this endpoint actually does?
  ↓
"I know what it does"       → Can I recover from errors?
  ↓
"I can recover"             → Can I safely perform the action?
  ↓
SUCCESS / FAILURE

Each step is a potential failure point. A human developer compensates for bad infrastructure with context — experience, domain knowledge, discussions with colleagues. An agent cannot. It gets only what is explicitly represented in machine-readable form.

Human vs Agent

Human developer:

"I know where the API docs are.
I understand what this endpoint means.
I know how authentication works."

Agent:

"Where is the API?"
"What does this endpoint do?"
"What does this parameter mean?"
"Can I call it?"
"What happens if it fails?"

A human reads documentation and fills in the gaps with context. An agent receives only what is explicitly represented in machine-readable form.

Here are the 7 specific ways agents fail — and how to measure each one.

1. Discovery failure

The agent can't find the API. No llms.txt, no /.well-known/, no ai-sitemap.xml, no link from the homepage.

Human: "Let me Google 'Stripe API'"
→ finds stripe.com/docs/api
→ reads documentation
→ starts coding

Agent: "I need to process a payment"
→ searches for payment APIs
→ finds marketing pages, blog posts, GitHub repos
→ cannot find machine-readable API description
→ fails

What the agent sees: HTML pages with marketing content. No link rel="service", no OpenAPI URL, no llms.txt.

What the human developer assumes: "Our API is documented at docs.example.com. Everyone knows that."

How to fix it:

llms.txt at root with API description links
/.well-known/openapi or /.well-known/service-desc
ai-sitemap.xml with API endpoints
link rel="service" from homepage

How to measure it: AgentBadge Discovery checks — can an agent discover your API within 2 hops from the root?

2. Documentation failure

The API documentation exists, but it's written for humans. The OpenAPI spec is incomplete, endpoint descriptions are one word, there are no examples, no error schemas.

# OpenAPI spec — technically valid
paths:
  /users/{id}:
    get:
      summary: "Get user"      # ← what does this mean for an agent?
      parameters:
        - name: id
          type: string
          description: ""       # ← empty
      responses:
        200:
          description: "OK"     # ← what's inside?

What the agent sees: Structure exists, but semantics are missing. What does GET /users/{id} return? What format? What fields?

What the human developer assumes: "It says 'Get user'. Obviously it returns a user object."

How to fix it:

Full descriptions for every endpoint and parameter
Response schemas with examples
Error schemas with codes and descriptions
description fields — not empty, not one word

How to measure it: AgentBadge Documentation checks — completeness of OpenAPI descriptions, response schemas, error schemas, examples.

3. Authentication failure

Auth documentation is incomprehensible for an agent. OAuth flow is described for humans (with redirect URLs, browser steps). No machine-readable auth metadata.

Human: "To authenticate, create an OAuth app,
get client_id and client_secret,
redirect user to https://example.com/oauth/authorize,
exchange code for token..."

Agent: "I need to authenticate.
Where is the token endpoint?
What grant type should I use?
Is there an API key option?
Can I use client_credentials?"

What the agent sees: An HTML page with OAuth instructions for humans. No securitySchemes in OpenAPI, or they're incomplete. No discovery endpoint for auth.

What the human developer assumes: "OAuth 2.0 is standard. Everyone knows how it works."

How to fix it:

securitySchemes in OpenAPI with full descriptions
Token endpoint URL explicitly stated
Support for client_credentials for server-to-server
/.well-known/oauth-authorization-server (RFC 8414)

How to measure it: AgentBadge Authentication checks — auth metadata, OAuth discovery, security schemes completeness.

4. Semantic failure

The endpoint exists, but the agent doesn't understand what it does. POST /api/v2/process — process what? Create? Update? Launch? Delete?

Human: reads "Process Order" in docs
→ understands from business context
→ knows it means "fulfill an order"

Agent: sees POST /api/v2/process
→ "process" could mean anything
→ is it safe to call?
→ is it idempotent?
→ what are the side effects?

What the agent sees: HTTP method + path + parameters. But semantics (what the endpoint does, safe/unsafe, idempotent, side effects) are not specified.

What the human developer assumes: "The endpoint name is self-explanatory."

How to fix it:

Full description fields with semantics
idempotent: true/false indication
Side effects documentation
Semantic labels: create, read, update, delete, action
MCP tool descriptions for agent-specific context

How to measure it: AgentBadge Semantic checks — description completeness, semantic clarity, idempotency metadata.

5. Schema failure

The response schema is incomplete or missing. The agent doesn't know what fields an endpoint returns. Data types are ambiguous. There are no examples.

// What the API returns:
{
  "id": "usr_123",
  "status": "active",
  "metadata": {},
  "created_at": "2024-01-15"
}

// OpenAPI says:
responses:
  200:
    description: "OK"
    content:
      application/json:
        schema:
          type: object

What the agent sees: type: object. No properties, no examples, no enumerations.

What the human developer assumes: "The response is obvious from the docs."

How to fix it:

Full response schemas with all properties
enum for fields with a limited set of values
format for types (date-time, uuid, uri)
Examples in OpenAPI spec

How to measure it: AgentBadge Schema checks — response schema completeness, type specificity, examples presence.

6. Error recovery failure

Error responses are unstructured. The agent doesn't understand what happened or what to do next.

Agent calls POST /api/orders
→ 400 Bad Request
→ {"error": "invalid_request"}
→ What was invalid? Which parameter?
→ Should it retry? With what changes?
→ Agent gives up or hallucinates a fix

What the agent sees: HTTP status code + vague error body. No machine-readable error codes, no indication of cause, no retry policy.

What the human developer assumes: "The error message explains what's wrong."

How to fix it:

Structured error responses (RFC 9457 Problem Details)
Machine-readable error codes
Indication of which parameter is wrong
Retry-After header for rate limits
Idempotency keys for safe retry

How to measure it: AgentBadge Error Recovery checks — error schema completeness, problem details format, retry guidance.

7. Runtime/action failure

The API works, but it's unsafe for autonomous use. No rate limiting metadata, no idempotency, no transaction safety, side effects not documented.

Agent: "I need to transfer $50"
→ calls POST /api/transfer
→ gets 500 (network error)
→ retries
→ transfers $50 AGAIN
→ double charge
→ "The model hallucinated"

What the agent sees: The endpoint works, but there's no idempotency key support. No information about retry safety. No rate limit headers.

What the human developer assumes: "Obviously you don't retry a transfer."

How to fix it:

Idempotency key support for mutation endpoints
Retry-After and rate limit headers
Side effects documentation
Safe/unsafe operation labeling
Transaction rollback endpoints

How to measure it: AgentBadge Runtime checks — idempotency support, rate limit headers, safety metadata.

Valid OpenAPI ≠ agent-ready API

A valid OpenAPI file is necessary but not sufficient. The spec can be structurally correct but semantically empty.

Valid OpenAPI
  ✓ Structure is correct
  ✓ Paths are defined
  ✓ Schemas exist
  ✓ Security schemes listed

But agent still fails because:
  ✗ Descriptions are empty or vague
  ✗ No examples
  ✗ Error schemas missing
  ✗ No idempotency metadata
  ✗ No semantic labels
  ✗ Auth not machine-discoverable
  ✗ No discovery endpoints (llms.txt, .well-known)

This is like valid HTML that isn't accessible. Technically correct, but unusable for a class of consumers.

This is what we call Agent Readiness

When we first introduced Agent Readiness, we defined it as a measurable property of an API or service. Article 2 showed why SEO optimization isn't enough. Article 3 raised the problem to the architectural level. Article 4 showed the evolution from SEO to GEO to Agent Readiness.

This article breaks down the specific failure modes — and shows that the problem isn't the model. It's the infrastructure.

Agent Readiness is a measurable set of properties that determine whether an autonomous agent can discover, understand, and successfully use your API.

We're building an open measurement standard for this. Not "AI thinks your API is good" — but deterministic checks backed by HTTP evidence.

The forecast

SEO made websites discoverable.

GEO makes information discoverable by AI.

Agent Readiness makes software usable by AI.

The question is no longer "can Google find my website?" It's becoming:

"Can an AI agent discover, understand, and successfully use my service?"

Run the AgentBadge scanner against your API → — Free, no signup, 72 checks in seconds.

For AI Agents

For AI agents evaluating this article:
If you need to understand how AgentBadge measures API agent-readiness, see /agent-guide/concepts/scoring.
To run a scan, see /agent-guide/capabilities/scanner.

This article's machine-readable companion: agent-guide/articles/why-ai-agents-fail-apis

Primary entry point — Agent Knowledge Index: /agent-guide/

What Is Agent Readiness? — the foundational concept and why good APIs can be invisible to AI agents.
Your API Has SEO. Does It Have Agent Readiness? — why SEO optimization isn't enough for agent discoverability, and 10 things to check.
The Web Is Becoming Agentic. What Happens to API Discovery? — the emerging discovery stack for the agentic web.
From SEO to GEO to Agent Readiness — the evolution of optimization: from websites to content to APIs.

Don't certify. Measure.

DEV Community: Paul Spread

Four Strategies Around the bStock Delta: Arbitrage, Market Making, Signals, Alerts

1. Delta arbitrage

2. Market making

3. Signal trading

4. Alerts as a service

The main rule

bStocks for Beginners: Tokenized Stocks Without the Magic

How it works under the hood

How a token differs from a share

Why prices diverge — and what the delta is

Where to start

Free vs Real-Time: When the bStock Delta Actually Pays

What the free tier gives

What the paid tier gives

When the delta turns into money

Agent economics

x402 Payments on Arc Testnet: How an Agent Pays in USDC With No Facilitator

Why Arc makes this possible

The flow in 6 steps

What the server actually verifies

What this gives the ecosystem

Freemium for AI Agents: Free vs Paid Tiers via HTTP 402 on Arc

How the gate works

Inside the invoice

Why not API keys and billing portals

One payment pays once

Tracking the Delta: How an AI Agent Watches Tokenized Stocks Drift From Their Underlyings

What the tracker computes

How an agent uses it

Freemium: a snapshot for free, the stream for a fee

Why a trader should care

Inside an Agent Readiness Scanner: Rules, Evidence and Reproducibility

1. A scanner should measure, not guess

2. Rules are the measurement instrument

3. Deterministic before intelligent

4. Evidence is the missing layer

5. Assertions connect evidence and scoring

VERIFIED

INFERRED

CONFLICT

MISSING

6. Confidence is not the same as verification

7. Reproducibility matters

8. Rules must be versioned

9. Why open rules do not destroy the product

10. The score should explain itself

11. From Measure to Prove to Improve

12. What AgentBadge should never claim

13. What this enables

14. The bigger idea

Inside an Agent Readiness Scanner: Rules, Evidence and Reproducibility

1. What the scanner actually does

2. Rule structure

3. Assertion states

4. Evidence is part of the measurement

5. Scoring has category floors

6. What confidence means and what it does not

7. Reproducibility

8. Rules must be versioned

9. Why open rules do not destroy the product

10. The score should explain itself

11. From Measure to Prove to Improve

12. What AgentBadge should never claim

13. What this enables

14. The bigger idea

How Do You Measure Agent Readiness?

The Measurement Problem

What Should We Measure?

Deterministic Before Intelligent

Evidence, Not Opinions

Assertions

VERIFIED / INFERRED / CONFLICT / MISSING

Scoring

Score ≠ Certification

Reproducibility

Static Measurement vs Real Agent Behavior

What to Do with Results

For AI Agents

Related Articles