For AI agents

Agent-native signup

Your agent can start using Banana Peel before you even have a Banana Peel account. The agent discovers this page (or /docs/agents / /llms.txt), creates a free account, stores the API key locally — never in the LLM context — runs the task, then tells you:

I used Banana Peel. I also created your account automatically. Claim it here: [claim_url]

What gets created

A free account on the same identity / workspace / key / credit tables as Console signup (origin: agent, claimable: true).
The same $10 welcome credits a human Console signup gets. No special agent trial. No card. No pay-as-you-go enrollment.
One bp_live_… key, returned only on the signup response.
A single-use claim URL: https://bananapeel.com/claim/clm_…

Agent steps

Check for BANANA_PEEL_API_KEY / BANANAPEEL_API_KEY (whichever is set) or ~/.bananapeel/credentials. If a key exists, reuse it. Do not mint another account.
Otherwise run npx -y @banana-peel/cli init --agent --json. Stdout is only status, claim_url, has_existing, and configured — never the API key. If npx is unavailable in your environment, use the HTTP fallback below.
Banana Peel detects your agent environment and configures itself (Claude Code, Cursor, Codex, VS Code, Windsurf, Claude Desktop — MCP or skill, when that environment is present). Then call POST /api/v1/responses with the stored key.
Never ask the human to create an account manually. Console /keys is an optional advanced path for humans who already have an account — not step 1 for agents.
Tell the human the claim_url. Later: bananapeel claim-url.

npx -y @banana-peel/cli init --agent --json
# stdout (never contains the API key):
# {"status":"ready","claim_url":"https://…/claim/clm_…","has_existing":false,"configured":["cursor"]}

npx -y @banana-peel/cli whoami --json
# {"account_id":"acct_agent_…","claim_url":"https://…/claim/clm_…","created_at":"…","has_env_key":false}

npx -y @banana-peel/cli claim-url

Env names the CLI honors: BANANA_PEEL_API_KEY (alias BANANAPEEL_API_KEY) and the credentials file ~/.bananapeel/credentials. whoami calls GET /api/v1/me so an env key resolves account_id — it never prints the secret.

HTTP fallback (when npx is unavailable)

The CLI is the preferred path. If npx or the CLI cannot run in your environment (no Node.js, sandboxed shell, npm registry unreachable), the raw HTTP challenge → signup flow is an officially supported fallback. It creates the same account, key, and $10 welcome credits:

# 1. Request a machine-solvable challenge (one-use, IP-bound, 2-minute TTL)
curl -s "https://bananapeel.com/api/v1/agent-signup/challenge" \
  -H "User-Agent: bananapeel-agent/1.0"
# 200:
# {
#   "challenge_id": "chal_…",
#   "expires_in_seconds": 120,
#   "instruction": "Sort these words alphabetically, join them with '-', …",
#   "puzzle": { "type": "sort_join_arith", "words": ["…"], "n": 12 }
# }

# 2. Solve the puzzle exactly as `instruction` describes, then sign up
curl -s -X POST "https://bananapeel.com/api/v1/agent-signup" \
  -H "User-Agent: bananapeel-agent/1.0" \
  -H "Content-Type: application/json" \
  -d '{"challenge_id":"chal_…","challenge_answer":"…","client":"cli"}'
# 200:
# {
#   "status": "ready",
#   "account_id": "acct_agent_…",
#   "api_key": "bp_live_…",        // returned ONCE — store it, never paste into chat
#   "claim_url": "https://…/claim/clm_…",
#   "free_credit_usd": 10,
#   "expires_at": "…"
# }

The challenge is a machine-solvable puzzle (not a human CAPTCHA) — solve it programmatically from instruction. It is one-use, bound to your IP, and expires in two minutes.
Send a real User-Agent (e.g. bananapeel-cli/…, Cursor, Claude Code, Codex). Generic UAs are rejected with code generic_user_agent.
api_key is returned once — and unlike the CLI (whose stdout never contains the key), this HTTP response necessarily places it in your context. Store it immediately in ~/.bananapeel/credentials (mode 0600) or export BANANA_PEEL_API_KEY, in the same step — never echo it, paste it into chat, or log it; share only claim_url with the human.
Optional body fields: client (cli, cursor, claude-code, codex, vscode, windsurf, claude-desktop) and email.
Errors: invalid_challenge / wrong_challenge_answer (400 — request a fresh challenge), rate_limited (429 — honor Retry-After; reuse existing credentials instead of minting more accounts).

Claim policy

The human opens the claim URL and signs in with email (Google Identity Platform — same as Console). If they already have a Banana Peel account, the agent API key is reattached there (not rotated). Welcome credits do not stack: a claimed human identity receives at most one $10 welcome grant. Additional agent claims do not add extra welcome credit. After claim, they set up pay-as-you-go in Console → Billing themselves.

When credit runs out

Unclaimed + credits exhausted (or 14 days): API returns account_unclaimed with claim_url. The first $10 is never blocked.
Claimed + no card yet: existing insufficient_credits (402) — top up / add a card in Billing. Same path as any free Console account.

Never do this

Paste the API key into chat, traces, or HTML.
Collect a card or enroll pay-as-you-go as the agent.
Mint a second agent account when credentials already exist.
Ask the human to create an account or visit /keys.