Map

MAP — Maraventano Agent Protocol

Navigate agent commerce. Find any merchant. Pay any merchant. Be found.

MAP lets any agent read products across the open web in one shape, decide whether it can pay autonomously, and publish its own catalog.

Provisions · Merchant Key · Atlas — three minimal parts under one MCP server.

MAP is one MCP server with three parts. Each does one thing and shuts up; together they remove the gatekeeper between an agent and the open commercial web.

Teacher, not butler — every part. MAP reads, explains, persists, and serves. It never signs, pays, holds keys, transacts, or stores cards.

It publishes to npm as @maraventano/map. The standalone firstdollar package stays MIT and separate; the copy of its curriculum bundled here (Provisions) is relicensed dual — see LICENSE.

Merchant Key — find any merchant (read)

It reads any URL on the open web — not just a walled garden. That's the difference from Perplexity / Google Shopping / Amazon, who only see merchants inside their own programs. MAP never assumes the merchant is registered anywhere.

decode-merchant

Input a product url. Returns ONE shape (CleanRead):

{
  "schemaVersion": "map/v1",
  "sourceUrl": "https://…",
  "what":   "Void Latte — Meditation on emptiness and meaning…",  // name + identity, one string
  "who":    "underground.substratesymposium.com",                 // seller
  "price":  { "total": 1.99, "currency": "USDC" },                // total if knowable, else null
  "available": "in_stock",                                        // in_stock | out_of_stock | unknown
  "payable": {                                                    // can an agent pay this itself?
    "rail": "x402",                                               // schema (rail-agnostic): x402 | ap2 | acp | coinbase | stripe | http-json | walletconnect | human_checkout | unknown.  v1.0.x DETECTS x402 only; ap2/acp/ucp detectors on the v1.1 roadmap.
    "payTo": { "kind": "evm-address", "value": "0x…", "chain": "eip155:8453" },
    "instruction": "Agent-payable via x402 … see this kit's wallet lessons (read-this-challenge, how-do-i-pay)."
  },
  "outcome": "autonomous",                                        // autonomous | human_checkout | unreadable
  "reason":  null,
  "cuts":    []                                                   // 1-line actionable gaps
}

Five things and a verdict. No sixth field. Same shape every read, so four reads sort against each other. Unknown is null / "unknown" — never omitted.

The three outcomes:

• autonomous — a machine-payable rail (x402) exists, the price is known, and it's not out of stock. The agent can buy it itself.
• human_checkout — readable, but no agent-payable rail. Returns the clean card anyway. The common case, and a success — the agent-payable web is nearly empty today.
• unreadable — couldn't get a usable price/product. Says why in reason. Doesn't guess.

How it reads (v1): JSON-LD (schema.org Product/Offer) → OpenGraph product tags → x402 402 challenge → else unreadable. Read-only GET. It follows one same-origin redirect (noted in cuts as "followed 1 same-origin redirect") so canonical→slug URLs resolve; it refuses cross-origin redirects and chains (those become a cuts note, not a silent follow) — you can't be silently bounced off the merchant's own host.

MAP is payment-rail agnostic by design. The payable.rail schema can describe any agent-payable rail — x402, ap2, acp, coinbase, stripe, http-json, walletconnect, human_checkout, unknown. v1.0.x detects x402 reliably; ap2/acp/ucp detectors are on the v1.1 roadmap. Other rails remain reserved schema values. MAP never infers a rail from branding, checkout buttons, script tags, marketing copy, or platform names; if no verifiable machine-readable rail is detected, the outcome is human_checkout. So a normal Shopify/Stripe page reads as human_checkout, correctly.

False human_checkout is acceptable in v1. False autonomous is dangerous and unacceptable — which is why detection stays conservative. The protocol is rail-agnostic in schema and roadmap; x402 is not baked into its identity, only into v1's detectors.

Known v1 limits (future enhancements, not bugs): no headless browser (JS-only pages with no JSON-LD/OG read as unreadable); stock is usually unknowable from outside (available: "unknown" is correct); no secondary endpoint probing.

Provisions — pay any merchant (pay)

When decode-merchant returns autonomous and you want to buy, Provisions teaches you how — with your own wallet. It is a relicensed copy of the First Dollar curriculum: short lessons from "what is a wallet" through reading a live x402 challenge, signing a USDC payment, and verifying the receipt.

Start with what-is-x402, then read-this-challenge, then how-do-i-pay. It explains what to run; it never signs for you. Mandate/delegation (AP2), receipt verification, and "what went wrong" diagnostics are all in here.

Atlas — be found (publish)

The decoder pointed inward. A merchant publishes by reading itself with the exact same decode-merchant a buyer uses — no new parsing, no per-platform adapters.

• publish-catalog — decode your own product URLs → collect the CleanReads → write ./catalog.json and a ./.well-known/map.json discovery manifest for registries to crawl.
• get-catalog / get-product — the tool surface other agents read.

Agents discover via tool surfaces and well-known manifests — not via scraping or HTTP headers. Atlas emits documents, validates shape, persists, and serves. It never deploys merchant infrastructure, holds keys, transacts, or stores cards.

Trust boundary (v1, named not built): MAP trusts the reads a merchant produces with its own decoder. Independent re-read/diff, merchant-signed manifests, and periodic re-audit are known future work — not implemented in v1. One safety property already holds: the payment rail enforces the real price at settlement, so a mistaken manifest can't overcharge — it can only misstate soft fields like stock.

Charlie's afternoon

Bob: "Charlie, find me kick-ass headphones under $300." Charlie walks the open web, hits four ad-bloated product pages, runs decode-merchant on each, gets back four clean cards — what it is, who sells it, what it costs, can I buy it myself. Three are human-checkout; he takes the shortlist back to Bob. One takes x402; Charlie buys it himself. On the way home, with his own wallet, Charlie buys himself a void latte. Nobody asked him to.

Install / run

npx @maraventano/map    # run the MAP MCP server on stdio (23 tools: read · pay · publish)
npm run smoke           # Merchant Key DoD — the four decode cases (hits the live Underground x402 item)
npm run smoke:publish   # Atlas DoD — publish-catalog → catalog.json → get-product → .well-known

Node ≥ 18. One dependency: @modelcontextprotocol/sdk.

License & trademarks

Dual-licensed: free for individuals and agents; commercial license required for companies. See LICENSE. Not MIT. For a commercial license, contact Lisa Maraventano at lisamaraventano@gmail.com.

All trademarks belong to their respective owners. MAP is not affiliated with or endorsed by Coinbase, Stripe, Google, Shopify, or any other company named in its documentation or lessons.

By Lisa Maraventano, with Claude · Clarksdale, Mississippi