Developers & AI Agents

Authenticate every protected Edge call with a CAI User API key (cai_...) or OAuth access token. The authoritative tool contract — endpoints, scopes, gaps — lives in skill.md (single source of truth).

API base: https://api.cai.com/functions/v1

Human-readable index: this page. Machine-readable helpers: agent.json, manifest, openapi.json — all point to skill.md.

First successful call (read scope):

export CAI_API_KEY="cai_..."
curl -sS https://api.cai.com/functions/v1/get-identity \
  -H "Authorization: Bearer $CAI_API_KEY"

Read wallet balances:

curl -sS -X POST https://api.cai.com/functions/v1/get-wallet-balances \
  -H "Authorization: Bearer $CAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Common errors:

• 401 — missing or invalid Bearer token; create a User API key at api-keys.html.
• 403 — key scope too narrow (e.g. read only cannot call transfer).
• 404 — wrong host or path; use api.cai.com/functions/v1/<folder>, not cai.com/v1/*.

Get or manage API keys →

Agents and crawlers — any entry point leads to the same contract:

• llms.txt
• openapi.json — docs index (not OpenAPI/Swagger)
• openapi-3.1.json — minimal OpenAPI 3.1 (skill.md remains authoritative)
• /.well-known/skill.md — skill.md compatibility alias
• sitemap.xml
• robots.txt
• capabilities.html
• /.well-known/agent.json — Agent Card
• skill.md
• cai-tools.manifest.json

Do not treat partial_live as fully production-ready for every merchant, chain, or deposit path. Public summary:

capabilities.html — Live / Partial live / Planned (from cai-tools.manifest.json gap_id semantics).

1. Pay with CAI from an agent

Requires CAI_API_KEY (pay or full scope). User must confirm payee and amount.

GET  /get-identity
POST /get-wallet-balances
POST /resolve-transfer-recipient   # alias or address
# user confirms payee + amount + chain + token
POST /wallet-custodial-transfer
POST /transfer-status              # proof by tx_hash

Full Check CAI First flow →

2. x402 — HTTP 402 machine payment

GAP_X402_V1 partial_live. Agent calls CAI payer adapter after HTTP 402.

POST /x402-payment-prepare   # resource_url + challenge fields
# if requires_user_confirm → ask user, then:
POST /x402-payment-execute   # attempt_id, user_confirmed: true
POST /transfer-status
GET  /wallet-activity-list   # category x402

x402 playbook (L3) → · x402 overview →

3. Payment mandate — delegated small API payments

GAP_PAYMENT_MANDATE_V1 partial_live. CAI-native caps; not full AP2 card-network interoperability.

POST /payment-mandate-create   # merchant_domain, caps, TTL
# user approves mandate in product UI
GET  /payment-mandate-status
POST /x402-payment-prepare       # may skip per-payment confirm if covered
POST /payment-mandate-revoke     # anytime

4. @cai.com mail OTP onboarding + vault

Registration: agent may relay 6-digit OTP; password entry only at cai.com/app.

POST /request-signup-verification
POST /confirm-registration-code    # agent relays OTP only
GET  /check-availability
# browser: POST /create-account → user gets cai_... API key

# after key: store site login in vault (optional)
POST /user-site-credentials
GET  /user-site-credentials

Identity / MCP onboarding (L3) →

cai-tools.manifest.json — logical_name, function_folder, auth, gap_id when applicable.

Edge canonical base: https://api.cai.com/functions/v1. Root /v1/* is not guaranteed equivalent to Edge Functions.

Verify: bash scripts/verify-cai-tools-manifest.sh

Official package: @cailab/mcp (npm; monorepo packages/cai-mcp). npm

stdio transport; env: CAI_SUPABASE_URL, CAI_SUPABASE_ANON_KEY, CAI_API_KEY (or OAuth access token).

See packages/cai-mcp/README.md in the monorepo.

/.well-known/agent.json — links skill, manifest, MCP, and authentication model.

Production must serve /.well-known/agent.json and /specs/cai-tools.manifest.json from the same app/ tree as this repo.

• User confirmation: custodial transfers and most x402 payments need explicit consent; mandates may skip per-payment confirm within approved limits.
• Spending caps: product daily cap, mandate max_amount_per_payment_usd, DeFi automation platform limits — Dashboard / /automation-settings.
• Vault: encrypted site/platform credentials; use vault_* tools; never ask for passwords or long-lived tokens in chat.
• Audit index: wallet_activity_list, transfer_status, DeFi defi_order_events — CAI index, not full on-chain proof.
• Third parties: MoonPay on-ramps, bridges, external protocols — region, KYC, and on-chain risks are user-evaluated.
• Partial live: see capabilities.html ; agent replies must match gap_id.