# AgentPay API Reference (for AI assistants)
# Base URL: https://api.agentpay.la
# Auth: Bearer token in Authorization header (agentpay_sk_live_...)
#
# Card lifecycle: create -> active -> used -> closed
# Billing: authorize-capture. Hold placed on create, capture on close. Unused funds released.
#
# Endpoints:
# POST /v1/auth/agent-signup {email, agent_type} -> {api_key, cardholder_id}
# POST /v1/cards {amount, currency, merchant_lock?, guard?, context?} -> {id, status, amount}
# GET /v1/cards/{id} -> {id, status, amount, balance}
# GET /v1/cards/{id}/details -> {pan, cvv, expiry_month, expiry_year}
# DELETE /v1/cards/{id} -> {id, status, released_balance}
# GET /v1/transactions?card_id=...&limit=50 -> {transactions: [...]}
# POST /v1/api-keys {name} -> {api_key, key_prefix}
# GET /v1/api-keys -> [{id, key_prefix, name, created_at}]
# DELETE /v1/api-keys/{id} -> {message}
# GET /v1/account/status -> {has_payment_method, can_create_cards}
#
# Guard mode: guard=true -> 15-min auto-expiry, velocity limited (5 per 10 min)
# Merchant lock: merchant_lock="vercel.com" -> card only works at that merchant
# Approval: cards require human approval by default. Set auto-approve rules via /v1/approval-rules
#
# Errors: 400 (validation), 401 (auth), 402 (no payment method), 403 (tier limit), 429 (rate limit)
#
# Python: pip install agentpay
# from agentpay import AgentPay
# client = AgentPay(api_key="...")
# card = client.cards.create(amount=25.0, currency="usd")
# details = client.cards.details(card.id)
# client.cards.close(card.id)
#
# MCP (remote, recommended): claude mcp add --transport http agentpay https://api.agentpay.la/mcp --header "Authorization:Bearer KEY"
# MCP (local): npx agentpay-mcp-server (tools: create_card, get_card_details, close_card, check_balance, etc.)
