# Bott Pay - API Documentation for LLMs

Bott Pay is an API-first payment system for AI agents built on Cloudflare Workers. It enables agent-to-agent payments using USDC on the Base network (Ethereum L2).

**Base URL:** https://pay.bo.tt
**Network:** Base L2 (Ethereum Layer 2)
**Currency:** USDC (USD Coin)
**Version:** 0.3.0

---

## Overview

Bott Pay provides:
- Agent registration with automatic wallet creation via Coinbase Developer Platform (CDP)
- Payment request creation and management
- Public agent profiles
- Shareable payment request links
- Multi-domain routing (bo.tt and pay.bo.tt)

---

## Public Pages

| Route | Method | Description |
|-------|--------|-------------|
| `/` | GET | Landing page (domain-aware: bo.tt shows cryptic page, pay.bo.tt shows payment-focused page) |
| `/health` | GET | Health check endpoint (returns JSON status) |
| `/skill.md` | GET | Agent instructions (markdown) |
| `/llms.txt` | GET | This file (markdown) |
| `/fund`, `/funding`, `/docs/funding` | GET | Funding guide page (HTML) |
| `/fund/:address` | GET | Fund specific wallet page (HTML, address must be 0x + 40 hex chars) |
| `/r/:id` | GET | Payment request page (HTML, shows payment details) |
| `/u/:name` | GET | Agent profile page (HTML, shows wallet address for direct payments) |
| `/waitlist` | POST | Waitlist signup (JSON) |

---

## API Endpoints

### Base URL
All API endpoints are prefixed with `/v1/`

### Authentication
Most endpoints require authentication via Bearer token:
```
Authorization: Bearer bpay_{uuid}
```

API keys are only returned once during agent registration. They are SHA-256 hashed before storage.

---

### Agent Registry

#### POST /v1/agents/register
Register a new agent. Automatically creates a CDP wallet on Base network.

**Request:**
```json
{
  "name": "agent_name",
  "webhook_url": "https://example.com/webhook" // optional
}
```

**Response (201):**
```json
{
  "agent_id": "uuid",
  "wallet_address": "0x...",
  "api_key": "bpay_...",
  "profile_url": "https://pay.bo.tt/u/agent_name"
}
```

**Rate Limit:** 3 registrations per IP per hour

**Validation:**
- Name: alphanumeric, hyphens, underscores only
- Webhook URL: must be valid HTTP(S) URL

---

#### GET /v1/agents/me
Get authenticated agent's profile. Requires Bearer token.

**Response (200):**
```json
{
  "id": "uuid",
  "name": "agent_name",
  "wallet_address": "0x...",
  "webhook_url": "https://...",
  "created_at": "ISO8601"
}
```

---

#### GET /v1/agents/:id
Public agent lookup by ID. No authentication required.

**Response (200):**
```json
{
  "name": "agent_name",
  "wallet_address": "0x..."
}
```

---

### Payment Requests

#### POST /v1/requests
Create a payment request. Requires Bearer token.

**Request:**
```json
{
  "amount": "10.00",
  "currency": "USDC", // optional, defaults to USDC
  "description": "Payment for service", // optional
  "pay_to": "0x..." // wallet address
}
```

**Response (201):**
```json
{
  "request_id": "uuid",
  "pay_url": "https://pay.bo.tt/r/{id}"
}
```

**Validation:**
- Amount: positive decimal number
- Currency: uppercase (USDC, etc.)
- Description: max 500 chars
- Pay to: valid Ethereum address (0x + 40 hex chars)

**Expiry:** Payment requests expire after 24 hours, KV entries expire after 7 days.

---

#### GET /v1/requests/:id
Get payment request status. Requires Bearer token.

**Response (200):**
```json
{
  "status": "pending" | "paid" | "expired",
  "amount": "10.00",
  "currency": "USDC",
  "description": "...",
  "pay_to": "0x...",
  "tx_hash": "0x..." // only if status is "paid"
}
```

---

### Legacy Endpoints (Backwards Compatibility)

#### POST /v1/payments
Legacy payment creation endpoint.

**Request:**
```json
{
  "from_agent": "agent_id",
  "to_agent": "agent_id",
  "amount": "10.00",
  "currency": "USDC",
  "memo": "..." // optional
}
```

---

#### GET /v1/payments/:id
Legacy payment lookup endpoint.

---

## Data Structures

### Agent
```typescript
{
  id: string; // UUID
  name: string; // alphanumeric, hyphens, underscores
  wallet_address: string; // Ethereum address (0x + 40 hex)
  webhook_url?: string; // optional HTTP(S) URL
  api_key_hash: string; // SHA-256 hash (not returned in API)
  created_at: string; // ISO8601 timestamp
}
```

### PaymentRequest
```typescript
{
  id: string; // UUID
  amount: string; // decimal number as string
  currency: string; // uppercase (e.g., "USDC")
  description?: string; // optional, max 500 chars
  pay_to: string; // Ethereum address
  status: "pending" | "paid" | "expired";
  tx_hash?: string; // only if paid
  created_at: string; // ISO8601
  expires_at: string; // ISO8601 (24h from creation)
}
```

---

## Domain Routing

- **bo.tt** / **www.bo.tt**: Shows cryptic landing page
- **pay.bo.tt**: Shows payment-focused landing page
- **workers.dev subdomain**: Shows payment-focused landing page

Domain detection uses `request.url.hostname`. In development, `?domain=bo.tt` or `?domain=pay.bo.tt` query param can override.

---

## Storage

- **KV Namespaces:**
  - `PAYMENT_REQUESTS`: Payment request data (key = request ID)
  - `AGENTS`: Agent registry with three key patterns:
    - `agent:{agentId}`: Full agent data
    - `hash:{apiKeyHash}`: Agent ID lookup (for auth)
    - `name:{lowercaseName}`: Agent ID lookup (for profiles)
  - `WAITLIST`: Waitlist signups

- **KV Characteristics:**
  - Eventually consistent (may take a few seconds)
  - String keys and values (JSON.stringify/parse required)
  - Case-sensitive keys

---

## CORS

All API endpoints include CORS headers:
```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
```

---

## Error Responses

All errors follow this format:
```json
{
  "error": "Error message",
  "details": "..." // optional, only in development
}
```

**Common Status Codes:**
- `200`: Success
- `201`: Created
- `400`: Bad Request (validation error)
- `401`: Unauthorized (missing/invalid API key)
- `404`: Not Found
- `429`: Too Many Requests (rate limited)
- `500`: Internal Server Error

---

## Environment

- **Runtime:** Cloudflare Workers (edge computing)
- **Language:** TypeScript 5.9+ (ES2021)
- **Storage:** Cloudflare KV
- **Crypto:** Coinbase Developer Platform (CDP) for wallet management
- **Blockchain:** Base network (Ethereum L2)
- **Currency:** USDC

---

## Notes

- API keys are only returned once during registration. Store securely.
- Each agent automatically receives a CDP wallet on Base network.
- Payment requests expire after 24 hours.
- KV entries expire after 7 days for payment requests.
- All crypto operations use Web Crypto API (available in Workers runtime).
- Rate limiting: 3 registrations per IP per hour.