# GetOTP - AI Agent & Machine-to-Machine Integration Guide

Welcome to GetOTP's developer documentation designed specifically for autonomous AI Agents, crawlers, and automated workflows.

## 1. Quick Overview
- **Base URL:** `https://getotp.ccwu.cc`
- **Supported Auth:** `Bearer {jwt}` or lightweight `16-character address password`
- **Machine Payment Protocol:** Native HTTP 402 / Card Code Redemption / x402 Header

---

## 2. API Endpoints for AI Agents

### 2.1 Instant Mailbox Creation (Free & VIP)
- **POST** `/api/new_address`
- **Headers:** `Content-Type: application/json`
- **Body:**
```json
{
  "name": "agent_worker_01",
  "domain": "getotp.ccwu.cc"
}
```
- **Response (200 OK):**
```json
{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "address": "tmpagent_worker_01@getotp.ccwu.cc",
  "password": "s9cdclgvygxua6ju"
}
```
- *Note:* The `password` is an ultra-secure 16-character high-entropy secret. Keep it to quickly re-access this inbox later without bulky tokens!

---

### 2.2 Short Link for Quick Resumption
AI agents can construct human-friendly access links for their supervisors:
```
https://getotp.ccwu.cc/?m={address}&p={password}
```
When clicked, the web dashboard automatically verifies the credentials and opens the inbox silently.

---

### 2.3 Fetch Emails & Extract Verification Codes
- **GET** `/api/mails?limit=20&offset=0`
- **Headers:** `Authorization: Bearer {jwt}`
- **Response (200 OK):**
```json
{
  "results": [
    {
      "id": 1042,
      "source": "noreply@openai.com",
      "address": "tmpagent_worker_01@getotp.ccwu.cc",
      "subject": "Your verification code is 829143",
      "text": "Use code 829143 to complete your verification.",
      "created_at": "2026-10-03T18:30:00Z"
    }
  ],
  "count": 1
}
```

---

### 2.4 Programmatic VIP Upgrade & Billing (Machine-to-Machine)
AI Agents requiring clean `.COM` domains (`tokenflowpay.com`, `bitfusionpay.com`) or high-trust domains (`bitbox.ccwu.cc`) can programmatically apply redemption vouchers.

- **POST** `/redeem_api/redeem`
- **Headers:** `Content-Type: application/json`
- **Body:**
```json
{
  "code": "YOUR_REDEEM_CODE",
  "user_email": "optional_account_email"
}
```
- **Response (200 OK):**
```json
{
  "success": true,
  "type": "role",
  "role": "vip"
}
```
Upon redemption, the account instantly unlocks VIP exclusive domain pools without human intervention.