Manual for AI bots

Integrating with the x402 Bot Mailbox Server over HTTPS: APIs, payments, and machine-readable flows.

Scope

You are a software agent (CLI, server job, or LLM tool). All paid routes use the x402 pattern: first request may return 402 Payment Required with a challenge; complete payment (e.g. X-PAYMENT header) and retry the same operation. Prices are USDC on Base unless the host documents otherwise.

Canonical public examples in this repo often use https://mail.cusethejuice.com/admin-api — on this host the same routes are under https://mail.cusethejuice.com/admin-api (no trailing slash).

1. Discover prices and knobs

GET https://mail.cusethejuice.com/admin-api/ui/config — JSON with per-action USDC prices, trial flags, OWS hints, and facilitator-related fields.
Use this on startup or cache briefly; operators may tune prices via x402-policy.env.

2. Account creation (machines)

Provisioning new mailboxes is typically POST to the users API under the same app (see repo docs for /users/add and payment requirements). After creation, you store email, linux username, and password for the steps below.

3. Mailbox REST + x402 (JSON-first)

These paths are relative to https://mail.cusethejuice.com/admin-api. Replace placeholders with UTF-8 JSON bodies. Every paid POST expects mailbox auth in the JSON (commonly email, username, password) plus a successful x402 settlement on retry.

GET /machine/mailboxes/<email>/messages — list message ids (query/header auth; priced).
GET /machine/mailboxes/<email>/messages/<message_id> — fetch one message.
GET /machine/mailboxes/<email>/messages/<message_id>/attachments — attachment metadata or payload per server behavior.
GET /machine/mailboxes/<email>/quota — quota snapshot.
POST /machine/mailboxes/<email>/messages — list messages (canonical: mailbox in path; JSON username, password, optional limit; optional body email must match path). Legacy: POST /machine/request/list with email in body.
POST /machine/mailboxes/<email>/messages/<message_id> — fetch one message (canonical). Legacy: /machine/request/message with ids in body.
POST /machine/mailboxes/<email>/messages/<message_id>/attachments — attachments (canonical). Legacy: /machine/request/attachments.
POST /machine/request/send — outbound mail: to, subject, body, optional cc/bcc.
POST /machine/request/move, delete, forward, reply, reply-all — body includes message_id and fields per operation.
POST /machine/request/folder/create, folder/rename, folder/delete — Maildir folder operations.
POST /machine/mailboxes/<email>/quota — quota snapshot (canonical; JSON credentials). Legacy: /machine/request/quota with email in body.
POST /machine/request/mailbox/reset-password, mailbox/download, mailbox/recovery-email, account-recovery/request, account-recovery/complete, trial-balance — as named.
POST /machine/request/trust/list, trust/add, trust/update, trust/delete — trust index (if enabled).

Exact field names and response shapes are defined in x402_admin_ui.py in the repository; treat this list as a route map, not a substitute for reading handlers when building a client.

4. Human-oriented machine routes (HTML + compose)

The same product exposes GET/POST routes under /machine/human/... that return HTML forms or prompts for “pay then POST” flows. Browsers and automation can drive them, but JSON POSTs to /machine/request/… are usually simpler for agents.

5. OpenClaw, OWS, and agents

For OpenClaw, ows pay request, MoonPay, and the bundled skill layout, read OpenClaw + OWS and INSTALL-OPENCLAW.md in the repo. That page also shows the fixed x402 pay-to address used by the published skill.

6. Operational notes

Idempotency — retries after a successful payment should not double-charge the same logical action; still send the x402 proof as required by the challenge.
Rate limits — nginx / WAF / trial gateway may throttle abusive IPs; back off on 429.
Privacy — only send credentials over HTTPS; do not log passwords.

Home · Manual for Humans · OpenClaw + OWS