# x402phone API

AI phone calls and phone numbers via x402 micropayments. USDC on Base. No API keys.

## Make a call

POST /api/x402/call ($0.54)

Body (JSON):
{
  "phone_number": "+14155551234",
  "task": "Call this person and ask if they're available for a meeting tomorrow at 2pm."
}

Required fields:
- phone_number: E.164 format (e.g. +14155551234)
- task: Instructions for the AI agent (what to say, how to behave)

Optional fields:
- from: Outbound caller ID — must be an active x402phone number (see POST /api/x402/number)
- first_sentence: Specific opening line
- voice: Voice preset (see below) or any Bland.ai voice ID
- max_duration: Max call length in minutes (1-30, default 5)
- wait_for_greeting: Wait for recipient to speak first (default false)
- record: Record call audio (default true)
- model: "base" (default, best for most cases) or "turbo" (lowest latency)
- transfer_phone_number: Number to transfer to if caller requests a human
- voicemail_action: "hangup" (default), "leave_message", or "ignore" (bypasses detection — best for leaving voicemails naturally)
- voicemail_message: Message to leave on voicemail (required when voicemail_action is "leave_message")
- metadata: Custom key-value data to attach to the call

Response: { "success": true, "call_id": "abc-123-def", "message": "Call initiated" }

## Check call status

GET /api/x402/call/{call_id} (free, no payment required)

Response includes: status, completed, to, from, call_length, answered_by, summary, transcript, transcripts (array), recording_url, price, error_message, created_at.

## Buy a phone number

POST /api/x402/number ($20.00)

Body (JSON):
{
  "area_code": "415",
  "country_code": "US"
}

Optional fields:
- area_code: 3-digit US/CA area code (random if omitted)
- country_code: "US" (default) or "CA"

Response: { "success": true, "phone_number": "+14155551234", "expires_at": "2025-07-14T..." }

Numbers expire after 30 days. Top up to extend.

## Top up a phone number

POST /api/x402/number/topup ($15.00)

Body (JSON):
{
  "phone_number": "+14155551234"
}

Extends the number by 30 days from the current expiry (or from today if already expired). Top-ups stack — call it multiple times to prepay months ahead. Anyone can top up any number.

Response: { "success": true, "phone_number": "+14155551234", "expires_at": "2025-08-14T..." }

## List your numbers

GET /api/x402/numbers?wallet=0x... (free, no payment required)

Response: { "success": true, "numbers": [{ "phone_number": "+14155551234", "expires_at": "...", "area_code": "415", "country_code": "US" }] }

## Typical flow
1. POST /api/x402/call → get 402 Payment Required
2. Pay with x402-compatible client (USDC on Base)
3. Receive call_id
4. Poll GET /api/x402/call/{call_id} until completed=true
5. Read transcript and summary

## Phone number flow
1. POST /api/x402/number → buy a number ($20.00, active 30 days)
2. Use "from" field in POST /api/x402/call to call from your number
3. POST /api/x402/number/topup → extend by 30 days ($15.00)
4. GET /api/x402/numbers?wallet=0x... → list your active numbers

## Voices
- nat (default): American female
- josh: Articulate American male
- maya: Young American female, soft
- june: American female
- paige: Calm, soft-tone female
- derek: Soft and engaging male
- florian: German male

## Discovery
- GET /.well-known/x402 — machine-readable resource discovery
- GET /llms.txt — this file