# Dial x402 — Complete API Reference

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

Base URL: https://x402.dial.wtf
Facilitator: https://facilitator.openx402.ai
MCP: https://x402.dial.wtf/mcp
Discovery: https://x402.dial.wtf/discovery/resources
Protocol: https://x402.dial.wtf/.well-known/x402

---

## AUTH: x402 Payment Protocol

All paid endpoints return HTTP 402 when called without payment.

### How it works:
1. POST to endpoint without payment → receive 402
2. Read Payment-Required header (base64-encoded JSON):
   {
     "x402Version": 2,
     "accepts": [{
       "scheme": "exact",
       "network": "eip155:8453",
       "amount": "10000",
       "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
       "payTo": "0x..."
     }]
   }
3. amount is in USDC atomic units (6 decimals). "100000" = $0.10
4. Sign EIP-3009 transferWithAuthorization for the amount to the payTo address
5. Base64-encode the signed authorization
6. Resubmit original request with header: Payment-Signature: <base64>
7. Server verifies via facilitator, settles on-chain, returns 200

### JavaScript setup:
```javascript
import { privateKeyToAccount } from "viem/accounts";
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { toClientEvmSigner } from "@x402/evm";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(),
});

const signer = toClientEvmSigner(walletClient);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));
const paidFetch = wrapFetchWithPayment(fetch, client);

// Now use paidFetch instead of fetch — 402s are handled automatically
const res = await paidFetch("https://x402.dial.wtf/api/v1/messages/send", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ to: "+1234567890", body: "Hello" }),
});
```

### Networks:
- Base mainnet: eip155:8453 — USDC: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- Base Sepolia: eip155:84532 — USDC: 0x036CbD53842c5426634e7929541eC2318f3dCF7e

---

## AUTH: Bearer Token (Credits)

Alternative to per-request x402 payments. Buy credits once, use Bearer token after.

1. Buy credits: POST /api/v1/credits/top-up (requires x402 payment + Bearer token)
2. Use credit endpoints with: Authorization: Bearer <privy_access_token>
3. Each credit endpoint costs 1 credit per call
4. If a provider fails, the credit is auto-refunded

---

## ENDPOINT: Send SMS

### POST /api/v1/messages/send
Price: $0.10 USDC | Auth: x402

Request:
{
  "to": "+1234567890",       // Required. E.164 format phone number
  "body": "Hello world",     // Required. Message text
  "from": "MyApp"            // Optional. Sender ID or phone number
}

Response (200):
{
  "success": true,
  "message": "SMS sent",
  "provider": "dial",
  "messageIds": [12345678],
  "balance": 42.5,
  "totalPrice": 0.0075
}

### POST /api/v1/messages/send-with-credits
Auth: Bearer | Cost: 1 credit | Same request/response format

---

## ENDPOINT: Phone Lookup

### POST /api/v1/lookup
Price: $0.05 USDC | Auth: x402

Request:
{
  "phoneNumber": "+1234567890",   // Required. E.164 format
  "fields": [                      // Optional. Defaults to line_type_intelligence + caller_name
    "line_type_intelligence",      // Carrier, line type (mobile/landline/voip)
    "caller_name",                 // CNAM lookup
    "line_status",                 // Reachable/unreachable
    "sim_swap",                    // Recent SIM swap detection
    "identity_match",              // Name/address verification
    "reassigned_number",           // Number reassignment check
    "sms_pumping_risk",            // Fraud detection
    "phone_number_quality_score"   // Quality scoring
  ]
}

Response (200):
{
  "success": true,
  "phoneNumber": "+1234567890",
  "countryCode": "US",
  "nationalFormat": "(234) 567-890",
  "valid": true,
  "validationErrors": null,
  "data": {
    "line_type_intelligence": {
      "type": "mobile",
      "carrier": "T-Mobile USA, Inc.",
      "mobile_country_code": "310",
      "mobile_network_code": "260"
    },
    "caller_name": {
      "caller_name": "JOHN DOE",
      "caller_type": "CONSUMER"
    }
  },
  "provider": "dial"
}

### POST /api/v1/lookup/with-credits
Auth: Bearer | Cost: 1 credit | Same request/response format

---

## ENDPOINT: Breach Search

### POST /api/v1/dehashed/search
Price: $0.05 USDC | Auth: x402

Request:
{
  "query": "email:user@example.com",  // Required. field:value format
  "size": 100,                         // Optional. Results per page (1-10000, default 100)
  "page": 1                            // Optional. Page number (default 1)
}

Query field options:
- email:user@example.com
- phone:+1234567890
- ip_address:1.2.3.4
- domain:example.com
- username:johndoe
- password:plaintext
- hashed_password:hash
- name:"John Doe"
- vin:1HGBH41JXMN109186
- address:"123 Main St"

Response (200):
{
  "success": true,
  "total": 42,
  "entries": [
    {
      "id": "abc123",
      "email": "user@example.com",
      "username": "johndoe",
      "password": "p@ssw0rd",
      "hashed_password": "",
      "name": "John Doe",
      "database_name": "ExampleDB",
      "ip_address": "1.2.3.4",
      "phone": "+1234567890",
      "address": "",
      "vin": "",
      "obtained_from": "example_breach_2023"
    }
  ],
  "balance": 95
}

### POST /api/v1/dehashed/search-with-credits
Auth: Bearer | Cost: 1 credit | Same request/response format

---

## ENDPOINT: Buy Credits

### POST /api/v1/credits/top-up
Price: $0.10 USDC | Auth: x402 + Bearer

Requires both:
1. x402 payment ($0.10 USDC)
2. Authorization: Bearer <privy_access_token>

Request: {} (empty body)

Response (200):
{
  "success": true,
  "creditsAdded": 100,
  "credits": 200
}

---

## ENDPOINT: Account Balance

### GET /api/v1/account
Auth: Bearer (free)

Response (200):
{
  "success": true,
  "credits": 150,
  "address": "0x..."
}

---

## COMING SOON

### POST /api/v1/numbers/buy — $1.50
Buy a phone number. Request: { "country": "US" }

### POST /api/v1/verifications/start — $0.25
Start phone verification. Request: { "to": "+1234567890", "channel": "sms" }

### POST /api/v1/esim/checkout — $2.45
Order an eSIM data plan. Request: { "packageId": "..." }

---

## MCP SERVER

Endpoint: https://x402.dial.wtf/mcp
Protocol: Model Context Protocol (JSON-RPC over HTTP)
Transport: Streamable HTTP (GET for SSE, POST for messages)

Available tools:
- send_sms ($0.10) — Send SMS worldwide
- phone_lookup ($0.05) — Reverse phone lookup
- breach_search ($0.05) — Search breach databases
- discovery (free) — List all endpoints and pricing

### JavaScript MCP client:
```javascript
import { experimental_createMCPClient as createMCPClient } from "ai";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { withPayment } from "x402-mcp";

const mcpClient = await createMCPClient({
  transport: new StreamableHTTPClientTransport("https://x402.dial.wtf/mcp"),
});
const client = await withPayment(mcpClient, {
  account: purchaserAccount,
  network: "base",
});

const tools = await client.tools();
// send_sms, phone_lookup, breach_search, discovery
```

---

## ERROR CODES

| Code | Meaning |
|------|---------|
| 200  | Success |
| 400  | Bad request — validation error in request body |
| 402  | Payment required or payment verification failed |
| 401  | Unauthorized — invalid or missing Bearer token |
| 429  | Rate limited — 60 requests/minute. Check Retry-After header |
| 502  | Upstream provider error |
| 500  | Internal server error |

All error responses:
{
  "error": "error_code",
  "message": "Human-readable description"
}

Rate limit headers on every response:
- X-RateLimit-Remaining: requests left in window
- X-Request-Id: unique request ID for debugging

---

## CORS

All endpoints allow cross-origin requests:
- Access-Control-Allow-Origin: *
- Access-Control-Allow-Headers: Authorization, Content-Type, Payment-Signature, Payment-Response
- Access-Control-Expose-Headers: Payment-Required, Payment-Response, X-Request-Id

---

## DISCOVERY

### GET /discovery/resources
Bazaar-standard resource catalog. Pagination: ?offset=0&limit=100&type=http

### GET /.well-known/x402
Protocol metadata: version, networks, facilitators, payTo address.

### GET /api/v1/discovery
Legacy discovery endpoint (backward-compatible).

---

## LINKS

- Docs: https://x402.dial.wtf/docs
- Getting Started: https://x402.dial.wtf/docs/getting-started
- API Reference: https://x402.dial.wtf/docs/api-reference
- GitHub: https://github.com/Dial-WTF/x402-dial
- OpenX402: https://openx402.ai
- x402 Protocol: https://docs.x402.org