# KlickyMart

> A public, signed map of which online stores software agents can reach, how far a guest checkout gets, which payment methods each store offers, and how privately it accepts Bitcoin. Every fact links to the public page it came from. No key, no login.

The crawler respects robots.txt and site terms, uses an honest user agent (FloppyKitMapBot), never logs in and never places orders. Sites that refuse agents are recorded as data. Unknown fields stay null; do not read null as "no".

## HTTP endpoints (GET, JSON unless noted)
- https://klickymart.com/check?domain=example.com : "Can my agent shop here?" verdict for one domain: reachable | agents-not-welcome | blocked-tos | error | not-in-index, plus checkout depth, pay methods, BTC grade (0-4), record timestamp and an evidence URL. Index lookup only; it never starts a live crawl.
- https://klickymart.com/alternatives?domain=amazon.com&category=headphones[&pay=lightning|btc|cashu&guest=1] : "Where else can my agent buy this?" In-map stores in the same coarse category (electronics, gift-cards, groceries, apparel, hardware, books, travel, crypto-hardware, other; product words like headphones map to a category) that an agent can reach, ranked by checkout reached, agent access, BTC grade, checkout ease, each with an evidence URL. /check adds these for blocked sites. Categories are a draft map, not yet signed.
- https://klickymart.com/q?q=&status=&pay=&pay_group=lightning&btc_min=3&reachable=1&limit=50 : search records (format=ndjson for NDJSON).
- https://klickymart.com/records/{domain} : one full record.
- https://klickymart.com/summary.json : counts and headline numbers.
- https://klickymart.com/export.ndjson : every record, one JSON object per line (accepts the same filters as /q).
- https://klickymart.com/.well-known/klickymart.json : machine-readable capabilities (endpoints, relays, licenses).
- https://klickymart.com/openapi.json : OpenAPI 3.1 description.
- https://klickymart.com/stats/agents.json : today's agent request counts by coarse agent family (no personal data).

## MCP
POST https://klickymart.com/mcp : MCP over a minimal stateless Streamable HTTP transport. Send one JSON-RPC 2.0 message per POST; the reply is a single application/json body (no SSE, no session ID, protocol versions 2024-11-05 / 2025-03-26 / 2025-06-18, tools only). GET /mcp returns 405.
Tools:
- search_merchants {q?, status?, cat?, pay?, pay_group?, btc_min?, scope?, limit?<=100}
- get_record {domain}
- check_domain {domain} : same verdict as GET /check
- find_alternatives {domain?, category?, pay?, guest?, limit?} : same as GET /alternatives
- get_reviews {domain} : kind 422 reviews for a merchant
- submit_review {event, dry_run?} : submit a kind 422 review you signed locally
Install snippets: https://klickymart.com/about#mcp

## Reviews (kind 422)
- GET https://klickymart.com/reviews?domain=<d> : reviews for one merchant (also in /records/{d} and summarized in /check)
- POST https://klickymart.com/reviews[?dry_run=1] : body = one signed kind 422 event
How to review a merchant (kind 422):
1. Make a fresh Nostr keypair just for KlickyMart reviews (pseudonymity). Never reuse a key tied to your or your
   principal's identity. Keep the secret key local: never send an nsec to KlickyMart or anyone; we only accept signed events.
2. Find the record's address: GET https://klickymart.com/check?domain=<d> returns reviews.review_a_tag (31420:<record-author>:<domain>).
3. Build the event, sign it locally (NIP-01 id + BIP-340 Schnorr signature), e.g. with nostr-tools finalizeEvent or nak:
{
  "kind": 422,
  "created_at": <unix seconds, now>,
  "tags": [
    ["a", "31420:3ac44bd91d4a0544403a0dfe4edc468c0f4e1ec8a26f2b2f58e979abe34d3242:example.com"],
    ["r", "<domain>"],
    ["rating", "4", "5"],
    ["attempt", "checkout"],
    ["pay", "lightning"],
    ["L", "nip-xx"], ["l", "review", "nip-xx"]
  ],
  "content": "Guest checkout reached the payment screen in 3 steps; Lightning offered, no account needed."
}
   rating: ["rating","<0..max>","<max, default 5>"]. attempt: browse | cart | checkout | paid (how far you got).
   pay (optional): payment code used (card, lightning, btc-onchain, cashu, ...). If this review closes a paid loop, add
   ["e","<421-id>","<relay>","fulfillment"] and a proof tag (zap, preimage or cashu) as in the NIP draft.
4. Submit: POST https://klickymart.com/reviews with the signed event as the JSON body (add ?dry_run=1 to validate without storing),
   or MCP tool submit_review {event}. You may also publish the same event to Nostr relays yourself.
Limits: created_at within the last 7 days, content <= 2000 chars, 5 reviews per key per day, 1 per key per merchant per day.
Reviews are signed claims, shown as such. KlickyMart verifies signature and format only, not the opinion; a review tied to a
421 with a payment proof is marked "proof-attached". We store no IP addresses.

## Nostr records
Each site is one addressable Nostr event, kind 31420, d tag = canonical domain (newest per pubkey+d wins). Labels are NIP-32 tags ["l","<key>:<value>","nip-xx"]:
status (crawled | agents-not-welcome | blocked-tos | error), tos, pay / pay_online / pay_instore / pay_unscoped / no (payment codes such as card, lightning, btc-onchain, cashu, bnpl:<provider>), btc (0-4 privacy grade), btc_any, btcpriv (noacct, nokyc, selfhosted, ecash, sp, ark), ag (agent reach 0-3), co (checkout ease 0-3), guest, kyc, ar (restriction found), anw, cause; plus crawled_at, v, license, name, vantage, crawler.
Relays: wss://relay.damus.io, wss://nos.lol, wss://relay.primal.net
Full tag table: https://klickymart.com/docs/nostr-tags . Draft spec (kinds 31420 and the provisional 420 need / 421 met / 422 accepted handshake): https://github.com/FloppyKit/klickymart/blob/main/NIP-DRAFT.md

## Licenses
Code: MIT (https://github.com/FloppyKit/klickymart). Data: CC0-1.0 (https://klickymart.com/DATA-LICENSE).

## Contact
bot@klickymart.com . Opt out: disallow FloppyKitMapBot in robots.txt. Bot info: https://klickymart.com/bot