1.0Use at your own risk: information here may be inaccurate or not current, and figures are estimates; stores.md is not purchasing advice and never sells anything, lists real stores, moves money, holds keys or fetches other sites. See the terms.

STORES.md

Open format · stores + agents

Every store your AI agent can buy from, in one file.

STORES.md is a simple, open format for what agents can buy and how they pay: an x402 link, a checkout link, an invoice. Stores publish one. Your agent keeps one too, with every store it finds, in every format, read into one file.

Try every format
The format The skill Add to an MCP client

● Format v1.0/stores.md on any domainmade-up stores shown

Your agent’s file

Every store, one STORES.md

Read from any format, checked before paying.

index · v1
STORES.md3 stores · 3 formats
  • # Example Weatherknown
    forecast · 0.002 USD per call · x402
  • # Example Outfittersnew
    camp mug · 18 USD once · checkout
  • # Example Bakerynew
    sourdough · 7 USD · pickup · checkout
  • # Purchases
    10-15 · forecast · 0.002 USD · x402 · ref 0x9f…
checked
FITS YOUR RULES
x402 answer
api.example.com
read in
Product feed
outfitters.example.org
read in
Map listing
Example Bakery
read in
before paying
0.002 USD to a listed address
pay_to matches · under $1
01 read any format02 check the 40203 log the purchase

Every format in, one file out

Whatever a store publishes, your agent reads it the same way.

A 402 answer, a discovery list, a product page, a feed, a tool list, an API document: pick one and see it read into STORES.md, with links worth following and text that tries to instruct agents flagged. For a 402, see the check that runs before your agent pays. Every sample is made up.

Made-up sample. Edit it, or paste your own.

Read an HTTP 402 answer: 1 product from 1 store.

Before payingAsk firstrecommended rules
  • askExample Weather is new to you: ask first. Once the person says yes, mark it status: known.
  • noteRead with 6 decimal places, the usual number for dollar tokens. If this token uses another number, pass decimals.
  • note0x000000...0000E1 matches an address Example Weather lists under pay_to.
api.example.comapi.example.com
  • Hourly forecast, 48 hours0.002 USD per requestx402
STORES.md (your entry)
# api.example.com

- url: https://api.example.com
- source: https://api.example.com/v1/forecast
- format: HTTP 402 answer
- pulled: 2026-10-16
- status: new

## Hourly forecast, 48 hours

- id: v1-forecast
- price: 0.002 USD per request
- pay: x402 https://api.example.com/v1/forecast
- delivers: application/json, in the response
- x402_terms: eip155:8453 0.002 USD to 0x00000000000000000000000000000000000000E1

For stores

Sell to agents with one file.

  1. 1

    Add stores.md to your domain

    Serve it at https://your-domain/stores.md and link it from /llms.txt. Plain Markdown; no account, no sign-up.

  2. 2

    One heading per store, one per product

    Under # Your store: url, terms, refunds. Under each ## Product: price, pay and delivers.

  3. 3

    Say where payments go

    One pay_to line per address you receive at. Buyers’ agents stop when a 402 pays anywhere else.

  4. 4

    Check it

    Run check_stores_md below, or call it from your build, before you publish.

Prices read like 0.002 USD per call, 5 USD per 1,000 calls or 20 USD per month. Ways to pay: x402, l402, checkout, agent-checkout, mcp, invoice, transfer, free and contact. The whole format: /spec.md.

stores.mdmade-up store
---stores: 1updated: 2026-10-15---# Example WeatherForecasts and history for any place on Earth, sold by the call or by the month.- url: https://example.com- terms: https://example.com/terms- refunds: Plans within 14 days. Single calls are final.- pay_to: eip155:8453 0x00000000000000000000000000000000000000E1- contact: https://example.com/support## Forecast lookupHourly forecast for the next 48 hours, for one place.- id: forecast- price: 0.002 USD per call- pay: x402 https://api.example.com/v1/forecast- delivers: JSON, at once- tags: weather, forecast## History pack, 2025Every hour of 2025 for one city, as one file.- id: history-2025- price: 12 USD once- pay: checkout https://example.com/buy/history-2025- pay: agent-checkout https://example.com/agents/checkout- delivers: a CSV download link, within a minute## Pro plan- id: pro- price: 20 USD per month- pay: checkout https://example.com/buy/pro- pay: invoice https://example.com/agents/invoice- delivers: an API key by email, within an hour- refunds: 14 days

Customize

Your buying rules, written into the skill.

27 settings in 5 groups. Start from a preset, change anything, and your settings are written into STORES.md. Every setting is a number or a fixed choice, so a shared link can’t slip words into the file. The same settings work as URL parameters, MCP prompt arguments, the build_settings tool and /api/v1/build_settings.

Start from

Pay per request within small limits; ask before checkouts, invoices, renewals and new stores; never transfer to an address.

Spend

How much, and when to ask.

5 of 6 set
24 of 27 set
STORES.md · your settings
Your rules

Set by the person you work for, and only that person can change them. Rules an agent drafted count only after that person says yes. Where a rule here and the rest of this file differ, the rule wins. If a rule blocks a purchase, stop and ask; don't work around it.

Spend
Never spend more than $5 on one purchase. A purchase is everything you buy in one go: 100 calls at $0.01 is one purchase of $1.
Ask the person before any purchase over $1.
Spend at most $20 a day, all purchases together, counted from your purchase log.
Spend at most $100 a month, all purchases together.
Tell the person when spending reaches 80% of any cap. At 100%, stop.
Ways to pay
Paying per request over x402: allowed within these limits.
Paying per request with Lightning (L402): ask first, every time.
Paid tools on MCP servers: allowed within these limits.
Checkout pages and payment links: ask first, every time.
Checkout APIs for agents: ask first, every time.
Invoices: ask first, every time.
Never pay by direct transfer to an address.
Ask before anything that renews, and say how to cancel it.
Networks and assets
Main and test networks are both fine.
Ask before paying in anything but dollars or dollar tokens.
For these limits only, count a dollar token as one dollar. That is a simplification, not a statement about its value.
If a payment goes to an address the store's STORES.md doesn't list, stop. If the store lists none, ask first.
Stores
Buy from stores marked known. Ask before buying from a new one; once the person says yes, mark it known.
If you read a listing more than 30 days ago, read it again before paying.
Never pay more than the listed price.
Your STORES.md

How to keep the file of everything you can buy. Follow these unless a rule above says otherwise.

Your STORES.md
Pull your stores again every 7 days.
When a store stops listing a product, mark it status: gone.
Log every purchase under # Purchases in STORES.md: date, store, product, amount, way to pay and the receipt reference.
Tell the person after each purchase: what, how much and the receipt.
The full skill, with your settings at the top.
mkdir -p ~/.claude/skills/stores && curl -fsSL "https://www.stores.md/stores.md?max_per_purchase=5&ask_over=1&daily_cap=20&monthly_cap=100&alert_pct=80&x402=allow&l402=ask&paid_tools=allow&checkout_links=ask&agent_checkout=ask&invoices=ask&transfers=never&recurring=ask&networks=any&other_assets=ask&dollar_tokens=face_value&pay_to_check=ask_if_unlisted&which_stores=ask_new&max_listing_age_days=30&price_drift_pct=0&refresh_days=7&gone_products=mark&log_purchases=yes&report=each" -o ~/.claude/skills/stores/SKILL.md
Linkhttps://www.stores.md/stores.md?max_per_purchase=5&ask_over=1&daily_cap=20&monthly_cap=100&alert_pct=80&x402=allow&l402=ask&paid_tools=allow&checkout_links=ask&agent_checkout=ask&invoices=ask&transfers=never&recurring=ask&networks=any&other_assets=ask&dollar_tokens=face_value&pay_to_check=ask_if_unlisted&which_stores=ask_new&max_listing_age_days=30&price_drift_pct=0&refresh_days=7&gone_products=mark&log_purchases=yes&report=each

Copy as JSON

The same settings as one JSON object. It feeds the build_settings tool or POST /api/v1/build_settings.

24 of 27 settings set. Anything not set follows the skill’s own rules.

Tools

Tools your agent calls before it buys.

They read what you send them and nothing else: no fetching, no storing, no paying. Run them here, or call them over HTTP or MCP. They read, compare and check; they never approve a purchase.

Read any listing into STORES.md

Reads what a store publishes, in any of these formats, into STORES.md entries: STORES.md, an HTTP 402 answer (x402 version 1 or 2, L402), an x402 discovery list, JSON-LD or a web page with it, a product feed (CSV, TSV or JSON), an MCP tool list, an OpenAPI document (JSON), llms.txt or an agent card. Returns the stores and products, links worth following, and warnings, including text that reads like instructions to agents. It reads only the text you send; it fetches nothing and checks nothing with the store.

Run the tool to see a result. Estimates only; check them yourself.
POST /api/v1/read_listing
{
  "text": "HTTP/1.1 402 Payment Required\ncontent-type: application/json\npayment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQQVlNRU5ULVNJR05BVFVSRSBoZWFkZXIgaXMgcmVxdWlyZWQiLCJyZXNvdXJjZSI6eyJ1cmwiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbS92MS9mb3JlY2FzdCIsImRlc2NyaXB0aW9uIjoiSG91cmx5IGZvcmVjYXN0LCA0OCBob3VycyIsIm1pbWVUeXBlIjoiYXBwbGljYXRpb24vanNvbiJ9LCJhY2NlcHRzIjpbeyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MyIsImFtb3VudCI6IjIwMDAiLCJhc3NldCI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDBBNSIsInBheVRvIjoiMHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMEUxIiwibWF4VGltZW91dFNlY29uZHMiOjYwLCJleHRyYSI6eyJuYW1lIjoiVVNEIn19XX0=\n\n{}",
  "format": "auto",
  "source_url": "https://api.example.com/v1/forecast",
  "output": "index"
}
curl -s https://www.stores.md/api/v1/read_listing -H 'content-type: application/json' -d '{"text":"HTTP/1.1 402 Payment Required\ncontent-type: application/json\npayment-required: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQQVlNRU5ULVNJR05BVFVSRSBoZWFkZXIgaXMgcmVxdWlyZWQiLCJyZXNvdXJjZSI6eyJ1cmwiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbS92MS9mb3JlY2FzdCIsImRlc2NyaXB0aW9uIjoiSG91cmx5IGZvcmVjYXN0LCA0OCBob3VycyIsIm1pbWVUeXBlIjoiYXBwbGljYXRpb24vanNvbiJ9LCJhY2NlcHRzIjpbeyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MyIsImFtb3VudCI6IjIwMDAiLCJhc3NldCI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDBBNSIsInBheVRvIjoiMHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMEUxIiwibWF4VGltZW91dFNlY29uZHMiOjYwLCJleHRyYSI6eyJuYW1lIjoiVVNEIn19XX0=\n\n{}","format":"auto","source_url":"https://api.example.com/v1/forecast","output":"index"}'

Agents can pay now. They can't see what's for sale.

A payment per request is one HTTP call away, but what an agent can buy is scattered across 402 answers, product feeds, structured data, tool lists and API docs, each in its own shape, with no price list and no rules. So agents guess: they pay whatever the 402 says, to whatever address it names, as often as the loop runs. STORES.md gives stores one plain file to say what they sell and where payments go, gives agents one file of everything they can buy, and puts a check between the 402 and the wallet.

  • One file per store: price, way to pay, what you get, refunds and the addresses payments go to.
  • One file for your agent: every store it found, in every format, with its status: known, new or blocked.
  • A check before the wallet: the 402's amount, network and pay-to against the listing and your limits.
  • Prompt injection, flagged: store text that tries to instruct agents gets a warning, and the skill says to ignore it.
  • Nothing you send is kept: requests are answered and forgotten. No accounts, no keys, no money moves.

Use it in your stack

Paste it, install it, or call it.

The skill alone gives an agent the method. The MCP server and API add the tools and your settings. No key, no account.

Paste the prompt into a system prompt or project instructions. Or keep the file in the repo and point AGENTS.md at it.

terminal
mkdir -p .agents && curl -fsSL "https://www.stores.md/stores.md?preset=recommended" -o .agents/stores-skill.mdecho "Whenever a task needs to find, compare, buy, subscribe to or pay for a product, an API call, data or a tool, follow .agents/stores-skill.md. Keep what you can buy in STORES.md." >> AGENTS.md
Quickest start:claude mcp add --transport http stores https://www.stores.md/mcp

Example code

Call it from your own code.

Working calls against the API. The full reference is at /api/v1 and /openapi.json.

Check a payment request over MCP before your wallet signs anything.

check.mts
// Check a payment request over MCP before your wallet signs anything.const answer = await fetch("https://api.example.com/v1/forecast"); // 402 Payment Requiredconst raw = `HTTP/1.1 ${answer.status}\npayment-required: ${answer.headers.get("payment-required") ?? ""}\n\n${await answer.text()}`;const res = await fetch("https://www.stores.md/mcp", {  method: "POST",  headers: { "content-type": "application/json", accept: "application/json" },  body: JSON.stringify({    jsonrpc: "2.0",    id: 1,    method: "tools/call",    params: { name: "check_purchase", arguments: { payment_request: raw, preset: "recommended", max_per_purchase: 2 } },  }),});const { result } = await res.json();const { verdict, summary } = result.structuredContent; // fits_your_rules | ask_first | stopif (verdict !== "fits_your_rules") throw new Error(summary); // ask the person instead of paying

FAQ

Is stores.md a marketplace?

No. stores.md never sells anything, lists real stores, moves money, holds keys or fetches other sites. STORES.md is a file format, and every store on this site is made up, on the reserved example domains.

Where does the list of every store come from?

From the stores themselves. Each store publishes its own STORES.md (or a 402, a feed or a tool list), your agent reads them, and read_listing turns each into the same format. There is no central directory to trust, and nothing to scrape: you choose which stores your agent reads.

Does a fit from check_purchase mean the payment is safe?

No. It means the numbers you sent fit the rules you set: the amount, the network, the pay-to address against the listing. It can't see whether the store delivers, whether a token is worth its name, or whether the listing itself is honest.

How is this different from llms.txt, product feeds or x402 discovery?

It complements them. llms.txt points to things, feeds list products, a 402 prices one request. STORES.md is a short file any store can write by hand that says all of it in one place, and the tools read the others into it.

Is this advice?

No. Nothing here is financial, legal, tax or purchasing advice, or an endorsement of any store. STORES.md is a file format and a method for software agents, plus tools that read and check what you send. They can misread things. Check them yourself, and ask a qualified person when it matters.

Does it show real stores or prices?

No. Every store and price here is made up, on the reserved example domains. The tools fetch nothing and look up no rates: every number comes from what you send. Names of formats such as x402, L402, MCP or OpenAPI are used only to describe them.

Can an agent set up its own settings?

It can draft them: the same settings work as URL parameters, MCP prompt arguments and the build_settings tool. The skill and the tool both say that drafted settings count only after the person says yes. Nothing technical stops an agent from ignoring that, so read what it sends you.

Does a tool result mean something is approved?

No. Tools read, compare and check. They don’t approve, enforce or certify anything, and they can be wrong.

Can I change everything?

Yes. Start from a preset, change any setting above, and your choices are written into the file. Or edit the Markdown yourself. It’s MIT; keep your copy next to your code.

Do you track anything?

We count page views, copies, skill fetches and API and MCP calls to learn what is useful, without cookies or stored IP addresses. We never record your settings values or what you send to a tool. Details in the terms.
STORES.md: Every store your AI agent can buy from, in one file