# DimeBox

> Give an AI agent a real email identity — draft, send, and receive — priced in cents. Pay per call over x402 (HTTP 402, USDC on Base) with no wallet setup needed, or fund a card-based credit wallet for agents that don't hold crypto. No accounts or API keys either way.

DimeBox's paid endpoints are gated by x402's `exact` scheme by default. Call any paid endpoint unpaid to get back a `402` with a `PAYMENT-REQUIRED` header describing the price, network, and asset; sign a payment and retry with a `PAYMENT-SIGNATURE` header. The same routes also accept `Authorization: Bearer <wallet_secret>` instead — see "Wallets" below - in which case that header alone settles it and x402 is skipped entirely for that call.

## Paying with x402 (for an agent holding its own crypto wallet)

The signature is an EIP-3009 `transferWithAuthorization` (USDC's native gasless-transfer permission), verified and broadcast by a facilitator - don't hand-construct it. Use an existing x402 client library, which handles the whole 402 → sign → retry flow automatically:

- JS/TS: `npm install @x402/fetch @x402/evm viem`
- Python: `pip install x402`

Minimal JS example:

```js
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY); // 0x-prefixed hex
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }], // Base mainnet
});

const res = await fetchWithPayment("https://dimebox.app/api/emails/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ recipient: "jane@example.com", purpose: "follow up" }),
});
```

The wallet only needs a USDC balance on Base (`eip155:8453`) - no ETH, no gas: the signature just authorizes a transfer, and DimeBox's facilitator broadcasts it and pays gas itself. Full protocol spec: https://x402.org

## Docs

- Full API reference (every endpoint, price, request/response shape, status codes, buyer quickstart): https://dimebox.app/docs
- Machine-readable spec: https://dimebox.app/openapi.json
- Live, authoritative price/network/asset per route (source of truth over anything cached): https://dimebox.app/api/discovery/resources
- Wallet dashboard (create/fund/manage a card-based credit wallet): https://dimebox.app/wallet

## Endpoints

- POST /api/emails/generate — draft an email from a brief ($0.02, paid)
- POST /api/inboxes — provision an inbox with a random address (free, IP-throttled)
- POST /api/inboxes/claim — provision an inbox with a chosen address ($1.00, paid)
- POST /api/inboxes/{slug}/send — send from an inbox, drafted or raw ($0.01, paid)
- POST /api/inboxes/{slug}/messages — priority delivery to an inbox ($0.03, paid)
- GET /api/inboxes/{slug}/messages — read a mailbox's history (free, requires X-Inbox-Token header)
- GET /api/inboxes/{slug}/messages/{message_id} — read one message's full details by its UUID (free, requires X-Inbox-Token header)

All paid POST endpoints require `Content-Type: application/json` — a form-encoded body silently fails to parse and returns a free `415` before any payment challenge.

## Wallets (card-funded, no crypto needed)

An alternative to signing an x402 payment per call: fund a wallet by card once, then pay for the same routes above with `Authorization: Bearer <wallet_secret>` instead of a `PAYMENT-SIGNATURE` header. Closed-loop credit only — spendable exclusively on DimeBox's own paid routes, never withdrawable, cashable, or transferable to another wallet or system.

- POST /api/wallets — start wallet creation (Stripe Checkout; a one-off top-up or a recurring monthly plan)
- GET /api/wallets/checkout/{checkout_session_id} — reveal the new wallet's id + secret exactly once, right after checkout
- GET /api/wallets/{id} — balance + recent ledger, requires the wallet secret
- POST /api/wallets/{id}/recharge — top up; charges a saved card automatically if there is one, otherwise returns a checkout link
- PATCH /api/wallets/{id}/settings — set a persistent daily spend limit, and turn auto-reload on/off
- POST /api/wallets/{id}/subscription — attach a recurring monthly plan to a wallet that already exists
- POST /api/wallets/{id}/subscription/cancel — cancel it; the wallet's existing balance stays untouched and spendable

Dashboard for all of the above without hand-rolling requests: https://dimebox.app/wallet

## Contact

hello@dimebox.app