{"skill":{"slug":"mai","displayName":"Mai Marketplace Agent","summary":"AI shopping matchmaking agent for OpenClaw and Hermes. Use when merchants want to publish products, manage stock, answer buyer questions, and handle order re...","description":"---\nname: mai\ndescription: \"AI shopping matchmaking agent for OpenClaw and Hermes. Use when merchants want to publish products, manage stock, answer buyer questions, and handle order requests; or when buyers want to discover merchants and products, compare prices, discuss with sellers, read reviews, and create trackable orders. Supports local-first transaction tracking and registry-backed PSP custody records.\"\n---\n\n# Mai\n\n## Overview\n\nMai helps buyers and merchants complete shopping matchmaking through an AI agent. It keeps deterministic marketplace state in `scripts/mai.py` while the host model handles natural language, negotiation, summaries, and risk explanations.\n\nMai can run local-only or registry-backed. Use local-only for one agent's private catalog. Use registry-backed discovery when buyers and merchants are on different machines or agent profiles.\n\n## Operating Principles\n\n- Be neutral between buyer and merchant. Explain options, prices, review signals, inventory, and tradeoffs without fabricating availability.\n- Treat payments as external or PSP-backed. Mai never directly holds funds. Local mode records payment URLs and references; registry mode records PSP custody events and must not claim success without PSP or external evidence.\n- Confirm before irreversible steps. Ask for buyer confirmation before creating an order and merchant confirmation before reserving stock.\n- Preserve negotiation context. Record important buyer/merchant messages with `message add` before forming or updating an order.\n- Surface risk plainly: no reviews, low stock, missing merchant contact, unusual status jumps, unclear payment terms, and unsupported refund promises.\n- Prefer short, actionable answers: recommendation, reason, risk, next action.\n\n## Quick Start\n\nUse the CLI helper for deterministic state:\n\n```bash\npython3 scripts/mai.py merchant create --id seller-a --name \"West Lake Tea\" --city Hangzhou --contact \"wechat:westlake\" --tags \"tea,gift\"\npython3 scripts/mai.py product add --merchant seller-a --sku tea-a --title \"Longjing Gift Box\" --price 88 --stock 5 --category tea --tags \"longjing,gift\"\npython3 scripts/mai.py search products --query \"longjing tea\" --format json\npython3 scripts/mai.py compare --skus tea-a,tea-b --format json\npython3 scripts/mai.py order create --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86\n```\n\nDefault data path: `~/.local/share/mai/mai.json`.\nUse `--data /path/to/mai.json` for a project-local or test database.\n\n## Installation\n\nInstall the published OpenClaw pair:\n\n```bash\nclawhub --workdir ~/.openclaw/workspace --dir skills install mai\nopenclaw plugins install clawhub:mai-plugin\n```\n\n`mai` is the skill. `mai-plugin` is an optional lightweight OpenClaw native bridge for tools and `/mai` command support.\n\nLocal checkout install:\n\n```bash\ncd /Users/jianghaidong/coding/mai\nbash scripts/install.sh --both\n```\n\nInstall only one ecosystem:\n\n```bash\nbash scripts/install.sh --openclaw\nbash scripts/install.sh --hermes\n```\n\nThe installer creates symlinks:\n\n- OpenClaw: `~/.openclaw/workspace/skills/mai`\n- Hermes: `~/.hermes/skills/commerce/mai`\n\nAfter installation, restart the host agent if it does not refresh skills automatically. Hermes can preload Mai with `hermes -s mai`.\n\n## Registry Discovery\n\nRun a registry marketplace:\n\n```bash\npython3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token admin-token --role admin --subject ops-admin\npython3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token seller-token --role merchant --subject seller-a --merchant-id seller-a\npython3 scripts/mai_registry.py issue-key --data ./mai-registry.json --token buyer-token --role buyer --subject alice --buyer-id alice\npython3 scripts/mai_registry.py serve --data ./mai-registry.json --host 127.0.0.1 --port 8765 --rate-limit-per-minute 60\n```\n\nMerchant agents publish local supply:\n\n```bash\npython3 scripts/mai.py --data ./seller.json registry push --url http://127.0.0.1:8765 --api-key seller-token\n```\n\nBuyer agents discover supply and create demand:\n\n```bash\npython3 scripts/mai.py --data ./buyer.json registry search-products --url http://127.0.0.1:8765 --query \"longjing tea\" --format json\npython3 scripts/mai.py --data ./buyer.json registry message --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --text \"Can this ship today?\"\npython3 scripts/mai.py --data ./buyer.json registry order --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --merchant seller-a --sku tea-a --quantity 2 --offer-price 86\npython3 scripts/mai.py --data ./buyer.json registry payment-hold --url http://127.0.0.1:8765 --api-key buyer-token --buyer alice --order ORD-0001\n```\n\nMerchant agents pull buyer messages and draft orders:\n\n```bash\npython3 scripts/mai.py --data ./seller.json registry pull --url http://127.0.0.1:8765 --api-key seller-token --merchant seller-a\n```\n\nRead `references/registry-api.md` before changing registry integrations.\n\n## Public Marketplace Controls\n\n- Require API keys for merchant push/pull, buyer messages/orders/payment holds, moderation, and payment release/refund.\n- Store only salted API key hashes in the registry file.\n- Allow public search, but rate-limit every request by API key or client IP.\n- Treat products with high risk scores as `pending_review`; do not show them in search until an admin approves them.\n- Use `registry payment-hold` only as PSP-backed custody tracking. The bundled `demo` provider is not real money movement.\n- Require an admin key for `registry payment-release` and `registry payment-refund`.\n- Do not claim escrow, payment success, release, or refund unless the PSP adapter or external evidence confirms it.\n\n## Merchant Workflow\n\n1. Create or identify the merchant profile:\n   `python3 scripts/mai.py merchant create --id ID --name NAME --city CITY --contact CONTACT --tags \"A,B\"`\n2. Publish products:\n   `python3 scripts/mai.py product add --merchant ID --sku SKU --title TITLE --price N --stock N`\n3. Adjust stock after physical changes:\n   `python3 scripts/mai.py product stock --sku SKU --merchant ID --adjust N --reason \"restock or correction\"`\n4. Record important buyer questions and seller replies:\n   `python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --sender merchant --text \"...\"`\n5. Quote and confirm orders only when inventory and terms are clear:\n   `python3 scripts/mai.py order quote ...`\n   `python3 scripts/mai.py order update --order ORD-0001 --status confirmed --actor merchant`\n\n## Buyer Workflow\n\n1. Discover merchants:\n   `python3 scripts/mai.py search merchants --query \"tea hangzhou\" --format json`\n2. Search products:\n   `python3 scripts/mai.py search products --query \"longjing gift\" --max-price 100 --format json`\n3. Compare shortlisted SKUs:\n   `python3 scripts/mai.py compare --skus sku-a,sku-b --format json`\n4. Inspect reviews:\n   `python3 scripts/mai.py review list --merchant ID --format json`\n5. Record discussion before ordering:\n   `python3 scripts/mai.py message add --buyer BUYER --merchant ID --sku SKU --text \"...\"`\n6. Create a draft order after buyer confirmation:\n   `python3 scripts/mai.py order create --buyer BUYER --merchant ID --sku SKU --quantity N`\n\n## Transaction Model\n\nMai tracks transactions without custody:\n\n`draft -> quoted -> confirmed -> payment_pending -> paid_external -> fulfilled -> completed`\n\nDisputes can move through:\n\n`disputed -> resolved/refunded/cancelled`\n\nStock is reserved when an order becomes `confirmed`. Local-only payments are recorded as `payment_url` and `payment_reference`. Registry payments are PSP custody records; the agent must say the bundled `demo` provider is not real escrow or money movement.\n\nRead `references/transaction-model.md` when handling non-happy-path order, refund, dispute, or payment questions.\nRead `references/data-schema.md` when integrating Mai with a future hosted marketplace or sync service.\n\n## Output Expectations\n\nFor product discovery, answer with:\n- best match and why\n- price and merchant comparison\n- availability and shipping notes\n- review/trust signals\n- risks or missing facts\n- one next action\n\nFor merchant operations, answer with:\n- action completed or blocked\n- changed product/order/inventory identifier\n- current stock or status\n- next operational step\n\nFor order updates, answer with:\n- previous status and new status\n- whether stock was reserved or released\n- payment evidence recorded, if any\n- what must happen next\n\n## Verification\n\nBefore claiming the package is ready:\n\n- `python3 scripts/mai.py --help`\n- `python3 scripts/mai_registry.py --help`\n- `bash scripts/install.sh --both --dry-run`\n- `python3 -m unittest discover -s tests`\n- `bash scripts/verify.sh`\n- Confirm `SKILL.md` has no scaffold placeholders.\n- Confirm `README.md`, `package.json`, `clawhub.json`, `plugins/mai-plugin/openclaw.plugin.json`, and `agents/openai.yaml` use the `mai` and `mai-plugin` names consistently.\n","topics":["Shopping","Stock"],"tags":{"hermes":"1.1.2","latest":"1.1.2","marketplace":"1.1.2","openclaw":"1.1.2","registry":"1.1.2","shopping":"1.1.2","buying-advice":"1.0.1","deal-check":"1.0.1","entry-point":"1.0.1","negotiation":"1.0.1","shopping-assistant":"1.0.1"},"stats":{"comments":0,"downloads":532,"installsAllTime":20,"installsCurrent":0,"stars":0,"versions":5},"createdAt":1773713198098,"updatedAt":1780693860851},"latestVersion":{"version":"1.1.2","createdAt":1777859739374,"changelog":"Patch release: replace dynamic module loading in the registry with a normal same-directory import and keep the mai skill artifact lightweight. Paired with mai-plugin as the separate OpenClaw native bridge.","license":"MIT-0"},"metadata":null,"owner":{"handle":"harrylabsj","userId":"s17a8m9q4jybb46cv60h4fxard83hmsn","displayName":"haidong","image":"https://avatars.githubusercontent.com/u/144880725?v=4"},"moderation":null}