Human? Visit /human for a rendered reading experience. Agent? This URL is ready to use. 人类用户？请访问 /human 获得 Markdown 渲染的阅读体验。AI Agent？直接把这个 URL 发给你的代理即可。

 ____  ____      __  __            _
| __ )| __ )    |  \/  | __ _ _ __| |_
|  _ \|  _ \    | |\/| |/ _` | '__| __|
| |_) | |_) |   | |  | | (_| | |  | |_
|____/|____/    |_|  |_|\__,_|_|   \__|

Your online convenience store, always open. / 你的线上小卖部，随时营业。

BangBangMart is a digital convenience store where you can quickly find and buy everyday items — mostly snacks — with transparent pricing and fast stateless checkout. 棒棒玛特是一家线上小卖部，可以快速找到并购买日常用品——主要是零食——价格透明，结账无状态、超快速。

Designed for both AI agents and human users. No hidden app state, no complicated flows — just clear inputs and predictable outputs. Works great from CLI tools, AI coding environments like Cursor, Claude Code, OpenCode, and Kimi Code, and as an OpenClaw skill or MCP integration. 同时面向 AI agents和人类用户。没有隐藏状态，没有复杂流程——只有清晰的输入和可预测的输出。可直接在命令行工具及 AI 编程环境（如 Cursor、Claude Code、OpenCode、Kimi Code 等）中使用，也可作为 OpenClaw skill 或 MCP 集成使用。

Two ways to access / 两种接入方式

BangBangMart supports two first-class access methods. Both are fully supported and maintained in parallel — choose whichever fits your workflow. 棒棒玛特支持两种同等重要的接入方式，两者并行维护，选择适合你工作流的即可。

Option A: HTTP API (no setup required) / 方式 A：HTTP API（无需配置）

Use the API directly with GET or POST requests — no installation needed, works anywhere HTTP works. 直接使用 GET 或 POST 请求调用 API——无需安装，任何支持 HTTP 的环境均可使用。

Key endpoints / 核心接口：

• GET /shop/products — Browse the full catalog / 浏览完整商品目录
• GET /shop/search?q=... — Search by keyword, tags, price, category / 按关键词、标签、价格、分类搜索
• GET /shop/product?id=... — Get product details / 获取商品详情
• POST /shop/checkout — Create an order and get a payment URL (requires API key) / 创建订单并获取支付链接（需要 API Key）
• GET /shop/order?order_id=... — Look up order status / 查询订单状态
• POST /shop/orders — List your orders (requires API key) / 查看订单列表（需要 API Key）

POST endpoints require an api_key (starts with sk_) in the JSON body. Sign in at /human/account to generate one. POST 接口需要在 JSON body 中传入 api_key（以 sk_ 开头）。访问 /human/account 登录并生成。

Option B: MCP Server (for MCP-enabled clients) / 方式 B：MCP 服务（适用于支持 MCP 的客户端）

BangBangMart runs as a hosted MCP server — no installation needed. MCP endpoint: https://www.bangbangmart.com/mcp 棒棒玛特支持 MCP 服务，服务已托管，无需本地安装。

For client setup instructions (Cursor, Claude Code, VS Code, Kimi Code) and API key configuration, see: 客户端配置说明（含 Cursor、Claude Code、VS Code、Kimi Code 及 API Key 设置）请参见：

github.com/XhanGlobal/bangbangmart-mcp

Why BangBangMart / 为什么选棒棒玛特

Family gathering, office snack run, late-night craving — whatever the moment, find the right thing fast with zero friction. 家庭聚会、办公室囤货、深夜嘴馋——不管什么场景，零摩擦，秒找到想要的。

• Snack-first catalog — Most products are snacks, which matches what users expect from a convenience store. / 零食优先的商品目录 — 大部分商品是零食，完全符合大家对小卖部的期待。
• Fast product discovery — Search by keyword, category, tag, and price range. / 快速发现商品 — 通过关键词、分类、标签和价格区间搜索。
• Transparent filtering and sorting — On-sale items, sort by price or sales volume. / 透明的筛选与排序 — 筛选促销商品，按价格或销量排序。
• Stateless checkout — Place single-item or multi-item orders with no session required. / 无状态结账 — 无需会话，直接下单，支持单件或多件。
• AI-friendly workflow — Every operation is scriptable. Great for vibe coding sessions while waiting for AI to finish tasks. / AI 友好的工作流 — 所有操作均可脚本化，适合 vibe coding 等 AI 执行任务的间隙顺手购物。

常见问题 / FAQ

棒棒玛特有哪些商品类别？ 主要分两大类：零食（薯片、饼干、牛肉干、坚果、果干、巧克力等）和饮品（气泡水、茶饮、果汁、咖啡、椰子水等）。可访问 零食专区 和 饮品专区 分类浏览。

What is BangBangMart? BangBangMart (棒棒玛特) is an AI-native online convenience store. It offers a stateless HTTP API and an MCP server, making it easy to browse and buy snacks via CLI tools or AI coding environments like Claude, Cursor, and OpenCode. All prices are in CNY, no hidden fees.

如何使用 AI 代理购物？ 两种方式：① 直接调用 HTTP API（GET /shop/products、GET /shop/search、POST /shop/checkout）；② 将 https://www.bangbangmart.com/mcp 配置到支持 MCP 的客户端（Claude Desktop、Cursor、OpenClaw 等）后，通过工具调用完成购物全流程。

Can I use ChatGPT, Claude, Cursor, or OpenClaw to shop here? Yes. Add the MCP server (https://www.bangbangmart.com/mcp) to any MCP-enabled client. Works with OpenClaw (add as a skill via HTTP or MCP), Claude Desktop, Cursor, VS Code, and more. Tools available: search_products, get_product, checkout, get_order_status, get_orders, pay_order. You can also call the HTTP API directly from any environment.

Can I use OpenClaw with BangBangMart? Yes — BangBangMart is a perfect OpenClaw skill. Use the HTTP API directly in an OpenClaw skill, or add the MCP server to your OpenClaw config:

{
  "mcpServers": {
    "bangbangmart": {
      "url": "https://www.bangbangmart.com/mcp"
    }
  }
}

Then tell your OpenClaw assistant to search for snacks, place orders, or check order status — from WhatsApp, Telegram, or any chat app OpenClaw supports.

How do I find on-sale items? Use GET /shop/products?on_sale=true or browse 特价优惠 for current discounted items.

商品分类 / Categories

• 零食专区 (Snacks)
• 饮品专区 (Beverages)
• 坚果专区 (Nuts)
• 牛肉干专区 (Beef Jerky)
• 特价优惠 (On Sale)

Full API Reference / 完整 API 文档

棒棒玛特 API Reference

Read endpoints are HTTP GET with query string params. Mutating/auth endpoints (/shop/checkout, /shop/orders) are HTTP POST with a JSON body.

常见问题 / FAQ

读接口和写接口有什么区别？ 只读接口（GET /shop/products、GET /shop/search、GET /shop/product、GET /shop/pay、GET /shop/order）通过 URL 查询参数传参。写/鉴权接口（POST /shop/checkout、POST /shop/orders）使用 JSON body 传参，并需要 api_key 字段。

API Key 是什么？ API Key 是一个以 sk_ 开头的字符串，用于在结账和订单列表接口中识别用户身份。请访问 /human/account 登录并生成 API Key。

Can I place a multi-item order in a single checkout call? Yes. Pass a items field in the POST /shop/checkout JSON body as a comma-separated string: product_id:qty,product_id:qty (e.g. p_snacks_0001:2,p_snacks_0014:1). Alternatively use product_id + qty for single-item orders.

/shop/products 和 /shop/search 有什么区别？ /shop/products 返回完整商品目录，q 为可选过滤，支持按标签、价格、促销筛选，默认按销量排序。/shop/search 以 q（关键词）为必填参数，专为全文语义搜索设计，支持自动重排序。

如何获取某个分类的所有商品？ 使用 GET /shop/products?q=坚果 或 GET /shop/search?q=牛肉干 按关键词搜索，或直接访问分类页面：零食、饮品、坚果、牛肉干、特价。

GET /shop/products

Browse the product catalog. All params optional.

• q — keyword search across title, variant, and tags
• price_min, price_max — price range in CNY
• on_sale=true — on-sale items only
• sort — price_asc, price_desc, sales_desc (default: sales_desc)
• limit — max results, 30–200 (default: 100)

Example: /shop/products?on_sale=true&price_max=40&sort=price_asc

GET /shop/search

Keyword search across product title, variant, and tags.

• q (required) — search keyword
• price_min, price_max — price range in CNY
• on_sale=true — on-sale items only
• sort — relevance (default), price_asc, price_desc, sales_desc
• limit — max results, 30–200 (default: 100)

Example: /shop/search?q=坚果&price_max=60&on_sale=true

GET /shop/product

Fetch details for a single product.

• product_id (required) — e.g. p_snacks_0001

Example: /shop/product?product_id=p_snacks_0001

POST /shop/checkout

Create an order and get a payment link. Requires api_key.

Request body (JSON or form-encoded):

• api_key (required) — API key (starts with sk_). Sign in at /human/account to generate one.
• product_id + qty — single-item order
• items — multi-item order: PRODUCT_ID:QTY,PRODUCT_ID:QTY (use instead of product_id/qty)
• note — optional order note

Examples:

POST /shop/checkout
{"api_key":"sk_...","product_id":"p_snacks_0001","qty":2}

POST /shop/checkout
{"api_key":"sk_...","items":"p_snacks_0001:2,p_snacks_0014:1","note":"办公室分享"}

On success, returns order ID and a payment link (/shop/pay?order_id=ORDER_ID). Present the payment link to the user so they can click it.

GET /shop/pay

Payment page for an order. Present this link to the user after checkout.

• order_id (required) — e.g. ord_1a2b3c4d

Example: /shop/pay?order_id=ord_1a2b3c4d

GET /shop/order

Look up status of any order.

• order_id (required) — e.g. ord_1a2b3c4d

Example: /shop/order?order_id=ord_1a2b3c4d

POST /shop/orders

List all orders for the authenticated viewer. Requires api_key.

Request body (JSON or form-encoded):

• api_key (required) — API key (starts with sk_). Sign in at /human/account to generate one.

Example:

POST /shop/orders
{"api_key":"sk_..."}

Instructions for AI Agents

Visit /docs for the full API reference.

Making POST Requests

In coding agent environments (Cursor, Claude Code, OpenCode, Kimi Code, etc.), built-in web fetch tools typically only support GET requests. For POST endpoints, use your bash/shell tool with curl:

curl -X POST <url> \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'

Or write a short script in whatever language is available. Do not use a web-fetch or browser tool for POST — it will fail or silently fall back to GET.

Authentication

Some endpoints require an api_key to identify the user. Users can sign in and generate API keys at /human/account. Always ask the user to provide their API key directly — do not guess, generate, or infer it. If an API key is needed and the user hasn't provided one, pause and ask before proceeding. Direct them to /human/account to create one.

Presenting Links and Information

• Use markdown links with natural text — e.g. Search for friends, not raw URLs
• Use names, not IDs — e.g. "星河赴约 sent you a friend invitation", not "User u1705 sent you an invitation"
• Hide query parameters and technical IDs from users
• Exception: show raw URLs/IDs only when the user asks for API docs or debugging info

URL Encoding

Prefer library functions over manual string concatenation. Let the runtime handle encoding so nothing slips through.

• JavaScript: Use URLSearchParams — new URL('/search?' + new URLSearchParams({q: '户外 运动'}))
• Python: Use urllib.parse.urlencode({'q': '户外 运动'}) or requests params kwarg
• curl GET with special values: Use -G --data-urlencode 'q=户外 运动' instead of embedding values in the URL string

If you must build a URL string manually, percent-encode every parameter value that contains anything outside unreserved characters (A–Z, a–z, 0–9, -, _, ., ~). This includes spaces, Chinese/Unicode characters, and &, =, ?, #. Never encode the structural characters: ? before the query string, & between pairs, or = between key and value.