# ClawCall API

AI-powered phone calls via the x402 payment protocol. Two modes: outbound (call a number) and inbound (reserve a number that answers calls with your AI).

Base URL: `https://www.clawcall.xyz`

## Authentication

Payment endpoints require x402. The server responds with `HTTP 402` containing payment requirements. Include a signed `X-PAYMENT` header to proceed.

- **Network**: Base mainnet (USDC)
- **Facilitator**: OpenX402
- **Discovery**: `npx awal@latest x402 bazaar search "phone call"`

---

## Outbound Calls ($0.25)

Make an AI-powered call to any US phone number.

### POST /api/call

**Request:**

```json
{
  "phoneNumber": "+15551234567",
  "prompt": "What are your business hours today?"
}
```

| Field       | Type   | Required | Description                                |
|-------------|--------|----------|--------------------------------------------|
| phoneNumber | string | yes      | E.164 format (e.g. +15551234567)           |
| prompt      | string | yes      | Instructions for the AI (1-2000 chars)     |

**Response (202):**

```json
{
  "callId": "uuid",
  "status": "initiating",
  "pollUrl": "/api/call/{uuid}"
}
```

### GET /api/call/:id

Poll for call result. No payment required.

```json
{
  "callId": "uuid",
  "status": "completed",
  "transcript": "assistant: Hi, what are your hours?\nuser: We're open 9 to 5.",
  "duration": 45
}
```

**Statuses:** `initiating` -> `ringing` -> `in_progress` -> `completed` | `failed` | `timeout`

### Outbound Flow

1. `POST /api/call` with phone number and prompt
2. Receive `402` with x402 payment requirements
3. Re-send with signed `X-PAYMENT` header (USDC on Base)
4. Receive `202` with `callId` and `pollUrl`
5. Poll `GET /api/call/:id` every 3-5 seconds
6. When status is `completed`, read `transcript`

---

## Inbound Calls ($1.00)

Reserve a phone number for 30 minutes. Incoming calls are answered by an AI assistant using your prompt.

### POST /api/inbound/reserve

**Request:**

```json
{
  "prompt": "You are a pizza shop called Mario's. Our hours are 11am-10pm daily. We have cheese, pepperoni, and veggie pizzas."
}
```

| Field  | Type   | Required | Description                                      |
|--------|--------|----------|--------------------------------------------------|
| prompt | string | yes      | Instructions for the AI assistant (1-2000 chars) |

**Response (201):**

```json
{
  "reservationId": "uuid",
  "phoneNumber": "+15551234567",
  "expiresAt": "2025-01-01T00:30:00.000Z",
  "durationMinutes": 30,
  "statusUrl": "/api/inbound/{uuid}"
}
```

### GET /api/inbound/:id

Get reservation status and call history. No payment required.

```json
{
  "reservationId": "uuid",
  "phoneNumber": "+15551234567",
  "prompt": "You are a pizza shop...",
  "status": "active",
  "expiresAt": "2025-01-01T00:30:00.000Z",
  "calls": [
    {
      "callId": "uuid",
      "status": "completed",
      "duration": 30,
      "transcript": "assistant: Hello, thank you for calling...\nuser: What are your hours?",
      "callerNumber": "+15559876543",
      "createdAt": "2025-01-01T00:05:00.000Z"
    }
  ]
}
```

**Reservation statuses:** `active` | `expired` | `released`

### POST /api/inbound/:id/release

Release a reservation early. No payment required. Returns the phone number to the pool.

### Inbound Flow

1. `POST /api/inbound/reserve` with prompt
2. Receive `402` with x402 payment requirements
3. Re-send with signed `X-PAYMENT` header (USDC on Base)
4. Receive `201` with `phoneNumber` and `expiresAt`
5. Call the phone number -- AI answers with your prompt
6. Poll `GET /api/inbound/:id` for call history and transcripts
7. Optionally `POST /api/inbound/:id/release` to release early

---

## Utility

### GET /api/health

```json
{ "status": "ok", "service": "clawcall" }
```

## Error Responses

| Status | Meaning                          |
|--------|----------------------------------|
| 400    | Invalid request body             |
| 402    | Payment required (x402)          |
| 404    | Not found                        |
| 409    | Reservation already released     |
| 422    | Prompt rejected by validation    |
| 503    | No numbers available             |
| 500    | Internal server error            |