Moltpho 购物技能

在 Base 主网上使用基于信用的 mUSD 代币，自主地在亚马逊上购物。

概述

Moltpho 是一个无头购物商城，它使 AI 代理能够使用基于 mUSD（Base 主网上的 ERC-20 代币）的信用系统来发现和购买亚马逊产品。此技能处理：

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

启动流程

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

凭证位置

注册流程

1. 检查凭据文件在适当的路径
2. 如果缺失，调用POST /v1/agents/register携带：
   • openclaw_instance_id（如果可用）
   • agent_display_name
   • agent_description
   • 注册时无需配送配置文件
3. 保存凭据使用chmod 600权限
4. 自动打开浏览器并显示提示："正在浏览器中打开门户以完成设置..."
5. 注册继续进行，无需配送配置文件 - 在所有者通过门户添加之前，订单将失败

凭据文件格式

{
  "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在亚马逊上搜索产品。

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

错误处理

常见错误

报价过期自动重试

当报价在x402流程中过期时：

1. 获取同一商品的新报价
2. 与原报价比较价格
3. 若在5%容差范围内：使用新报价继续
4. 若变化超过5%：以“价格已变更”失败处理
5. 最多3次重试尝试

约束与限制

系统限制

速率限制

禁止购买项目（系统强制执行）

无论所有者设置如何，以下类别均无法购买：

• 武器、枪支、弹药
• 管制物质、处方药
• 烟草、尼古丁产品
• 酒精
• 成人内容
• 危险材料

支付系统

信用模式

• 所有者设定以美元计的目标信用额度
• 每周自动充值恢复信用至目标额度
• 信用由Base主网上的mUSD代币支持
• 在亚马逊价格基础上加价10%（覆盖手续费+gas费）

x402流程

1. POST /v1/orders 返回402，并带有PAYMENT-REQUIRED头部
2. 调用 POST /v1/wallets/x402/sign 并附带支付数据块
3. 钱包服务签署EIP-3009授权
4. 使用PAYMENT-SIGNATURE头部重试订单
5. 协调者确定使用Base主网
6. 订单进入履行阶段

退款

代理状态

最佳实践

购买前

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

对话指南

• 执行前始终确认购买总价
• 购买后报告订单状态及剩余额度
• 若检测到预算信号，需确认限制条件
• 切勿施压用户充值

错误恢复

• 当出现 INSUFFICIENT_CREDIT 时：建议通过门户添加额度
• 当出现 INVALID_SHIPPING_PROFILE 时：收集配送信息并调用 upsert_shipping_profile()，或引导至门户
• 关于"已暂停"状态：所有者需通过门户网站解决

快速参考

核心端点

门户网站地址

https://portal.moltpho.com

所有者操作：

• /claim/{token} - 认领代理所有权
• /agents - 管理代理
• /cards - 支付方式
• /orders - 订单历史
• /settings - 信用额度与偏好设置