Registering a bot

POST /api/bots/register — public, no authentication, rate-limited per IP (20/hour, 50/day).

{
  "platform": "openclaw",
  "display_name": "my-bot",
  "requested_scopes": ["mail:read", "calendar:read", "billing:read", "billing:write"],
  "handle_preference": "my-bot",
  "spend_cap_credits": 200000,
  "owner_contact": "optional@human.tld"
}

A 201 returns:

• account — email (a collision-safe handle on @bots.tamaton.ai), status: "inert", account_type: "bot".
• apiKey — key_id plus the secret, shown exactly once. Authenticate every call with Authorization: Bearer <key_id>:<secret>.
• funding_options — the rails currently available (card top-up, subscription, x402 when enabled) with their URLs.

⚠️ Treat the key as a secret. <key_id>:<secret> is a full credential granting mail, storage, calendar, and billing access. Store it in an environment variable or secrets manager — never commit it or paste it into a URL (query strings leak into logs, shell history, and telemetry). Keep spend_cap_credits set and rotate the key if you suspect it was exposed.

Scopes

Use least privilege. Scopes follow feature:operation (e.g. mail:read, mail:send, billing:write). Omitting requested_scopes grants a conservative read-only default. Include billing:read/billing:write if the bot manages its own funding.

Spend caps

spend_cap_credits bounds the key's lifetime spend — a leaked key can never spend past its cap. Strongly recommended for autonomous bots.

Choosing a handle

handle_preference lets you request the local-part of your mailbox on @bots.tamaton.ai (e.g. "my-bot" → my-bot@bots.tamaton.ai). It is best-effort, not a guarantee:

• It is lowercased and stripped to [a-z0-9._-]; leading/trailing separators are trimmed and it is clamped to 32 chars. If fewer than 3 usable characters remain, it falls back to bot.
• The domain is always @bots.tamaton.ai — you cannot choose it.
• If the handle is already taken, a short random suffix is appended (e.g. my-bot-3f9a2c).
• Omit the field (or send "auto") to get a fully generated handle.

The address returned in account.email is permanent — there is currently no way to change a bot's email after registration, so pick the handle you want up front.

Inert until funded

The key authenticates immediately, but every metered endpoint answers HTTP 402 until the account's first credit lands. Never-funded accounts are deleted after ~14 days.