Moltpost
将真实的实体明信片寄到世界任何地方。可使用 x402（Base 上的 USDC）、Stripe，或手动 USDC 转账支付。无需注册，无需 API 密钥——只需一次 API 调用。
作者：cktc · 最新版本：1.3.1
收藏：0 · 下载：1.7k
说明文档
# Moltpost
Send **real physical postcards** anywhere in the world through a single API call.
No registration. No API key. No account. Just compose, pay, and a printed postcard arrives in the mail.
**Base URL:** `https://api.moltpost.io/v1`
## Skill Files
| File | URL |
|------|-----|
| **SKILL.md** (this file) | https://moltpost.io/skill.md |
| **HEARTBEAT.md** | https://moltpost.io/heartbeat.md |
---
## How It Works
Moltpost supports three payment methods:
1. **x402** (preferred for agents with crypto wallets) — one-step, gasless USDC payment via HTTP headers
2. **Stripe** (fallback for humans) — credit card payment via Stripe checkout link
3. **Manual USDC** (legacy) — two-step onchain transfer + confirmation
### x402 — Preferred for Agents (Recommended)
The x402 protocol lets agents pay with USDC directly via HTTP — no gas fees, no wallet management, no two-step flow. If your agent has a crypto wallet, **always use x402**.
1. Agent calls `POST /v1/postcards/x402` with recipient address and content (no payment header)
2. API returns **HTTP 402** with payment requirements (amount, recipient, network)
3. Agent signs an EIP-712 authorization (gasless — no ETH needed)
4. Agent retries the same request with `X-PAYMENT` (v1) or `PAYMENT-SIGNATURE` (v2) header containing the signed payload
5. Moltpost verifies and settles the payment via the x402 facilitator, creates the postcard, and returns **HTTP 201** with postcard details
**No gas fees. No separate confirmation step. One round-trip after signing.**
Base Sepolia (testnet) payments use mock fulfillment — the postcard is marked "sent" but not printed. Use Base mainnet for real postcards.
### Stripe (fallback for humans)
1. Agent calls `POST /v1/postcards` with recipient address and content
2. API returns a **Stripe payment link** and a postcard ID
3. **Human owner clicks the payment link** and pays (agent must present this link)
4. Moltpost prints and mails the physical postcard
**The human must approve and pay.** Never attempt to complete payment on behalf of the owner. Always present the payment link and let them decide.
### Manual USDC (legacy)
1. Agent calls `POST /v1/postcards` with `"payment_method": "usdc"` and `"usdc_chain": "base-sepolia"` (or `"base"` for mainnet)
2. API returns a `usdc_payment` object with the recipient wallet, exact USDC amount, token contract, and deadline
3. Human (or agent with wallet access) sends the exact USDC amount to the recipient wallet onchain
4. Agent calls `POST /v1/postcards/{id}/confirm-payment` with the transaction hash
5. Moltpost verifies the transfer onchain and fulfills the postcard
**Note:** Base Sepolia (testnet) payments use mock fulfillment — the postcard is marked as "sent" but not actually printed. Use `"base"` for real postcards on mainnet.
> **Agent decision guide:** If you have a crypto wallet → use x402. If you don't → use Stripe and present the payment link to your owner.
---
## Important: Agent Guidelines
- **Always confirm with your owner** before calling the API. Sending a postcard is a real-world, irreversible physical action.
- **Present the payment link clearly.** The postcard is not sent until the human pays.
- **Do not fabricate addresses.** Only use addresses the owner has explicitly provided.
- **Postcards are not sealed.** A postcard is fully visible to every person who handles it — postal workers, mail carriers, roommates, family members, office mailroom staff. Before including any content, ask yourself: would the recipient be comfortable if someone other than them read this?
- **Never include any of the following in postcard content:**
- Identity documents or numbers (SSNs, passport numbers, driver's license numbers, tax IDs)
- Financial information (bank account numbers, credit card numbers, PINs, salary, financial statements)
- Authentication material (passwords, API keys, tokens, 2FA codes, recovery phrases, seed phrases)
- Medical or health details (diagnoses, medications, treatment plans, mental health status)
- Legal matters (court cases, criminal records, ongoing disputes)
- Children's personal details (school names, schedules, specific locations of minors)
- **Think about the recipient, not just the owner.** Even if the owner asks, do not put information on a postcard that the recipient may not have shared publicly — for example, a health condition, pregnancy, sexual orientation, addiction recovery, or relationship status. If in doubt, ask the owner whether the recipient would be comfortable with anyone seeing it.
- **Flag contradictions.** If the owner describes something as secret, confidential, or private and then asks you to put it on a postcard, point out that postcards are fully visible in transit and at the destination. Suggest they consider a sealed letter instead.
- **Do not include content that could interfere with mail processing.** Postcards are handled by automated sorting machinery. Avoid putting barcodes, QR codes, postal-style markings, routing symbols, or anything that mimics postal infrastructure on the postcard — especially on the back. Similarly, avoid text that could confuse postal workers (e.g., fake "RETURN TO SENDER" stamps, misleading delivery instructions, or addresses other than the actual recipient). The back-right area is reserved for the real address and postage; do not place competing address-like content anywhere else.
- **Idempotency:** If retrying a request, reuse the same `idempotency_key` to avoid duplicate postcards.
- **Payment expires in 24 hours.** If the owner doesn't pay in time, the postcard is cancelled. You can create a new one.
---
## Create a Postcard
`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"
}'
```
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `to` | object | Yes | Recipient address |
| `to.name` | string | Yes | Recipient name (1-255 chars) |
| `to.address_line1` | string | Yes | Street address (1-255 chars) |
| `to.address_line2` | string | No | Apt, suite, unit, etc. |
| `to.city` | string | Yes | City (1-255 chars) |
| `to.province_or_state` | string | No | State, province, or region |
| `to.postal_or_zip` | string | No | Postal or ZIP code |
| `to.country_code` | string | Yes | ISO 3166-1 alpha-2 (e.g. `US`, `GB`, `DE`, `JP`) |
| `sender` | object | No | Return address (same fields as `to`) |
| `front_html` | string | Yes | HTML for the front of the postcard (max 100,000 chars) |
| `back_html` | string | Exactly one of `back_html` or `back_message` | HTML for the back of the postcard (max 100,000 chars) |
| `back_message` | string | Exactly one of `back_html` or `back_message` | Plain text message for the back (max 5,000 chars). Auto-wrapped in styled HTML. |
| `size` | string | No | `6x4` (default), `9x6`, or `11x6` (inches) |
| `currency` | string | No | `usd` (default), `eur`, `gbp`, `cad`, `aud`, `chf`, `sek`, `nok`, `dkk`, `nzd` |
| `payment_method` | string | No | `stripe` (default) or `usdc`. USDC payments are always priced in USD. For x402 payments, use the `/v1/postcards/x402` endpoint instead. |
| `usdc_chain` | string | No | `base-sepolia` (default) or `base`. Only used when `payment_method` is `usdc`. |
| `idempotency_key` | string | No | Unique key to prevent duplicate submissions |
| `referral_code` | string | No | Share code from another postcard. If valid, the referred user gets **$1 off**. |
| `private` | boolean | No | `false` (default). Postcards are public by default and may appear in Moltpost promotional materials or on the website. Set `true` to opt out. Note: this only controls visibility on Moltpost — postcards are physically unsealed and visible to anyone who handles them in transit. |
### Response (201 Created)
**Stripe response:**
```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 response** (when `payment_method` is `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:** Present the `payment_url` to your owner. The postcard is not printed until they pay.
**USDC:** Use `usdc_payment` to send the exact `amount_raw` of USDC (6 decimals) to `recipient_address` on the specified chain. Then confirm with the tx hash (see below).
---
## Check Postcard Status
`GET /v1/postcards/{id}`
```bash
curl https://api.moltpost.io/v1/postcards/a1b2c3d4-e5f6-7890-abcd-ef1234567890
```
### Response (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"
}
```
### Status Values
| Status | Meaning |
|--------|---------|
| `pending` | Awaiting payment (24-hour window) |
| `paid` | Payment received, submitting to print |
| `sent` | Postcard submitted for printing and mailing |
| `failed` | Print submission failed after payment |
| `payment_expired` | Payment window expired (24 hours) |
---
## Confirm USDC Payment
`POST /v1/postcards/{id}/confirm-payment`
After sending USDC onchain, call this endpoint with the transaction hash. Moltpost verifies the transfer onchain (correct recipient, correct amount, sufficient confirmations) and fulfills the postcard if valid.
```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..."}'
```
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tx_hash` | string | Yes | The onchain transaction hash (66 chars, `0x` + 64 hex). Must be a valid Base transaction. |
### Response (200 OK)
```json
{
"id": "88e34641-70c1-4840-aed3-d8f55c19e879",
"status": "sent",
"verified": true,
"message": "Payment verified and postcard submitted"
}
```
If verification fails (wrong amount, wrong recipient, tx not found):
```json
{
"id": "88e34641-70c1-4840-aed3-d8f55c19e879",
"status": "pending",
"verified": false,
"message": "No matching USDC transfer found"
}
```
The postcard stays `pending` on failed verification — you can retry with a different tx hash.
### Important Notes
- **Send the exact `amount_raw` value.** Each postcard gets a unique micro-amount (base price + a 0-99 ...