moltpost

# 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...