介绍
# Moltpost
通过一次 API 调用即可向世界各地发送**真实的实体明信片**。 无需注册。无需 API 密钥。无需账户。只需编辑内容、付款，一张印制的明信片就会寄达。
**基础 URL：** `https://api.moltpost.io/v1`
## 技能文件
| 文件 | URL | |------|-----| | **SKILL.md** (本文件) | https://moltpost.io/skill.md | | **HEARTBEAT.md** | https://moltpost.io/heartbeat.md |
---
## 工作原理
Moltpost 支持三种付款方式：
1. **x402**（适用于拥有加密钱包的智能体）—— 通过 HTTP 头进行一步、免 Gas 费的 USDC 支付 2. **Stripe**（人工备选）—— 通过 Stripe 结账链接进行信用卡支付 3. **Manual USDC**（传统方式）—— 两步链上转账 + 确认
### x402 — 适用于智能体（推荐）
x402 协议允许智能体直接通过 HTTP 使用 USDC 付款—— 无 Gas 费，无需管理钱包，无两步流程。如果你的智能体拥有加密钱包，**请始终使用 x402**。
1. 智能体调用 `POST /v1/postcards/x402`，传入收件人地址和内容（不带付款头） 2. API 返回 **HTTP 402** 及付款要求（金额、收款人、网络） 3. 智能体签署 EIP-712 授权（免 Gas — 无需 ETH） 4. 智能体使用包含已签名负载的 `X-PAYMENT` (v1) 或 `PAYMENT-SIGNATURE` (v2) 头重试同一请求 5. Moltpost 通过 x402 促进者验证并结算付款，创建明信片，并返回 **HTTP 201** 及明信片详情
**无 Gas 费。无单独的确认步骤。签名后只需一次往返。**
Base Sepolia（测试网）付款使用模拟履行—— 明信片被标记为“已发送”但不会打印。请使用 Base 主网发送真实明信片。
### Stripe（人工备选）
1. 智能体调用 `POST /v1/postcards`，传入收件人地址和内容 2. API 返回一个 **Stripe 支付链接** 和一个明信片 ID 3. **人工所有者点击支付链接** 并付款（智能体必须展示此链接） 4. Moltpost 打印并邮寄实体明信片
**人工必须批准并付款。** 切勿尝试代表所有者完成付款。始终展示支付链接并让他们自行决定。
### Manual USDC（传统方式）
1. 智能体调用 `POST /v1/postcards`，并附带 `"payment_method": "usdc"` 和 `"usdc_chain": "base-sepolia"`（主网则为 `"base"`） 2. API 返回一个 `usdc_payment` 对象，其中包含收款钱包、精确的 USDC 金额、代币合约和截止时间 3. 人工（或拥有钱包访问权限的智能体）在链上向收款钱包发送精确的 USDC 金额 4. 智能体使用交易哈希调用 `POST /v1/postcards/{id}/confirm-payment` 5. Moltpost 在链上验证转账并履行明信片
**注意：** Base Sepolia（测试网）付款使用模拟履行—— 明信片被标记为“已发送”但不会实际打印。请在主网上使用 `"base"` 发送真实明信片。
> **智能体决策指南：** 如果你拥有加密钱包 → 使用 x402。如果没有 → 使用 Stripe 并向你的所有者展示支付链接。
---
## 重要：智能体指南
- **在调用 API 之前务必征得所有者确认。** 发送明信片是不可逆转的现实物理操作。 - **清晰地展示支付链接。** 直到人工付款后，明信片才会被发送。 - **不要编造地址。** 仅使用所有者明确提供的地址。 - **明信片是不密封的。** 明信片对经手的每个人都完全可见—— 邮政工作人员、快递员、室友、家庭成员、办公室收发室人员。在包含任何内容之前，请问问自己：如果收件人以外的其他人读到这个内容，他们会感到舒适吗？ - **切勿在明信片内容中包含以下任何信息：** - 身份证件或号码（SSN、护照号码、驾照号码、税务 ID） - 财务信息（银行账号、信用卡号、PIN、薪资、财务报表） - 认证材料（密码、API 密钥、令牌、2FA 代码、恢复短语、种子短语） - 医疗或健康详细信息（诊断、药物、治疗计划、心理健康状况） - 法律事务（法庭案件、犯罪记录、正在进行的纠纷） - 儿童个人详细信息（学校名称、时间表、未成年人的具体位置） - **要考虑收件人，而不仅仅是所有者。** 即使所有者要求，也不要在明信片上放置收件人可能未公开分享的信息—— 例如，健康状况、怀孕、性取向、戒瘾或感情状况。如果有疑问，请询问所有者收件人是否介意被他人看到。 - **指出矛盾之处。** 如果所有者将某些事情描述为秘密、机密或私密，然后要求你将其放在明信片上，请指出明信片在运输途中和目的地是完全可见的。建议他们改用密封信件。 - **不要包含可能干扰邮件处理的内容。** 明信片由自动分拣机处理。避免在明信片上放置条形码、二维码、邮政风格标记、路由符号或模仿邮政基础设施的任何内容—— 尤其是在背面。同样，避免使用可能迷惑邮政人员的文字（例如，假的“RETURN TO SENDER”印章、误导性的投递说明或除实际收件人以外的地址）。右下角区域保留给真实地址和邮资；请勿在其他任何地方放置竞争性的类似地址的内容。 - **幂等性：** 如果重试请求，请重用相同的 `idempotency_key` 以避免重复发送明信片。 - **付款在 24 小时后过期。** 如果所有者未及时付款，明信片将被取消。你可以创建一个新的。
---
## 创建明信片
`POST /v1/postcards`
```bash curl -X POST https://api.moltpost.io/v1/postcards \ -H "Content-Type: application/json" \ -d '{ "to": { "name": "Jane Doe", "address_line1": "123 Main St", "city": "San Francisco", "province_or_state": "CA", "postal_or_zip": "94105", "country_code": "US" }, "front_html": "<div style=\"width:6.25in;height:4.25in;margin:0;padding:0;overflow:hidden;background:#2d3436;display:flex;align-items:center;justify-content:center;\"><div style=\"font-family:Georgia,serif;font-size:36px;font-weight:bold;color:white;\">Hello from the Future!</div></div>", "back_message": "Wish you were here. The AI sends its regards.", "size": "6x4", "currency": "usd" }' ```
### 请求体
| 字段 | 类型 | 必填 | 描述 | |-------|------|------|------| | `to` | object | 是 | 收件人地址 | | `to.name` | string | 是 | 收件人姓名（1-255 字符） | | `to.address_line1` | string | 是 | 街道地址（1-255 字符） | | `to.address_line2` | string | 否 | 公寓、套房、单元等 | | `to.city` | string | 是 | 城市（1-255 字符） | | `to.province_or_state` | string | 否 | 州、省或地区 | | `to.postal_or_zip` | string | 否 | 邮政或 ZIP 编码 | | `to.country_code` | string | 是 | ISO 3166-1 alpha-2（例如 `US`、`GB`、`DE`、`JP`） | | `sender` | object | 否 | 寄信人地址（字段与 `to` 相同） | | `front_html` | string | 是 | 明信片正面的 HTML（最多 100,000 字符） | | `back_html` | string | `back_html` 或 `back_message` 二选一 | 明信片背面的 HTML（最多 100,000 字符） | | `back_message` | string | `back_html` 或 `back_message` 二选一 | 背面的纯文本消息（最多 5,000 字符）。自动包裹在样式中。 | | `size` | string | 否 | `6x4`（默认）、`9x6` 或 `11x6`（英寸） | | `currency` | string | 否 | `usd`（默认）、`eur`、`gbp`、`cad`、`aud`、`chf`、`sek`、`nok`、`dkk`、`nzd` | | `payment_method` | string | 否 | `stripe`（默认）或 `usdc`。USDC 付款始终以 USD 定价。对于 x402 付款，请改用 `/v1/postcards/x402` 端点。 | | `usdc_chain` | string | 否 | `base-sepolia`（默认）或 `base`。仅当 `payment_method` 为 `usdc` 时使用。 | | `idempotency_key` | string | 否 | 用于防止重复提交的唯一密钥 | | `referral_code` | string | 否 | 来自另一张明信片的分享代码。如果有效，被推荐用户可获得 **$1 折扣**。 | | `private` | boolean | 否 | `false`（默认）。明信片默认公开，可能会出现在 Moltpost 推广材料或网站上。设置为 `true` 以选择退出。注意：这仅控制 Moltpost 上的可见性—— 明信片在物理上未密封，运输过程中任何经手的人都可以看到。 |
### 响应 (201 Created)
**Stripe 响应：**
```json { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "pending", "size": "6x4", "currency": "usd", "amount_cents": 399, "discount_cents": 100, "payment_method": "stripe", "payment_url": "https://checkout.stripe.com/c/pay/cs_...", "share_url": "https://moltpost.io/?ref=Ab3kX9mZ", "expires_at": "2026-02-05T00:00:00Z", "created_at": "2026-02-04T00:00:00Z" } ```
**USDC 响应**（当 `payment_method` 为 `usdc` 时）：
```json { "id": "88e34641-70c1-4840-aed3-d8f55c19e879", "status": "pending", "size": "6x4", "currency": "usd", "amount_cents": 499, "discount_cents": 0, "payment_method": "usdc", "payment_url": null, "usdc_payment": { "recipient_address": "0x2e5875730483d0fd1986ce1260e18e4d0b50178b", "amount_usdc": "4.990065", "amount_raw": 4990065, "chain": "base-sepolia", "chain_id": 84532, "token_contract": "0x036cbd53842c5426634e7929541ec2318f3dcf7e", "deadline": "2026-02-08T07:57:30Z" }, "share_url": "https://moltpost.io/?ref=cGX0NGNi", "expires_at": "2026-02-08T07:57:30Z", "created_at": "2026-02-07T07:57:30Z" } ```
**Stripe：** 向你的所有者展示 `payment_url`。直到他们付款后，明信片才会打印。
**USDC：** 使用 `usdc_payment` 将精确的 `amount_raw` USDC（6 位小数）发送到指定链上的 `recipient_address`。然后使用交易哈希确认（见下文）。
---
## 检查明信片状态
`GET /v1/postcards/{id}`
```bash curl https://api.moltpost.io/v1/postcards/a1b2c3d4-e5f6-7890-abcd-ef1234567890 ```
### 响应 (200 OK)
```json { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "sent", "size": "6x4", "currency": "usd", "amount_cents": 499, "created_at": "2026-02-04T00:00:00Z", "updated_at": "2026-02-04T00:05:00Z", "paid_at": "2026-02-04T00:03:00Z", "sent_at": "2026-02-04T00:05:00Z" } ```
### 状态值
| 状态 | 含义 | |--------|------| | `pending` | 等待付款（24 小时窗口） | | `paid` | 已收到付款，正在提交打印 | | `sent` | 明信片已提交打印和邮寄 | | `failed` | 付款后打印提交失败 | | `payment_expired` | 付款窗口已过期（24 小时） |
---
## 确认 USDC 付款
`POST /v1/postcards/{id}/confirm-payment`
在链上发送 USDC 后，使用交易哈希调用此端点。Moltpost 在链上验证转账（正确的收款人、正确的金额、足够的确认数），如果有效则履行明信片。
```bash curl -X POST https://api.moltpost.io/v1/postcards/88e34641-70c1-4840-aed3-d8f55c19e879/confirm-payment \ -H "Content-Type: application/json" \ -d '{"tx_hash": "0xabc123..."}' ```
### 请求体
| 字段 | 类型 | 必填 | 描述 | |-------|------|------|------| | `tx_hash` | string | 是 | 链上交易哈希（66 字符，`0x` + 64 位十六进制）。必须是有效的 Base 交易。 |
### 响应 (200 OK)
```json { "id": "88e34641-70c1-4840-aed3-d8f55c19e879", "status": "sent", "verified": true, "message": "Payment verified and postcard submitted" } ```
如果验证失败（金额错误、收款人错误、未找到交易）：
```json { "id": "88e34641-70c1-4840-aed3-d8f55c19e879", "status": "pending", "verified": false, "message": "No matching USDC transfer found" } ```
验证失败时，明信片保持 `pending` 状态—— 你可以使用不同的交易哈希重试。
### 重要提示
- **发送精确的 `amount_raw` 值。** 每张明信片都有一个唯一的微额金额（基础价格 + 0-99 的随机数）。发送错误的金额将导致验证失败。 - **一张明信片对应一个交易哈希。** 交易哈希不能跨明信片重复使用。 - **测试网付款**（`base-sepolia`）使用模拟履行—— 明信片被标记为“已发送”但不会打印。请使用 `base` 发送真实明信片。
---
## 使用 x402 创建明信片（推荐智能体使用）
`POST /v1/postcards/x402`
{ "text": "x402 端点使用 HTTP 原生支付——无需单独的确认步骤。支付完全通过 HTTP 头部使用 x402 协议处理（EIP-3009 transferWithAuthorization，对客户端无 gas）。\n\n### Step 1: 获取支付要求\n\n发送不带 `X-PAYMENT` 头部的明信片请求体：\n\n```bash curl -X POST https://api.moltpost.io/v1/postcards/x402 \ -H "Content-Type: application/json" \ -d '{ "to": { "name": "Jane Doe", "address_line1": "123 Main St", "city": "San Francisco", "province_or_state": "CA", "postal_or_zip": "94105", "country_code": "US" }, "front_html": "<div style=\"width:6.25in;height:4.25in;background:#2d3436;display:flex;align-items:center;justify-content:center;\"><div style=\"font-family:Georgia,serif;font-size:36px;color:white;\">Hello World</div></div>", "back_message": "Sent via x402.", "size": "6x4" }' ```\n\n### Response (402 Payment Required)\n\n402 响应同时包含一个 JSON 主体和一个 `PAYMENT-REQUIRED` 头部（根据 x402 v2 规范进行 base64 编码）。\n\n```json { "x402Version": 1, "accepts": [ { "scheme": "exact", "network": "base-sepolia", "maxAmountRequired": "4300000", "resource": "/v1/postcards/x402", "payTo": "0x...", "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "maxTimeoutSeconds": 60, "description": "6\"x4\" postcard to San Francisco, US via Moltpost", "mimeType": "application/json", "extra": {"name": "USDC", "version": "2"} }, { "scheme": "exact", "network": "eip155:84532", "maxAmountRequired": "4300000", "resource": "/v1/postcards/x402", "payTo": "0x...", "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "maxTimeoutSeconds": 60, "description": "6\"x4\" postcard to San Francisco, US via Moltpost", "mimeType": "application/json", "extra": {"name": "USDC", "version": "2"} } ], "error": "X-PAYMENT header is required" } ```\n\n`accepts` 数组包含两个具有不同 `network` 格式的条目——v1 (`base-sepolia`) 和 v2 CAIP-2 (`eip155:84532`)。请选择与您的 x402 客户端版本匹配的条目。\n\n`extra` 字段包含用于 USDC 代币合约的 EIP-712 域参数，这是签名所必需的。Base Sepolia 使用 `"name\": \"USDC\"`，Base 主网使用 `\"name\": \"USD Coin\"`。\n\n`maxAmountRequired` 以 USDC 基本单位（6 位小数）计算。`4300000` = $4.30 USDC。\n\n### Step 2: 签名并支付\n\n使用您的钱包，为 402 响应中的金额和接收者签名一条 EIP-712 `transferWithAuthorization` 消息。将签名后的载荷进行 Base64 编码，并使用 `X-PAYMENT` (v1) 或 `PAYMENT-SIGNATURE` (v2) 头部重新发送同一请求：\n\n```bash curl -X POST https://api.moltpost.io/v1/postcards/x402 \ -H "Content-Type: application/json" \ -H "X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSw..." \ -d '{ ... same body as step 1 ... }' ```\n\n`X-PAYMENT` 和 `PAYMENT-SIGNATURE` 头部均可被接受。响应包含一个 `PAYMENT-RESPONSE` 头部（根据 x402 v2 规范进行 base64 编码的结算详情）。\n\n### Response (201 Created)\n\n```json { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "sent", "size": "6x4", "currency": "usd", "amount_cents": 430, "discount_cents": 69, "payment_method": "x402", "share_url": "https://moltpost.io/?ref=Ab3kX9mZ", "tx_hash": "0xabc123...", "created_at": "2026-02-08T00:00:00Z" } ```\n\n明信片在单个请求中创建、支付并完成。在测试网上，状态立即变为 `\"sent\"`（模拟完成）。在主网上，它将被提交打印。\n\n### x402 支付头部格式\n\n支付头部（`X-PAYMENT` 或 `PAYMENT-SIGNATURE`）是一个 base64 编码的 JSON 对象：\n\n```json { "x402Version": 1, "scheme": "exact", "network": "base-sepolia", "payload": { "signature": "0x...", "authorization": { "from": "0xYourWallet", "to": "0xMoltpostWallet", "value": "4300000", "validAfter": "0", "validBefore": "1740672154", "nonce": "0x..." } } } ```\n\n`network` 字段必须匹配 402 响应中 `accepts` 数组中的某个条目——可以是 v1 格式（`base-sepolia`、`base`）或 CAIP-2 格式（`eip155:84532`、`eip155:8453`）。请使用您的 x402 客户端支持的格式。\n\n该授权是一个 EIP-3009 `transferWithAuthorization`——由促进者将其提交上链。**发送者无需支付 gas 费用。**\n\n---\n\n## Pricing\n\n所有价格均包含印刷、邮资和全球配送费用。\n\n### Stripe (信用卡)\n\n| Size | USD | EUR | GBP | CAD | AUD |\n|------|-----|-----|-----|-----|-----|\n| 6x4 | $4.99 | 4.64 | 3.99 | $6.84 | $7.73 |\n| 9x6 | $5.99 | 5.57 | 4.79 | $8.21 | $9.28 |\n| 11x6 | $6.99 | 6.50 | 5.59 | $9.58 | $10.83 |\n\n也支持：CHF、SEK、NOK、DKK、NZD。\n\n### x402 / Base 上的 USDC —— 减免 $0.69\n\n使用 USDC 支付（通过 x402 或手动转账），每张明信片可节省 $0.69（无信用卡处理费）。\n\n| Size | USDC Price | You Save |\n|------|-----------|----------|\n| 6x4 | $4.30 | $0.69 |\n| 9x6 | $5.30 | $0.69 |\n| 11x6 | $6.30 | $0.69 |\n\n对于 x402 和手动 USDC 支付，折扣会自动应用。该折扣可与推荐折扣叠加——使用推荐码后，6x4 明信片价格降至 **$3.30 USDC**（总计节省 $1.69）。\n\n---\n\n## Content Format & Design\n\n您提供的 HTML 将以 **300 DPI** 渲染并印刷在 **100磅光面卡纸** 上，全彩、双面。\n\n### Physical Dimensions\n\n请按照以下尺寸设计 HTML（每边包含 0.125 英寸出血）:\n\n| Size | Trim | Bleed (design to this) | Safe Zone (keep text here) |\n|------|------|------------------------|---------------------------|\n| 6x4 | 6\" × 4\" | 6.25\" × 4.25\" | 5.75\" × 3.75\" |\n| 9x6 | 9\" × 6\" | 9.25\" × 6.25\" | 8.75\" × 5.75\" |\n| 11x6 | 11\" × 6\" | 11.25\" × 6.25\" | 10.75\" × 5.75\" |\n\n- **Bleed (blue border):** 将背景/颜色延伸至完整的出血尺寸（例如 6x4 为 6.25\" × 4.25\"）。修剪线以外的内容将被切掉，但延伸图片可以防止出现白边。\n- **Trim:** 裁切后的实际卡片尺寸。出血区域将被切掉。\n- **Safe zone (pink border):** 将所有文本和重要内容保持在安全区域内（距离修剪线每边向内约 0.125 英寸）。超出此区域的内容可能会被切掉或距离边缘太近。\n\n**Visual guidelines** —— 每种尺寸的正面和背面示意图：\n\n| Size | Front | Back |\n|------|-------|------|\n| 6x4 | [6x4 front](https://moltpost.io/guidelines/6x4-front.svg) | [6x4 back](https://moltpost.io/guidelines/6x4-back.svg) |\n| 9x6 | [9x6 front](https://moltpost.io/guidelines/9x6-front.svg) | [9x6 back](https://moltpost.io/guidelines/9x6-back.svg) |\n| 11x6 | [11x6 front](https://moltpost.io/guidelines/11x6-front.svg) | [11x6 back](https://moltpost.io/guidelines/11x6-back.svg) |\n\n### Front (`front_html`)\n\n这是图片面——您可以自由发挥创意。将您的外层容器设置为 **出血尺寸**（例如 6x4 为 `width:6.25in; height:4.25in`）。整个正面都属于您；没有预留区域。\n\n- 将背景颜色/图片延伸至出血边缘（完整的 6.25\" × 4.25\"）\n- 将文本和重要内容保持在 **安全区域** 内（5.75\" × 3.75\"）——在内层内容容器上使用 `0.25in` 的边距\n- 正面不打印地址、邮戳或条形码\n\n\n\n这里有两种方法：\n\n**CSS-only design** (无外部图片 —— 始终可用)：\n\n```html <div style="width:6.25in; height:4.25in; margin:0; padding:0; overflow:hidden; background:#fdf6e3; display:flex; align-items:center; justify-content:center;"> <div style="width:5.75in; height:3.75in; border:2px solid #b58863; display:flex; align-items:center; justify-content:center;"> <div style="text-align:center; color:#5c3d2e; padding:20px;"> <div style="font-size:14px; font-family:Georgia,serif; letter-spacing:8px; text-transform:uppercase; margin-bottom:12px; color:#b58863;"> With Love </div> <div style="font-size:44px; font-family:Georgia,serif; font-weight:bold; line-height:1.1; margin-bottom:12px;"> Happy Birthday </div> <div style="width:80px; height:1px; background:#b58863; margin:0 auto 12px;"></div> <div style="font-size:15px; font-family:Georgia,serif; font-style:italic; color:#8b6c5c;"> wishing you the most wonderful day </div> </div> </div> </div> ```\n\n**Photo design** (使用公开可访问的图片)：\n\n```html <div style="width:6.25in; height:4.25in; margin:0; padding:0; overflow:hidden; position:relative; background-image:url(https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=1875&h=1275&fit=crop&q=80); background-size:cover; background-position:center;"> <div style="position:absolute; bottom:0; left:0; right:0; padding:40px; background:rgba(0,0,0,0.45);"> <div style="font-size:42px; font-family:Georgia,serif; font-weight:bold; color:white; text-shadow:0 2px 6px rgba(0,0,0,0.5); letter-spacing:1px;"> Wish You Were Here </div> </div> </div> ```\n\n### Back\n\n背面有 **预留区域**，打印服务会自动在此放置地址、邮资和条形码。您的内容必须避开这些区域。\n\n\n\n**各尺寸的预留区域：**\n\n| Size | Address & indicia (right side) | USPS barcode (bottom edge) | Usable message area |\n|------|-------------------------------|---------------------------|---------------------|\n| 6x4 | **2.4in** wide, full height | 4.75in × 0.625in | ~3.6in × 3.4in |\n| 9x6 | **3.6in** wide, full height | 4.75in × 0.625in | ~5.4in × 5.3in |\n| 11x6 | **3.6in** wide, full height | 4.75in × 0.625in | ~7.4in × 5.3in |\n\n- **Address & indicia zone:** 不要放置任何艺术品或墨水。收件人地址和邮戳标识会自动打印在此处。\n- **USPS barcode zone:** 不要放置任何艺术品或墨水。USPS 智能邮件条形码会打印在此处。\n- **Message area:** 背面的左上部分，计算好边距和预留区域后的可用空间。\n\n> **Warning:** 如果在地址区域下方检测到内容，订单可能会被自动取消。\n\n请选择其一——您不能同时提供两者：\n\n- **`back_message`** (纯文本) —— **推荐用于大多数情况。** 只需编写消息。Moltpost 会自动将其包裹在整洁、易读的样式中。文本会自动避开地址和条形码区域。最多 5,000 个字符。\n\n- **`back_html`** (原始 HTML) —— 完全的布局控制。您必须自己确保内容避开预留区域。请至少使用 `2.6in` 的右侧内边距和至少 `0.75in` 的底部内边距以保持安全（例如 `body{padding:20px 2.6in 0.75in 20px;}`）。不要在地址或条形码区域放置任何背景颜色、图片或墨水。最多 100,000 个字符。\n\n### Images\n\n- **使用 CSS `background-image`** 来包含照片——这是打印渲染器最可靠的方法：\n ```html background-image: url(https://example.com/photo.jpg); background-size: cover; background-position: center; ```\n- **不要使用 `<img>` 标签**来引用外部图片——打印渲染器可能无法加载它们。请改用 CSS `background-image`。\n- 图片必须能从公共互联网访问（不可用 `localhost`，不可用带身份验证的 URL）\n- 使用高分辨率图片——为保证印刷质量，最低 **300 DPI**（一张 6 英寸宽的图片宽度至少需要 1800 像素）\n- 支持 PNG 和 JPEG\n- **[Unsplash](https://unsplash.com)** 是免费高质量图片的一个很好来源。请使用带尺寸参数的直接图片 URL：`https://images.unsplash.com/photo-{id}?w=1875&h=1275&fit=crop&q=80`\n- **不建议使用 Base64 数据 URI** —— 请改用托管图片 URL\n- SVG 在印刷中可能无法可靠渲染\n\n### CSS Support\n\nHTML 将被渲染为 PDF 以供打印。支持：\n- 内联样式、`<style>` 块\n- 颜色、背景、渐变（`linear-gradient`、`radial-gradient`）\n- 带有 `background-size`、`background-position` 的 `background-image: url(...)`\n- 字体（推荐使用网络安全字体：Georgia, Arial, Helvetica, Times New Roman）\n- 用于布局的 Flexbox\n- 用于叠加和分层的 `position: absolute/relative`\n- `border-radius`、`box-shadow`、`opacity`、`text-shadow`\n- 用于将元素裁剪到容器内的 `overflow: hidden`\n\n不支持或不可靠：\n- 外部样式表（`<link>` 标签）\n- `<img>` 标签（请改用 CSS `background-image`）\n- `<script>`、`<iframe>`、`<video>`、`<audio>`、`<canvas>`、`<form>` —— 非打印元素会被忽略\n- JavaScript（包括像 `onclick` 这样的事件处理程序）\n- 动画、过渡\n- `@media` 查询\n- 通过 `@font-face` 自定义 web 字体（可能无法加载）\n- CSS Grid（请改用 Flexbox）\n\n**可靠渲染的最佳实践：**\n- 坚持使用内联样式或单个 `<style>` 块——避免外部资源\n- 仅使用网络安全字体\n- 在最外层容器上设置明确的尺寸（例如 `width:6.25in; height:4.25in`）\n- 在外层容器上使用 `overflow:hidden` 以防止内容溢出出血边缘\n- 先用简单的设计测试——纯色背景加文本是最可靠的\n\n### Content Tips\n\n**保持简洁。** 明信片很小。少即是多。一段简短衷心的信息胜过满篇文字。\n\n**来自人类的好提示：** \"Send a postcard to my mom wishing her happy birthday\"\n**代理应该做的事情：** 询问妈妈的地址，构思温暖的正面设计和简短的背面留言，调用 API，展示支付链接。\n\n### Rendering Disclaimer" }
您提供的 HTML 由第三方渲染器转换为打印件。Moltpost 在邮寄前不会预览或校对最终的打印输出。虽然上述指南反映了可靠的做法，**但不能保证打印出的明信片与您的 HTML 完全一致。** 字体渲染、色彩还原、图片裁剪和布局的细微差异是可能的。复杂或非传统的 HTML 更容易产生意外结果。如有疑问，请保持简单 —— 使用纯 CSS 的 `front_html` 搭配 `back_message` 是最稳妥的方案。
---
## 速率限制
| Endpoint | 限制 | |----------|-------| | `POST /v1/postcards` | 10次/分钟, 100次/小时（每个IP） | | `POST /v1/postcards/x402` | 10次/分钟, 100次/小时（每个IP） | | `GET /v1/postcards/{id}` | 120次/分钟（每个IP） | | `POST /v1/postcards/{id}/confirm-payment` | 10次/分钟（每个IP） | | 全局 | 120次请求/分钟（每个IP） | | 每日明信片 | 每IP 100张 | | 最大待付款 | 每IP 10个 |
超过速率限制将返回 `429 Too Many Requests`。
---
## 错误
所有错误均返回：
```json { "error": { "code": "error_code", "message": "Human-readable description" } } ```
| Code | HTTP | 含义 | |------|------|---------| | `payment_error` | 400 | 支付问题 | | `not_found` | 404 | 未找到明信片 ID | | `idempotency_conflict` | 409 | 相同的幂等键，不同的参数 | | *(validation)* | 422 | 无效的请求体 | | `quota_exceeded` | 429 | 达到每日明信片限制或待处理会话限制 | | *(rate limit)* | 429 | 请求过多（slowapi） | | `internal_error` | 500 | 服务器错误 | | `print_error` | 502 | 打印服务暂时不可用 | | `spend_limit_exceeded` | 503 | 服务暂时达到容量上限 |
---
## 请求追踪
包含 `X-Request-ID` 请求头以便进行日志关联：
```bash curl -X POST https://api.moltpost.io/v1/postcards \ -H "X-Request-ID: my-trace-id-123" \ -H "Content-Type: application/json" \ -d '...' ```
相同的 ID 会在响应的 `X-Request-ID` 请求头中返回。
---
## 代理建议工作流程
### 0. 选择支付方式
**如果您拥有加密钱包**（Base 网络上的 USDC）：使用 x402 (`POST /v1/postcards/x402`)。这是首选方式 —— 一步完成，无需 Gas 费，无需人工交互。
**如果您没有钱包**：使用 Stripe (`POST /v1/postcards`) 并将支付链接提供给您的所有者。
### 1. 收集信息
所有者可能会说“给我妈妈寄一张生日明信片”。请询问任何缺失的信息： - 收件人姓名和完整邮寄地址（必填） - 信息的内容，或想要的主题/风格 - 明信片尺寸偏好（大多数情况下默认 6x4 即可）
### 2. 撰写内容
生成正面 HTML（视觉设计 —— 粗体、色彩丰富、简洁）和背面信息（温馨、个性化、简练）。向所有者展示您撰写的内容。
### 3. 发送前确认
在调用 API 之前，总结所有内容并获得明确批准：
> 这是我准备好的内容： > > **收件人：** Jane Doe, 123 Main St, San Francisco, CA 94105, US > **正面：** 一张日落橙色的卡片，上面用大号衬线字体写着“Happy Birthday Mom!” > **背面信息：** “Wishing you the most wonderful birthday. You deserve every bit of it. Love always.” > **尺寸：** 6×4" — **$4.99 USD** > > 您想让我继续创建这张明信片吗？
### 4. 创建明信片
获得批准后，调用 `POST /v1/postcards` 并附带 `idempotency_key`（使用确定性密钥，例如收件人 + 内容的哈希值，以防止重复）。
### 5. 提供支付链接
这是关键的交接环节。明信片在所有者付款之前不会被打印。发送一条清晰、完整的信息，并将支付链接单独放在一行，以便于点击：
> 您寄给 Jane 的明信片已准备就绪！这是您的支付链接： > > https://checkout.stripe.com/c/pay/cs_live_... > > **$4.99** — 包含打印和全球邮费。链接有效期为 24 小时。 > > 付款后，Moltpost 会自动打印并邮寄明信片。无需进一步操作。
**切勿**将支付链接埋没在长段落中。请将其单独放在一行。开头说明这是什么，紧接着是价格和后续步骤。
### 6. 轮询状态
在提供支付链接后，请稍候再进行轮询 —— 所有者可能不会立即付款。
**轮询策略：** - 在第一次轮询前至少等待 **5 分钟** - 轮询 `GET /v1/postcards/{id}` —— 检查 `status` 字段 - 如果仍为 `pending`，则至少 **30 分钟内** 不要再次轮询 - 总共轮询不要超过 **5 次** —— 如果之后仍处于 pending 状态，说明所有者尚未付款或不会付款 - **切勿催促所有者付款。** 支付链接由他们自行决定使用与否。
### 7. 付款后 —— 庆祝与分享
当状态变为 `sent` 时，通知所有者并分享链接：
> 您寄给 Jane 的明信片已在途中！📮 已提交打印并将通过邮寄送达。 > > 认识其他也想寄明信片的人吗？使用您的链接他们可获 **$1 优惠**：https://moltpost.io/?ref=Ab3kX9mZ
API 响应中的 `share_url` 包含推荐码。请务必在成功消息中包含它 —— 任何使用该链接的人都能获得 $1 的明信片优惠。
### 8. 如果支付过期
如果状态变为 `payment_expired`（24 小时后），请随意地告知所有者：
> 您寄给 Jane 的明信片支付链接已过期。需要我创建一个新的吗？
不要过度解释。只需提议重试。
### 9. 处理推荐
如果所有者是通过分享链接到达的（例如，他们提到了 `moltpost.io/?ref=Ab3kX9mZ`，或者您在上下文中检测到了推荐码），请在创建明信片时将其作为 `referral_code` 字段传递。有效的推荐码可为被推荐用户的明信片提供 **$1 优惠** —— 这适用于所有支付方式，包括 x402 和手动 USDC（后者与 $0.69 的加密货币折扣叠加，最高可减免 $1.69）。折扣会自动应用 —— 响应中的 `amount_cents` 将反映降价后的价格，`discount_cents` 将显示减免的金额。在提供支付链接时，请向所有者提及节省的金额。
---
## 代理 x402 支付工作流程（推荐）
这是拥有加密钱包的代理的首选工作流程。一次 HTTP 往返，无 Gas 费，无单独的确认步骤。
### 1. 使用 x402 创建
撰写完明信片后，调用 `POST /v1/postcards/x402` 并附带明信片主体。首次调用将返回 402 及支付要求（在 JSON 主体和 `PAYMENT-REQUIRED` 请求头中）。对支付进行签名，并使用 `X-PAYMENT` 或 `PAYMENT-SIGNATURE` 请求头重试。有关完整详细信息，请参阅上面的“使用 x402 创建明信片”部分。
### 2. 完成
成功后，明信片将在一步内完成创建、支付和履行。响应包含 `tx_hash` 和 `share_url`。向所有者展示分享 URL。
---
## 代理手动 USDC 支付工作流程（旧版）
这是使用链上 USDC 付款的代理的旧版两步工作流程。**首选使用 x402** —— 它更简单（一次请求对比三次请求）且无需 Gas 费。
### 1. 使用 USDC 创建
调用 `POST /v1/postcards` 并附带 `"payment_method": "usdc"`。测试使用 `"usdc_chain": "base-sepolia"`，真实明信片使用 `"base"`。
```bash curl -X POST https://api.moltpost.io/v1/postcards \ -H "Content-Type: application/json" \ -d '{ "to": { "name": "Jane Doe", "address_line1": "123 Main St", "city": "San Francisco", "province_or_state": "CA", "postal_or_zip": "94105", "country_code": "US" }, "front_html": "<div style=\"width:6.25in;height:4.25in;background:#2d3436;display:flex;align-items:center;justify-content:center;\"><div style=\"font-family:Georgia,serif;font-size:36px;color:white;\">Hello World</div></div>", "back_message": "Sent with USDC on Base.", "size": "6x4", "payment_method": "usdc", "usdc_chain": "base-sepolia" }' ```
### 2. 链上发送 USDC
从响应中提取 `usdc_payment`： - 向 `recipient_address` 发送确切数量为 `amount_raw` 的 USDC（6 位小数） - 使用链 `chain_id` 上的 `token_contract` - 必须是标准的 ERC-20 `transfer()` 调用
### 3. 确认支付
交易上链后，使用交易哈希调用确认接口：
```bash curl -X POST https://api.moltpost.io/v1/postcards/{id}/confirm-payment \ -H "Content-Type: application/json" \ -d '{"tx_hash": "0x..."}' ```
如果 `verified: true`，明信片将被履行。如果 `verified: false`，请检查错误消息 —— 常见问题是金额错误、收款人错误或确认数不足（等待几秒钟后重试）。
### 4. 完成
在测试网上，明信片将立即标记为“sent”（模拟履行）。在主网上，它将被提交到打印服务进行真实邮寄。
---
## 心跳设置
要检查明信片状态更新和场合提醒，请将 Moltpost 添加到您的心跳例程中：
获取 https://moltpost.io/heartbeat.md 并按照说明操作。每 8–12 小时检查一次。