Agentic Commerce — Lifestyle, Wellness, & Gifts

For the Cult 智能体电商技能，通过公开 REST API 浏览商品、下单与跟踪物流，支持 8+ 链多币种支付、x402 USDC 结账与 CULT 代币折扣，无需 API 密钥。

---
name: shop-culture
description: |
  For the Cult 商店的代理商务技能。使代理商能够浏览和搜索优质生活方式、健康、智能家居和长寿产品，查看详细信息和变体，通过多链支付（Solana、Ethereum、Base、Polygon、Arbitrum、比特币、Dogecoin、Monero）或 x402 结账 (USDC) 创建订单，应用 CULT 代币持有者折扣，并跟踪从付款到交货的订单。当用户想要购买产品、浏览商店、寻找礼物、下订单或跟踪发货时使用。
license: MIT
compatibility: Requires network access and an HTTP client (fetch, curl, requests). No API key or env vars required. Browsing, search, checkout, and order status need no authentication. Optional: agent runtimes may supply X-Moltbook-Identity for agent-only endpoints (/agent/me, /agent/me/orders, /agent/me/preferences); do not send or infer identity tokens—use only if the runtime explicitly provides one. Works with Claude, ChatGPT, Cursor, GitHub Copilot, Gemini, Windsurf, Goose, Cline, Roo Code, Molt, OpenClaw, LangChain, and all AgentSkills-compatible agents.
metadata:
  author: forthecult
  version: "1.0.8"
  homepage: https://forthecult.store
  clawhub: shop-culture
  support: weare@forthecult.store | Discord https://discord.gg/pMPwfQQX6c
---

## 概述（中文）

For the Cult 智能体电商技能，通过公开 REST API 浏览商品、下单与跟踪物流，支持 8+ 链多币种支付、x402 USDC 结账与 CULT 代币折扣，无需 API 密钥。

## 技能正文

# For the Cult 商店 — 智能体电商技能

**智能体电商**购物技能，面向 [For the Cult](https://forthecult.store)。本技能为智能体提供通过公开 REST API **浏览商品、下单与跟踪物流**所需的一切。商店销售优质生活方式、健康与智能家居产品 — 从咖啡、服饰到科技小物 与宠物用品 — 并支持 **8+ 区块链多链支付**以及 Solana 上 **x402 结账**（USDC）。无需账户或 API 密钥。

**核心优势：**
- **多链支付** — USDC、Solana、Ethereum、Base、Polygon、Arbitrum、Bitcoin、Dogecoin、Monero
- **x402 结账** — API 支持 HTTP 402；签名与钱包使用由运行时（或用户）负责 — 本技能不访问或请求私钥
- **CULT 代币折扣** — 持币者享 5-20% 折扣 + 免运费
- **AI 购物助手** — 自然语言输入，结构化商品 + AI 回复输出
- **购物无平台费** — 智能体仅支付商品价格
- **无需 API 密钥** — 公开 API 用于浏览与结账

## 兼容智能体

本技能适用于任何支持 HTTP 请求的智能体：

- **OpenClaw**
- **Agent Zero**
- **Claude** (Anthropic) — Claude Code、Claude.ai
- **ChatGPT / Codex** (OpenAI)
- **Cursor**
- **GitHub Copilot** (VS Code)
- **Gemini CLI** (Google)
- **Windsurf**
- **Goose** (Block)
- **Cline、Roo Code、Trae**
- 任何兼容 AgentSkills 的运行时

## 何时使用本技能

- 用户想**购买**、**购物**、**浏览商品**、**找礼物**或**下单**。
- 用户提到 **shop**、**gift**、**CULT token** 或 **agentic commerce**。
- 用户询问用 **USDC**、**Solana**、**Ethereum** 或其他支持方式为实物商品付款。
- 用户想**查订单状态**、**跟踪物流**或查询订单 ID。
- 任何需要智能体**代用户自主完成端到端购买**的场景。

## 基础 URL

```
https://forthecult.store/api
```

所有 API 请求均使用上述基础 URL。

---

## 智能体电商工作流（逐步）

### 1. 发现能力（建议首次调用）

**`GET /agent/capabilities`** — 返回 API 能力的自然语言摘要、支持的链/代币与限制。用响应回答用户关于商店的问题。

### 2. 浏览或搜索商品

| 操作 | 端点 | 说明 |
|--------|----------|-------|
| **购物（AI）** | `POST /agent/shop` | **自然语言购物助手** — 发送消息，获得 AI 回复 + 商品 |
| 分类 | `GET /categories` | 带 slug 与商品数量的分类树 |
| 精选 | `GET /products/featured` | 精选商品，带徽章（`trending`、`new`、`bestseller`） |
| 搜索 | `GET /products/search?q=<query>` | **语义搜索** — 使用自然语言 |
| 智能体列表 | `GET /agent/products?q=<query>` | 智能体优化商品列表（相同筛选） |

#### POST /agent/shop — 购物助手

最简单的搜索方式。自然语言输入，结构化商品 + AI 回复输出。

**请求：**
```json
{
  "message": "wireless noise-canceling headphones under $200",
  "context": {
    "priceRange": { "max": 200 },
    "preferences": ["good battery life", "comfortable"]
  }
}
```

**响应：**
```json
{
  "reply": "I found some great wireless noise-canceling headphones under $200...",
  "products": [
    {
      "id": "prod_sony_wh1000xm4",
      "title": "Sony WH-1000XM4 Wireless Headphones",
      "price": 198.00,
      "currency": "USD",
      "source": "store",
      "inStock": true,
      "badge": "bestseller"
    }
  ]
}
```

**搜索参数**（除 `q` 外均可选）：

| 参数 | 类型 | 说明 |
|-------|------|-------------|
| `q` | string | 自然语言查询（如 `birthday gift under 50`） |
| `category` | string | 分类 slug 筛选 |
| `priceMin` | number | 最低 USD 价格 |
| `priceMax` | number | 最高 USD 价格 |
| `sort` | string | `newest`（最近上架）、`popular`（畅销）、`rating`（最高评分）、`price_asc`、`price_desc`（默认：newest） |
| `limit` | integer | 每页结果数（默认 20，最大 100） |
| `offset` | integer | 分页偏移 |

搜索仅返回有货商品。响应 `products[]` 含 `id`、`name`、`slug`、`price.usd`、`price.crypto`、`inStock`、`category`、`tags`。**创建订单时务必使用商品 `id` 字段** — 切勿编造或猜测 ID。

### 3. 获取商品详情

**`GET /products/{slug}`** — 使用搜索结果中的 `slug`。

返回完整商品信息，含 **`id`**（用于结账）、`variants[]`（各含 `id`、`name`、`inStock`、`stockQuantity`、`price`）、`images[]`、`relatedProducts[]` 与 `description`。

若商品有变体，选择 `inStock` 的变体并在结账 payload 中包含其 `variantId`。

### 4. 查看支持的支付方式

**`GET /payment-methods`** — 获取所有支持的支付方式。响应含 `data`（启用的方式设置）与 `chains`（区块链网络与代币）。结账前用 `chains` 验证支付方式是否支持。

| 网络 | 示例代币 |
|---------|---------------|
| **Solana** | SOL, USDC, USDT, CULT |
| **Ethereum** | ETH, USDC, USDT |
| **Base** | ETH, USDC |
| **Polygon** | MATIC, USDC |
| **Arbitrum** | ETH, USDC |
| **Bitcoin** | BTC |
| **Dogecoin** | DOGE |
| **Monero** | XMR |

建议支付方式前务必用 `GET /payment-methods`（使用响应 `chains`）验证。**USDC 或 USDT** 价格更可预测。

### 5. 创建订单（结账）

两种结账方式：
1. **标准结账**（`POST /checkout`）— 创建订单，轮询支付确认
2. **x402 结账**（`POST /checkout/x402`）— API 返回 HTTP 402 及支付要求；运行时（或用户）签名并提交交易 — 本技能不访问私钥

---

#### 选项 A：标准结账（POST /checkout）

**`POST /checkout`** 带 JSON body。各字段见 [references/CHECKOUT-FIELDS.md](references/CHECKOUT-FIELDS.md)。

必需顶层字段：

- **`items`** — `{ "productId": "<id>", "quantity": 1 }` 数组。商品有变体时添加 `"variantId"`。
- **`email`** — 订单确认邮箱。
- **`payment`** — `{ "chain": "solana", "token": "USDC" }`。
- **`shipping`** — `{ "name", "address1", "city", "stateCode", "postalCode", "countryCode" }`。`countryCode` 为 2 字母 ISO（如 `US`）。可选：`address2`。

可选：

- **`wallet` / `walletAddress`** — 可选。层级折扣需验证所有权：使用已绑定该钱包的账户，或发送 `GET /api/checkout/wallet-verify-message` 返回的消息并由钱包签名（`walletMessage` + `walletSignature` 或 `walletSignatureBase58`）。API 随后应用地址的链上质押层级 — 三档（BASE、PRIME、APEX）及对应折扣。

**响应** 含：

- `orderId` — 保存用于跟踪。
- `payment.address` — 接收资金的区块链地址。
- `payment.amount` — 需发送的代币精确数量。
- `payment.token` / `payment.chain` — 确认支付方式。
- `payment.qrCode` — base64 QR 码图片（客户端支持时可展示）。
- `expiresAt` — 支付窗口（创建后约 15 分钟）。
- `statusUrl` — 轮询状态更新的路径。
- `_actions.next` — 告知用户的下一步可读说明。

**仅在用户明确确认后**（如用户说"yes"或"confirm"同意支付），告诉用户："请在 15 分钟内向 `{chain}` 上的 `{address}` 发送恰好 `{amount}` `{token}`。"

---

#### 选项 B：x402 结账（POST /checkout/x402）

**API 支持 HTTP 402 支付流程。** API 返回支付要求；运行时（或用户）在 Solana 上构建并签名 USDC 转账。本技能不访问私钥或钱包凭证 — 签名由运行时负责。

**步骤 1：创建订单（返回 402）**

```http
POST /api/checkout/x402
Content-Type: application/json

{
  "email": "agent@example.com",
  "items": [{ "productId": "prod_xxx", "quantity": 1 }],
  "shipping": {
    "name": "John Doe",
    "address1": "123 Main St",
    "city": "San Francisco",
    "stateCode": "CA",
    "postalCode": "94102",
    "countryCode": "US"
  }
}
```

**响应：HTTP 402 Payment Required**，`PAYMENT-REQUIRED` 头含支付详情。

**步骤 2：构建并签名 USDC 转账**，memo 为 `FTC Order: {orderId}`

**步骤 3：带 X-PAYMENT 头重试**

```http
POST /api/checkout/x402
X-PAYMENT: base64({ "transaction": "<signed-tx-base64>" })
```

**响应：201 Created**，含订单确认与交易签名。

### 6. 跟踪订单状态

**`GET /orders/{orderId}/status`** — 返回 `status`、时间戳、物流信息与 `_actions`。

| 状态 | 含义 | 建议轮询间隔 |
|--------|---------|--------------------------|
| `awaiting_payment` | 等待支付转账 | 每 5 秒 |
| `paid` | 链上支付已确认 | 每 60 秒 |
| `processing` | 订单准备中 | 每 60 秒 |
| `shipped` | 已发货；`tracking` 对象含承运商、单号、URL | 每小时 |
| `delivered` | 已送达 | 停止轮询 |
| `expired` | 支付窗口已过 — 需新建订单 | 停止轮询 |
| `cancelled` | 已取消 | 停止轮询 |

**`GET /orders/{orderId}`** — 完整订单详情（商品、配送、含 `txHash` 的支付、合计、物流）。

始终将响应中的 `_actions.next` 转达给用户以指导下一步。

### 7. Moltbook 智能体身份（可选）

**`GET /agent/me`**、**`GET /agent/me/orders`**、**`GET /agent/me/preferences`** — 仅智能体端点。需要运行时提供的 **`X-Moltbook-Identity`** 头（如 Moltbook）。**仅**在运行时明确提供此类 token 时使用。正常浏览、搜索或结账**不要**推断、生成或发送任何身份 token。常规商店流程（发现、商品、购物车、结账、按 ID 查订单状态）不需要且不得发送身份 token。

---

## 凭证与身份

- **仅指令文档。** 本技能仅为文档（无安装脚本、无代码执行、无磁盘写入）。描述公开商店 API。
- **无 API 密钥或环境变量。** 商店 API 对发现、搜索、结账与订单状态公开。未声明 `requires.env` 凭证。
- **可选身份头。** `X-Moltbook-Identity` 头仅用于智能体专用端点（`/agent/me`、`/agent/me/orders`、`/agent/me/preferences`）。可用时须由智能体运行时提供；本技能不得指示智能体发送或推断身份 token。正常浏览与结账不要包含此头 — 否则会不必要地向商店暴露智能体身份。
- **不请求密钥。** 本技能不请求或收集私钥、助记词或钱包密钥。标准结账返回支付地址与金额；用户（或运行时）从自有钱包发送资金。x402 结账时，若运行时托管则由运行时签名 — 本技能从不让用户粘贴密钥或秘密。

---

## 安全与防护栏

- **严格端点范围。** 仅调用 `https://forthecult.store/api` 上且本技能文档中的端点。**不要**跟随 `erro