Getting Started

Get your AI agent sending SMS and querying phone data in under 5 minutes.

Prerequisites

Node.js 18+
An EVM wallet with USDC on Base (mainnet) or Base Sepolia (testnet)
That's it. No signup, no API keys, no accounts.

Install the SDK

npm install @dial/sdk @x402/fetch @x402/core @x402/evm viem

Set Up x402 Payment

import { privateKeyToAccount } from "viem/accounts";
import { createWalletClient, http } from "viem";
import { baseSepolia } 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";

// Your agent's wallet
const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
});

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

Create a Dial Client

import { DialClient } from "@dial/sdk";

const dial = new DialClient({
  baseUrl: "https://x402.dial.wtf",
  fetch: paidFetch, // x402 payments handled automatically
});

Send Your First SMS

const result = await dial.messages.send({
  to: "+1234567890",
  body: "Hello from my AI agent!",
});

console.log(result);
// { success: true, message: "SMS sent", provider: "dial", messageIds: [12345] }

Look Up a Phone Number

const lookup = await dial.lookup.phone({
  phoneNumber: "+1234567890",
  fields: ["line_type_intelligence", "caller_name"],
});

console.log(lookup);
// { success: true, phoneNumber: "+1234567890", valid: true, data: { ... } }

Search Breach Data

const breaches = await dial.dehashed.search({
  query: "email:target@example.com",
});

console.log(breaches);
// { success: true, total: 42, entries: [...] }

Using cURL (No SDK)

You can also call endpoints directly. Without a payment header, you'll get a 402 response with payment requirements:

curl -X POST https://x402.dial.wtf/api/v1/messages/send \
  -H "Content-Type: application/json" \
  -d '{"to": "+1234567890", "body": "Hello"}'

# Response: HTTP 402
# Header: Payment-Required: base64({
#   "x402Version": 2,
#   "accepts": [{
#     "scheme": "exact",
#     "network": "eip155:8453",
#     "amount": "10000",
#     "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#     "payTo": "0x..."
#   }]
# })

Sign the payment authorization with your wallet, base64-encode it, and resubmit with the Payment-Signature header.

Alternative: Credits (Bearer Token)

If you prefer not to pay per-request, buy credits via x402 once and use Bearer token auth:

// Buy 100 credits for $0.10 (requires x402 payment + Bearer token)
await dial.credits.topUp();

// Use credits for subsequent calls (no x402 needed)
const dial2 = new DialClient({
  baseUrl: "https://x402.dial.wtf",
  bearerToken: "your-privy-access-token",
});

await dial2.messages.sendWithCredits({
  to: "+1234567890",
  body: "Paid with credits!",
});

Generate a Wallet

Need a fresh wallet for your agent?

import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";

const privateKey = generatePrivateKey();
const account = privateKeyToAccount(privateKey);

console.log("Address:", account.address);
console.log("Private Key:", privateKey);
// Fund with USDC on Base Sepolia via faucet for testing

Next Steps

x402 Payment Flow — How the payment protocol works
API Reference — Complete endpoint documentation
Claude Code Integration — Use Dial from Claude Code

Getting Started

On this page