Egor

Posted on Jul 13 • Originally published at agentfix.pro

llms-pay.md: a discovery layer for AI shopping agents

#opensource #webdev #showdev #ai

TL;DR. AI shopping agents can read your marketing page just fine. What they cannot do is buy. There is no standard way for an agent to discover your products, pick a plan, and hit the right checkout endpoint. We shipped a two-file discovery layer, live at agentfix.pro/llms-pay.md and agentfix.pro/.well-known/agent-checkout.json. Draft spec v0.1, open for critique.

The problem: agents can read, agents cannot buy
Why llms.txt was the right template
The spec in 90 seconds: llms-pay.md + agent-checkout.json
Discovery flow, step by step
Why two files, not one
What is deliberately out of scope for v0.1
See it live and what we want feedback on
Key takeaways

1. The problem: agents can read, agents cannot buy

Put an autonomous agent in front of your pricing page. It parses the copy. It renders the marketing DOM. It probably understands your tiers. Then it stops.

Because it does not know:

Which endpoint to POST to
What body shape you expect
Whether there is a pre-check step (a scan, a quote, an eligibility call)
How to test the flow without a real card
What terminal status means "the pack is ready, go download"

Human buyers solve this with visual clicks. Agents cannot click their way through a Stripe modal without the seller building a first-class programmatic checkout. And most sellers have not.

Result: your site is agent-readable but not agent-buyable. That gap is a real revenue leak once shopping agents ship at scale, which is happening this year.

2. Why llms.txt was the right template

You have probably seen llms.txt. It is a small Markdown file at the root of a site that tells language models what matters, in one canonical place. Cheap to write, cheap to parse, no server changes, immediate value for retrieval.

The pattern is worth copying:

Human-readable Markdown at a predictable path
Discoverable without a crawl
Companion machine-readable JSON for the parts that need strict types

llms-pay.md follows the same shape, aimed at commerce instead of retrieval. It is not competing with llms.txt. It sits next to it.

3. The spec in 90 seconds

Two files. Same site.

File one: /llms-pay.md - human-friendly Markdown that explains what you sell, how to purchase programmatically, how to test, which providers you support, and how to reach a human. An agent reads this to build a mental model.

File two: /.well-known/agent-checkout.json - strict JSON with the exact endpoint shapes, body schemas, prereq steps, terminal statuses, and provider metadata. An agent reads this to execute.

Every field in the JSON has one job: remove ambiguity. checkout_flow.method is "POST". body_schema names the fields. fulfillment.poll_endpoint says where to poll. fulfillment.terminal_status says what to wait for. test_mode.supported: true says you can smoke-test the whole flow without a card.

Here is a trimmed slice of the live schema so you can see the shape:

{
  "$schema": "https://agentfix.pro/schemas/agent-checkout-v0.json",
  "version": "0.1",
  "products": [
    {
      "id": "agent_ready_pack_basic",
      "price": { "amount": 29, "currency": "USD", "recurrence": "one_time" },
      "checkout_flow": {
        "method": "POST",
        "endpoint": "https://agentfix.pro/api/checkout",
        "prereq": {
          "step": "scan",
          "endpoint": "https://agentfix.pro/api/scan",
          "returns": "scan_id"
        },
        "body_schema": { "scan_id": "string", "email": "string" }
      },
      "fulfillment": {
        "poll_endpoint": "https://agentfix.pro/api/orders/by-scan",
        "terminal_status": "delivered"
      }
    }
  ]
}

Full file: agent-checkout.json. Draft schema: agent-checkout-v0.json.

4. Discovery flow, step by step

From cold visit to delivered artifact:

Agent lands on example.com. Fetches /llms-pay.md. Reads the human summary.
Fetches /.well-known/agent-checkout.json. Picks the product by id or name.
Runs the prereq step (in our case, POST /api/scan with the target URL).
Polls the scan until it is done, extracts scan_id.
POST /api/checkout with scan_id and buyer email. Receives checkout_url.
Directs the buyer to checkout_url. Provider handles card auth, 3DS, receipt.
Polls fulfillment.poll_endpoint until terminal_status: "delivered".
Downloads the artifact from the signed URL in the response.

The whole flow is idempotent on the client side. Every step is a standard REST call with a documented body.

5. Why two files, not one

Because they answer different questions.

The Markdown answers "what and why". It handles nuance: refund policy, sandbox instructions, which providers are primary vs fallback, what is not supported yet. Humans read it too, so it is written in prose.
The JSON answers "how". It has to be machine-strict. No prose. No maybe. Every URL is a full URL, every schema is named.

You could stuff both into one YAML with a human_notes field, but then agents have to parse prose for edge cases and humans have to read schemas for policy. Splitting them keeps each file good at its job.

6. What is deliberately out of scope for v0.1

Being an open draft, we cut ruthlessly:

No crypto rails. No x402, no L402, no on-chain settlement. Cards only. If enough teams need x402, v0.2 adds it.
No auth beyond email. No OAuth handshake for the buyer. The provider handles PCI. We hand the agent a checkout_url and step aside.
No bulk cart. One product, one checkout. Bulk purchase agents are not the 2026 shape.
No delivery negotiation. Terminal status is boolean-ish: delivered or pending. No fractional progress states.

The point of v0.1 is "does the shape work end to end for a real product". Anything that is not necessary to test the discovery pattern is deferred.

7. See it live and what we want feedback on

Live: agentfix.pro/llms-pay.md and /.well-known/agent-checkout.json.

Please break it. Specifically:

Are field names ergonomic? prereq vs precondition vs pre_step - which reads best to an agent?
Is terminal_status a good name for "when to stop polling"?
Should the schema live at /.well-known/agent-checkout.json or at a versioned path like /.well-known/agent-checkout-v0.json?
Do you want a provider.priority field so agents can pick a preferred rail (e.g. "prefer FastSpring for EU VAT")?
What is missing for your product's flow?

Open an issue, DM me, or comment on the canonical post. Draft status is "v0.1-community-comment", which is the polite way of saying "everything is negotiable".

8. Key takeaways

AI shopping agents will read your site. They cannot buy from it without a spec.
A tiny two-file discovery layer (llms-pay.md + agent-checkout.json) is enough to close the gap for card-based checkout.
Draft v0.1 is live at agentfix.pro. Copy the pattern, adapt the shape, tell us what breaks.
If we get to shared field names across a handful of sellers, agents start to converge. That is how llms.txt worked and how this can too.

Try the scanner. If you want to see how agent-ready your own site is (before we get to checkout), scan it free at agentfix.pro. No signup, no email required. The full 34-signal checklist is documented at /methodology.

DEV Community