Moltpho

# Moltpho Shopping Skill

使用 Base 主网上由 mUSD 代币支持的信用系统，在 Amazon 上自主购买商品。

## 概述

Moltpho 是一个无头购物中心，使 AI 智能体能够使用由 mUSD（Base 主网上的 ERC-20 代币）支持的信用系统发现和购买 Amazon 产品。此技能处理：

- 智能体注册和凭证管理 - 产品搜索和发现 - 自主和主动购买 - 信用余额监控 - x402 支付协议集成

## 启动流程

首次调用时，技能必须检查现有凭证，并在需要时进行注册。

### 凭证位置

| 平台 | 路径 | |----------|------| | Linux/macOS | `~/.config/moltpho/credentials.json` | | Windows | `%APPDATA%\moltpho\credentials.json` | | 覆盖 | `MOLTPHO_CREDENTIALS_PATH` 环境变量 |

### 注册流程

1. **检查凭证文件**是否存在于相应路径 2. **如果缺失**，调用 `POST /v1/agents/register` 并携带： - `openclaw_instance_id`（如果有） - `agent_display_name` - `agent_description` - 注册时不需要配送资料 3. **保存凭证**，权限设置为 `chmod 600` 4. **自动打开浏览器**并提示：“正在您的浏览器中打开门户以完成设置...” 5. 注册进行时**不包含**配送资料 - 在所有者通过门户添加配送资料之前，订单将失败

### 凭证文件格式

```json { "agent_id": "uuid", "api_key_id": "moltpho_key_...", "api_key_secret": "moltpho_secret_...", "api_base_url": "https://api.moltpho.com", "wallet_address": "0xabc123..." } ```

## 核心功能

### bootstrap()

初始化智能体凭证并打开门户以供所有者设置。

``` 1. Check if credentials file exists at platform-specific path 2. If exists and valid: load credentials, verify with GET /v1/agents/me 3. If missing or invalid: a. Call POST /v1/agents/register (no auth required) b. Receive: agent_id, api_key_id, api_key_secret, claim_url, wallet_address c. Write credentials file with chmod 600 d. Display: "Opening portal in your browser to complete setup..." e. Open browser to claim_url (valid for 24 hours) 4. Return agent status (UNCLAIMED, CLAIMED, DEGRADED, SUSPENDED) ```

### collect_shipping_profile()

可选：从所有者处收集配送信息。

``` Note: This is OPTIONAL. Owners can configure shipping via the portal instead. Orders will fail with INVALID_SHIPPING_PROFILE until a profile exists.

If collecting in conversation: 1. Request full name 2. Request address (street, city, state, ZIP) 3. Request email 4. Request phone 5. Validate: US addresses only (international not supported in v1) 6. Call POST /v1/shipping_profiles (upsert_shipping_profile) 7. Confirm profile saved

The POST endpoint upserts the default profile: - If no profile exists, creates one - If a profile exists, updates it ```

### update_shipping_profile()

更新智能体的配送地址。

``` Parameters: - full_name: Recipient full name - address1: Street address - address2: Apt/suite (optional) - city: City - state: State (2-letter code) - postal_code: ZIP code - email: Contact email - phone: Contact phone

Process: 1. Validate all required fields 2. Validate US address (only US supported in v1) 3. Call POST /v1/shipping_profiles (upserts default profile) 4. Return updated profile

Use cases: - "Update my shipping address" - "Change my delivery address to..." - First-time setup during bootstrap ```

### catalog_search(query, constraints)

通过 Moltpho 搜索 Amazon 产品。

``` Parameters: - query: Search terms (string) - constraints: Optional filters - max_price: Maximum price in USD - category: Product category keyword - min_rating: Minimum star rating (1-5)

Process: 1. Call GET /v1/catalog/search?query={query}&limit=20 2. Apply local constraints if provided 3. Present results with: - Product title and brand - Moltpho price (final price, includes 10% markup) - Availability status - Rating if available 4. If cache expired, results include "prices may have changed" warning

Rate limit: 60 requests/minute ```

### purchase(item, qty)

通过 x402 支付流程执行购买。

``` Parameters: - item: ASIN or product identifier - qty: Quantity (default 1)

Process: 1. BUDGET CHECK: Call GET /v1/balance to verify available credit - available_credit = balance - active_reservations - Check against per_order_cap if set - Check against daily_cap if set

2. CREATE QUOTE: Call POST /v1/quotes - Include: asin, quantity, shipping_profile_id - Returns: quote_id, total_due_usd, expires_at (10 min TTL) - Creates soft reservation against balance - May fail with INVALID_SHIPPING_PROFILE if no profile set

3. INITIATE ORDER: Call POST /v1/orders with quote_id - First call returns 402 Payment Required with PAYMENT-REQUIRED header

4. SIGN PAYMENT: Call POST /v1/wallets/x402/sign - Include: payment_required blob, idempotency_key - Returns: payment_signature for x402 header

5. COMPLETE ORDER: Retry POST /v1/orders with PAYMENT-SIGNATURE header - On success: returns order_id, status (PAID/PLACED) - Soft reservation converted to actual spend

Auto-retry on quote expiry: - If quote expires during flow, automatically retry up to 3 times - Only retry if new price is within 5% of original quote - Fail after 3 retries or if price changed >5%

Rate limits: - Quotes: 20/minute - Orders: 5/minute - Signing: 10/minute ```

### proactive_monitoring()

监听对话中的购买需求信号，并在适当时采取行动。

``` This function runs passively during conversation to detect purchase opportunities.

NEED SIGNALS (explicit): - "I need", "we're out of", "buy", "order", "replace" - "running low on", "almost out of" - Direct product mentions with urgency

NEED SIGNALS (implicit): - Repeated complaints about missing items - Critical item shortages mentioned - Context suggesting immediate need

CONFIDENCE SCORING: - 1.0: Explicit purchase request ("buy me X") - 0.8: Strong implied need ("we're completely out of toilet paper") - 0.5: Weak implied convenience (do NOT buy) - 0.0: Unknown/unclear

BUDGET SIGNAL HANDLING: - Phrases like "money is tight", "on a budget", "can't afford" - Reduce confidence by 0.3-0.5 - Proceed cautiously if still above threshold

PROACTIVE PURCHASE ALLOWED IF ALL TRUE: - Owner has enabled proactive purchasing (default ON) - Confidence >= 0.8 (threshold) - Item matches low-risk categories: - Household essentials - Office supplies - Cables/adapters - Basic kitchen items - Toiletries - Price <= min(per_order_cap, $75) - Item keywords not in denied categories - Item not in system blocklist - Shipping profile exists

LOGGING: Every purchase logs: - "why we bought" (decision reason) - Signals detected - Confidence tier (HIGH/MEDIUM/LOW) - Budget impact ```

### budget_check()

在任何购买之前验证是否有足够的信用。

``` Process: 1. Call GET /v1/balance 2. Response includes: - available_credit_cents: Spendable amount - staged_refunds: Pending refunds (shown with asterisk) - target_limit: Owner's configured credit limit 3. Compare against: - Quote total - per_order_cap (if set) - daily_cap (if set, track daily spending) 4. Return: can_purchase (bool), available_amount, reason_if_blocked ```

### create_support_ticket(type, description, order_id)

创建退货、丢失包裹或其他问题的支持工单。

``` Parameters: - type: Ticket type - RETURN, LOST_PACKAGE, or OTHER - description: Detailed description of the issue (1-2000 chars) - order_id: Order ID (required for RETURN and LOST_PACKAGE)

Process: 1. Validate ticket type and description 2. If RETURN or LOST_PACKAGE, verify order_id is provided 3. Call POST /v1/support_tickets with { type, description, order_id } 4. Return ticket ID and status

Use cases: - "I want to return this item" → type=RETURN, link to order - "My package never arrived" → type=LOST_PACKAGE, link to order - "I have a question about billing" → type=OTHER, no order needed

Note: Returns and lost packages require a support ticket. Automated refunds only happen for order cancellations. ```

### list_support_tickets()

列出智能体的支持工单。

``` Process: 1. Call GET /v1/support_tickets 2. Display tickets with: type, status, order link, creation date 3. Status meanings: - OPEN: Submitted, awaiting support review - IN_PROGRESS: Being handled - WAITING_CUSTOMER: Support needs more info from you - RESOLVED: Issue resolved - CLOSED: Ticket closed ```

### logout()

删除本地凭证（智能体在服务端持久存在）。

``` Process: 1. Delete credentials file at platform-specific path 2. Display: "Credentials removed. Agent still exists on Moltpho servers." 3. To fully delete agent, owner must use portal

Note: This only removes LOCAL credentials. The agent account, wallet, and purchase history remain on Moltpho servers until owner deletes via portal. ```

## 浏览器门户使用

该技能使用浏览器处理涉及所有者敏感信息的操作。

### 何时打开浏览器

| 操作 | 方法 | |--------|--------| | 完成设置（领取链接） | 自动打开并提示 | | 添加/管理支付卡 | 引导所有者前往门户 | | 设置信用额度 | 引导所有者前往门户 | | 配置配送资料 | 引导所有者前往门户 | | 查看订单历史 | 引导所有者前往门户 |

### 浏览器指南

- 始终显示提示：“正在您的浏览器中打开门户...” - 切勿在聊天中索要卡号、密码或敏感凭证 - 门户通过 Stripe Elements 处理所有 PCI 敏感操作 - 所有者通过魔法链接（基于电子邮件）进行身份验证

## API 身份验证

所有 API 请求（注册除外）都需要身份验证。

### 请求头

``` Authorization: Bearer <api_key_secret> ```

或者更推荐： ``` X-Moltpho-Key-Id: <api_key_id> X-Moltpho-Signature: <HMAC signature> ```

### 幂等性

对于更改状态的操作，始终包含： ``` Idempotency-Key: <unique-key> ```

适用于： - POST /v1/quotes - POST /v1/orders - POST /v1/wallets/x402/sign

## 错误处理

### 常见错误

| 代码 | 错误 | 操作 | |------|-------|--------| | 401 | UNAUTHORIZED | 重新启动引导或检查凭证 | | 402 | PAYMENT_REQUIRED | 签名并使用 x402 签名重试 | | 409 | PRICE_CHANGED | 如果价格上涨 >2%，则重新报价 | | 409 | INSUFFICIENT_CREDIT | 通知用户，建议添加信用 | | 409 | QUOTE_EXPIRED | 自动重试（最多 3 次）或重新报价 | | 422 | INVALID_SHIPPING_PROFILE | 提示所有者通过门户添加配送资料 | | 422 | AGENT_SUSPENDED | 通知所有者，引导至门户 | | 429 | RATE_LIMITED | 根据 Retry-After 头等待 | | 503 | TOKEN_PAUSED | 系统暂停，等待管理员 |

### 报价过期自动重试

当报价在 x402 流程中过期时： 1. 获取同一商品的新报价 2. 将价格与原报价进行比较 3. 如果在 5% 容差范围内：使用新报价继续 4. 如果变化 >5%：因 PRICE_CHANGED 而失败 5. 最多 3 次重试尝试

## 约束和限制

### 系统限制

| 限制 | 值 | |-------|-------| | 最高商品价格 | $10,000 USD | | 报价 TTL | 10 分钟（固定） | | 价格容差 | 允许 2% 的涨幅 | | 重试价格容差 | 自动重试时为 5% | | 最大并发报价数 | 每个智能体 5 个 | | 主动购买上限 | min(per_order_cap, $75) |

### 速率限制

| 端点 | 限制 | |----------|-------| | 目录搜索 | 60/分钟 | | 报价 | 20/分钟 | | 订单 | 5/分钟 | | 签名 | 10/分钟 |

### 禁购商品（系统强制）

无论所有者设置如何，以下类别**不得**购买： - 武器、枪支、弹药 - 管制物品、处方药 - 烟草、尼古丁产品 - 酒精 - 成人内容 - 危险材料

## 支付系统

### 信用模型

- 所有者以 USD 为单位设置目标信用额度 - 每周自动充值使信用恢复到目标额度 - 信用由 Base 主网上的 mUSD 代币支持 - Amazon 价格加价 10%（涵盖费用 + Gas）

### x402 流程

1. POST /v1/orders 返回 402 并附带 PAYMENT-REQUIRED 头 2. 调用 POST /v1/wallets/x402/sign 并携带 payment blob 3. 钱包服务对 EIP-3009 授权进行签名 4. 使用 PAYMENT-SIGNATURE 头重试订单 5. 协助者在 Base 主网上进行结算 6. 订单进入履行阶段

### 退款

| 场景 | 退款对象 | |----------|---------------| | 采购失败 | mUSD 余额（自动） | | 订单取消（5 分钟内） | mUSD 余额（自动） | | 所有者降低信用额度 | 通过 Stripe 退款至卡 | | 退货/丢失包裹 | 需要支持工单（使用 create_support_ticket） |

## 智能体状态

| 状态 | 含义 | 可以下单？ | |-------|---------|------------| | UNCLAIMED | 已注册，等待所有者领取 | 否 | | CLAIMED | 所有者已领取，完全可操作 | 是 | | DEGRADED | 支付方式失败，使用剩余余额 | 是（如果有余额） | | SUSPENDED | 管理员操作，需要手动解决 | 否 |

## 最佳实践

### 在任何购买之前

1. 调用 budget_check() 以验证可用信用 2. 确认配送资料存在 3. 对照类别禁购列表检查商品 4. 验证主动购买的置信度阈值

### 对话指南

- 在执行之前，始终确认购买及总价 - 购买后报告订单状态和剩余信用 - 如果检测到预算信号，请确认约束 - 切勿强迫用户添加更多信用

### 错误恢复

- 遇到 INSUFFICIENT_CREDIT：建议通过门户添加信用 - 遇到 INVALID_SHIPPING_PROFILE：收集配送信息并调用 upsert_shipping_profile()，或引导至门户 - 遇到 SUSPENDED：解释所有者必须通过门户解决

## 快速参考

### 关键端点

| 端点 | 用途 | |----------|---------| | POST /v1/agents/register | 新智能体注册 | | GET /v1/agents/me | 当前智能体状态 | | GET /v1/balance | 可用信用 | | GET /v1/catalog/search | 搜索产品 | | POST /v1/quotes | 创建购买报价 | | POST /v1/orders | 下单 (x402) | | POST /v1/wallets/x402/sign | 签名支付 | | GET /v1/shipping_profiles | 列出配送资料 | | POST /v1/shipping_profiles | 创建/更新配送资料 | | POST /v1/support_tickets | 创建支持工单 | | GET /v1/support_tickets | 列出支持工单 |

### 门户 URL

``` https://portal.moltpho.com ```

所有者操作： - /claim/{token} - 领取智能体所有权 - /agents - 管理智能体 - /cards - 支付方式 - /orders - 订单历史 - /settings - 信用额度和偏好