# Dial x402

> Telephony and OSINT primitives for AI agents. Pay-per-use via x402 crypto payments on Base.

## 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

Alternative: Buy credits once ($0.10 for 100 credits) and use Bearer token auth.

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

## Endpoints

### POST /api/v1/messages/send — Send SMS ($0.10)
Auth: x402 | Send text messages to any phone number worldwide.
Body: { "to": "+1234567890", "body": "Hello", "from": "optional" }
Response: { "success": true, "messageIds": [12345], "totalPrice": 0.0075 }

### POST /api/v1/lookup — Phone Lookup ($0.05)
Auth: x402 | Reverse phone lookup — carrier, caller name, line type, SIM swap detection.
Body: { "phoneNumber": "+1234567890", "fields": ["line_type_intelligence", "caller_name"] }
Available fields: line_type_intelligence, caller_name, line_status, sim_swap, identity_match, reassigned_number, sms_pumping_risk, phone_number_quality_score
Response: { "success": true, "phoneNumber": "+1234567890", "valid": true, "data": { ... } }

### POST /api/v1/dehashed/search — Breach Search ($0.05)
Auth: x402 | Search leaked credentials by email, phone, IP, domain, username.
Body: { "query": "email:user@example.com", "size": 100, "page": 1 }
Query formats: email:, phone:, ip_address:, domain:, username:, password:, hashed_password:, name:, vin:, address:
Response: { "success": true, "total": 42, "entries": [...], "balance": 95 }

### POST /api/v1/credits/top-up — Buy Credits ($0.10)
Auth: x402 + Bearer | Buys 100 prepaid credits for Bearer-token access.
Response: { "success": true, "creditsAdded": 100, "credits": 200 }

### GET /api/v1/account — Check Balance (free)
Auth: Bearer | Returns credit balance and account info.

### Credit Endpoints (Bearer auth, 1 credit each)
- POST /api/v1/messages/send-with-credits — Same as send, uses credits
- POST /api/v1/lookup/with-credits — Same as lookup, uses credits
- POST /api/v1/dehashed/search-with-credits — Same as search, uses credits

## Coming Soon
- POST /api/v1/numbers/buy — Buy phone number ($1.50)
- POST /api/v1/verifications/start — Phone verification ($0.25)
- POST /api/v1/esim/checkout — eSIM data plan ($2.45)

## 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 (GET for SSE, POST for messages).
Tools: send_sms ($0.10), phone_lookup ($0.05), breach_search ($0.05), buy_number ($1.50), buy_esim ($2.45), list_esim_plans (free), discovery (free).
Compatible with x402-mcp's withPayment() wrapper.

## Error Codes
| 400 | Bad request (validation error) |
| 402 | Payment required or payment verification failed |
| 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/x402-dial
- OpenX402: https://openx402.ai
- x402 Protocol: https://docs.x402.org