# STORES.md

> An open format for what agents can buy and how they pay, plus the tools to read every listing format into it. Version 1.0. MIT.

STORES.md is a plain Markdown file that says what a store sells to agents, what it costs and how to pay: an x402 link, a checkout link, an invoice. Agents read listings in any format into one STORES.md of their own, compare offers, and check every payment request against the person's rules before paying. 27 settings in 5 groups, numbers or fixed choices only. Presets: core, recommended, test_money, strict. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.

Use at your own risk. stores.md is provided as is, without warranty. Information here may be inaccurate, incomplete or not current, and is not verified; figures are estimates from the numbers you send and the formulas stated. Nothing here is financial, legal, tax or purchasing advice, or an endorsement of any store. stores.md never sells anything, lists real stores, moves money, holds keys or fetches other sites. Check everything yourself before you act on it.

## Format

- [STORES.md format, version 1](https://www.stores.md/spec.md): what a store publishes at https://<its domain>/stores.md, and what a buyer's agent keeps

## Skill

- [STORES.md](https://www.stores.md/stores.md): load into your agent's instructions or save as ~/.claude/skills/stores/SKILL.md (sha256 6dd56b3420bc49edef1d8abea429c2f1b92cf8a9f9741d9703732d4cc61e2d34)
- [STORES.md with settings](https://www.stores.md/stores.md?preset=recommended): a preset plus any settings; each setting overrides the preset

## API (no key, CORS open, nothing stored)

- [read_listing](https://www.stores.md/api/v1/read_listing?text=HTTP%2F1.1+402+Payment+Required%0Acontent-type%3A+application%2Fjson%0Apayment-required%3A+eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQQVlNRU5ULVNJR05BVFVSRSBoZWFkZXIgaXMgcmVxdWlyZWQiLCJyZXNvdXJjZSI6eyJ1cmwiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbS92MS9mb3JlY2FzdCIsImRlc2NyaXB0aW9uIjoiSG91cmx5IGZvcmVjYXN0LCA0OCBob3VycyIsIm1pbWVUeXBlIjoiYXBwbGljYXRpb24vanNvbiJ9LCJhY2NlcHRzIjpbeyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MyIsImFtb3VudCI6IjIwMDAiLCJhc3NldCI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDBBNSIsInBheVRvIjoiMHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMEUxIiwibWF4VGltZW91dFNlY29uZHMiOjYwLCJleHRyYSI6eyJuYW1lIjoiVVNEIn19XX0%3D%0A%0A%7B%7D&source_url=https%3A%2F%2Fapi.example.com%2Fv1%2Fforecast): 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.
- [check_purchase](https://www.stores.md/api/v1/check_purchase?payment_request=HTTP%2F1.1+402+Payment+Required%0Acontent-type%3A+application%2Fjson%0Apayment-required%3A+eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQQVlNRU5ULVNJR05BVFVSRSBoZWFkZXIgaXMgcmVxdWlyZWQiLCJyZXNvdXJjZSI6eyJ1cmwiOiJodHRwczovL2FwaS5leGFtcGxlLmNvbS92MS9mb3JlY2FzdCIsImRlc2NyaXB0aW9uIjoiSG91cmx5IGZvcmVjYXN0LCA0OCBob3VycyIsIm1pbWVUeXBlIjoiYXBwbGljYXRpb24vanNvbiJ9LCJhY2NlcHRzIjpbeyJzY2hlbWUiOiJleGFjdCIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MyIsImFtb3VudCI6IjIwMDAiLCJhc3NldCI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDBBNSIsInBheVRvIjoiMHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMEUxIiwibWF4VGltZW91dFNlY29uZHMiOjYwLCJleHRyYSI6eyJuYW1lIjoiVVNEIn19XX0%3D%0A%0A%7B%7D&stores_md=---%0Astores%3A+1%0Aupdated%3A+2026-10-15%0A---%0A%0A%23+Example+Weather%0A%0AForecasts+and+history+for+any+place+on+Earth%2C+sold+by+the+call+or+by+the+month.%0A%0A-+url%3A+https%3A%2F%2Fexample.com%0A-+terms%3A+https%3A%2F%2Fexample.com%2Fterms%0A-+refunds%3A+Plans+within+14+days.+Single+calls+are+final.%0A-+pay_to%3A+eip155%3A8453+0x00000000000000000000000000000000000000E1%0A-+contact%3A+https%3A%2F%2Fexample.com%2Fsupport%0A%0A%23%23+Forecast+lookup%0A%0AHourly+forecast+for+the+next+48+hours%2C+for+one+place.%0A%0A-+id%3A+forecast%0A-+price%3A+0.002+USD+per+call%0A-+pay%3A+x402+https%3A%2F%2Fapi.example.com%2Fv1%2Fforecast%0A-+delivers%3A+JSON%2C+at+once%0A-+tags%3A+weather%2C+forecast%0A%0A%23%23+History+pack%2C+2025%0A%0AEvery+hour+of+2025+for+one+city%2C+as+one+file.%0A%0A-+id%3A+history-2025%0A-+price%3A+12+USD+once%0A-+pay%3A+checkout+https%3A%2F%2Fexample.com%2Fbuy%2Fhistory-2025%0A-+pay%3A+agent-checkout+https%3A%2F%2Fexample.com%2Fagents%2Fcheckout%0A-+delivers%3A+a+CSV+download+link%2C+within+a+minute%0A%0A%23%23+Pro+plan%0A%0A-+id%3A+pro%0A-+price%3A+20+USD+per+month%0A-+pay%3A+checkout+https%3A%2F%2Fexample.com%2Fbuy%2Fpro%0A-+pay%3A+invoice+https%3A%2F%2Fexample.com%2Fagents%2Finvoice%0A-+delivers%3A+an+API+key+by+email%2C+within+an+hour%0A-+refunds%3A+14+days%0A&preset=recommended): Check a purchase before paying. The last check before money moves. Send the payment request (the whole HTTP 402 answer: x402 version 1 or 2, L402, or a price header) and, ideally, the store's STORES.md or your own entry for it. It reads the amount, asset, network and pay-to address, matches them to the listing, and checks them against your rules: the same settings as the skill (or a preset). Returns fits_your_rules, ask_first or stop, with every reason, the total, and a line for your purchase log. Without a 402, it checks a listed product and a way to pay. It never pays, and a fit is a check of what you sent, not an approval.
- [compare_offers](https://www.stores.md/api/v1/compare_offers): Compare offers for the same need. Puts offers on one footing: what each costs for the amount you'll actually use. Handles prices per unit, per block of units (5 USD per 1,000 calls), renewing plans over a number of months, one-off prices, setup fees and minimum spends. Ranks offers in one currency; it has no exchange rates, so offers in another currency are listed but not ranked. Arithmetic on the prices you send.
- [check_stores_md](https://www.stores.md/api/v1/check_stores_md?text=---%0Astores%3A+1%0Aupdated%3A+2026-10-15%0A---%0A%0A%23+Example+Weather%0A%0AForecasts+and+history+for+any+place+on+Earth%2C+sold+by+the+call+or+by+the+month.%0A%0A-+url%3A+https%3A%2F%2Fexample.com%0A-+terms%3A+https%3A%2F%2Fexample.com%2Fterms%0A-+refunds%3A+Plans+within+14+days.+Single+calls+are+final.%0A-+pay_to%3A+eip155%3A8453+0x00000000000000000000000000000000000000E1%0A-+contact%3A+https%3A%2F%2Fexample.com%2Fsupport%0A%0A%23%23+Forecast+lookup%0A%0AHourly+forecast+for+the+next+48+hours%2C+for+one+place.%0A%0A-+id%3A+forecast%0A-+price%3A+0.002+USD+per+call%0A-+pay%3A+x402+https%3A%2F%2Fapi.example.com%2Fv1%2Fforecast%0A-+delivers%3A+JSON%2C+at+once%0A-+tags%3A+weather%2C+forecast%0A%0A%23%23+History+pack%2C+2025%0A%0AEvery+hour+of+2025+for+one+city%2C+as+one+file.%0A%0A-+id%3A+history-2025%0A-+price%3A+12+USD+once%0A-+pay%3A+checkout+https%3A%2F%2Fexample.com%2Fbuy%2Fhistory-2025%0A-+pay%3A+agent-checkout+https%3A%2F%2Fexample.com%2Fagents%2Fcheckout%0A-+delivers%3A+a+CSV+download+link%2C+within+a+minute%0A%0A%23%23+Pro+plan%0A%0A-+id%3A+pro%0A-+price%3A+20+USD+per+month%0A-+pay%3A+checkout+https%3A%2F%2Fexample.com%2Fbuy%2Fpro%0A-+pay%3A+invoice+https%3A%2F%2Fexample.com%2Fagents%2Finvoice%0A-+delivers%3A+an+API+key+by+email%2C+within+an+hour%0A-+refunds%3A+14+days%0A): Check a STORES.md file. Checks a STORES.md file against the format: every store has an https url, every product a price and a way to pay, pay lines name a known way to pay with an https link, and prices are readable. Warns about missing delivery and refund lines, missing pay_to addresses for x402, stale dates, and text that reads like instructions to agents. Returns errors and warnings with line numbers and the file rewritten in the canonical form. A clean result checks the format only; it says nothing about the store.
- [build_settings](https://www.stores.md/api/v1/build_settings?preset=recommended): Write your settings into the skill. Turns a preset and settings into the sections written at the top of STORES.md. Every setting is a number or a fixed choice; the catalog is at https://www.stores.md/api/v1/settings. Returns the sections as Markdown, the settings as JSON, a link to the skill with them written in and a one-line install. Out-of-range numbers are clamped with a note. Nothing is stored. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.
- [Settings catalog](https://www.stores.md/api/v1/settings): every setting with its unit, range, options and default, plus the presets
- [API index](https://www.stores.md/api/v1) and [OpenAPI](https://www.stores.md/openapi.json)

## MCP

- https://www.stores.md/mcp: Streamable HTTP, stateless, no auth. Tools: read_listing, check_purchase, compare_offers, check_stores_md, build_settings. Prompt: stores, with an optional preset and any setting. Resources: the skill and the settings catalog.

## Terms

- [Terms of use and disclaimer](https://www.stores.md/terms)

## Optional

- [Full text](https://www.stores.md/llms-full.txt): the skill plus the tool and settings reference
- [Manifest](https://www.stores.md/.well-known/stores.json)