# Dial x402

> Virtual phone numbers for AI agents and privacy. Monthly prepaid via x402 crypto payments on Base. Dashboard via Privy.

## Docs
- Full docs: https://x402.dial.wtf/docs
- Full API reference (plain text): https://x402.dial.wtf/llms-full.txt
- MCP server: https://x402.dial.wtf/mcp
- Machine-readable discovery: https://x402.dial.wtf/discovery/resources
- Protocol metadata: https://x402.dial.wtf/.well-known/x402

## Base URL
https://x402.dial.wtf

## Auth
All paid endpoints use the x402 protocol (HTTP 402 Payment Required).
Pay with USDC on Base (eip155:8453). No accounts, no API keys, no KYC.
Facilitator: https://facilitator.openx402.ai

## Number Management (SIWE)
After purchasing a number, manage it using Sign-In with Ethereum (SIWE).
The wallet that paid via x402 can authenticate at /api/v1/auth/siwe to manage its numbers.

## Quick Start (JavaScript)
```
npm install @x402/fetch @x402/core @x402/evm viem
```

## Endpoints

### POST /api/v1/numbers/buy/us — Buy Phone Line (US) ($100.00)
Auth: x402 | Buy an exclusive US phone line ($100, then $60/mo).
Body: { "country": "US" }
Response: { "success": true, "phoneNumber": "+12125551234", "country": "US", "expiresAt": "2026-04-26T..." }

### POST /api/v1/numbers/buy/intl — Buy Phone Line (International) ($100.00)
Auth: x402 | Buy an exclusive international phone line ($100, then $60/mo).
Body: { "country": "GB" }
Response: { "success": true, "phoneNumber": "+447700900123", "country": "GB", "expiresAt": "2026-04-26T..." }

### POST /api/v1/sms/send — Send SMS (A La Carte) ($0.05)
Auth: x402 | Send a one-off SMS to any phone worldwide ($0.05).
Body: { "to": "+1234567890", "message": "Hello from Dial" }
Response: { "success": true, "messageId": "...", "to": "+1234567890", "segments": 1 }

### POST /api/v1/numbers/mine/send — Send SMS (Own Line) ($0.05)
Auth: x402 + SIWE Bearer | Send SMS from your exclusive line ($0.05/msg after quota).
Headers: Authorization: Bearer <siwe_token>, Payment: <x402_proof>
Body: { "phoneNumber": "+12125551234", "to": "+0987654321", "message": "Hello" }
Response: { "success": true, "messageId": "...", "to": "+0987654321", "segments": 1 }

### GET /api/v1/auth/siwe — Get SIWE Nonce
Query: ?address=0x...&chainId=8453
Returns a nonce and pre-built SIWE message for the client to sign.

### POST /api/v1/auth/siwe — Verify SIWE Signature
Body: { "message": "...", "signature": "0x..." }
Returns: { "success": true, "token": "...", "address": "0x...", "expiresAt": "..." }

### GET /api/v1/numbers/mine — List My Numbers (SIWE auth)
Auth: Bearer <siwe_session_token>
Returns all virtual numbers owned by the authenticated wallet.

### GET /api/v1/discovery — Service Discovery (free)
Returns OpenX402-compatible resource metadata.

## x402 Payment Flow
1. POST to any paid endpoint without payment
2. Receive HTTP 402 with Payment-Required header (base64 JSON)
3. Decode to get: scheme, network, amount (USDC atomic units), payTo address
4. Sign EIP-3009 transferWithAuthorization with your wallet
5. Base64-encode the signature and resubmit with Payment-Signature header
6. Facilitator verifies and settles on-chain, server returns 200

## Networks
| Network | Chain ID | USDC |
| Base (mainnet) | eip155:8453 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| Base Sepolia (testnet) | eip155:84532 | 0x036CbD53842c5426634e7929541eC2318f3dCF7e |

## MCP (Model Context Protocol)
Connect at https://x402.dial.wtf/mcp (POST Streamable HTTP; human setup: https://x402.dial.wtf/connect — MCP + skill install for Cursor, Claude Code, Codex).
Tools: buy_number ($100.00), buy_number_us ($100.00), buy_number_intl ($100.00), send_sms ($0.05), discovery (free).
Compatible with x402-mcp's withPayment() wrapper.

## Coming Soon
- POST /api/v1/lookup — Phone Lookup ($0.05)
- POST /api/v1/dehashed/search — Breach Search ($0.05)
- POST /api/v1/credits/top-up — Buy Credits ($5.00)
- POST /api/v1/verifications/start — Phone Verify ($2.25)
- POST /api/v1/esim/checkout — eSIM Checkout ($2.45)

## Error Codes
| 400 | Bad request (validation error) |
| 402 | Payment required or payment verification failed |
| 401 | Unauthorized — invalid SIWE session |
| 429 | Rate limited (60 req/min) — check Retry-After header |
| 502 | Upstream provider error |
| 500 | Internal server error |

## Links
- Docs: https://x402.dial.wtf/docs
- GitHub: https://github.com/Dial-WTF/
- OpenX402: https://openx402.ai
- x402 Protocol: https://docs.x402.org