API Reference

Base URL: https://payphone.wtf

All paid endpoints support two auth methods:

Method	How it works	Best for
x402	Pay USDC per request (automatic via `Payment-Signature` header)	Agents with wallets
Credits	Prepay credits, use Privy JWT or `dial_live_*` API key	High-volume callers, long-running bots

See Bearer Token for Privy session tokens vs long-lived API keys. API keys are scope-gated; see API Keys.

Endpoints

Method	Path	Auth	Price	Description
POST	`/api/v1/sms/send`	x402	$0.05	Send SMS (pool number)

Method	Path	Auth	Price	Description
POST	`/api/v1/lookup`	x402	$0.05	Reverse phone lookup
POST	`/api/v1/lookup/with-credits`	Bearer	1 credit	Reverse phone lookup
POST	`/api/v1/dehashed/search`	x402	$0.05	Breach data search
POST	`/api/v1/dehashed/search-with-credits`	Bearer	1 credit	Breach data search

Method	Path	Auth	Price	Description
POST	`/api/v1/credits/top-up`	x402 + Bearer	$0.10	Buy 100 credits
GET	`/api/v1/account`	Bearer / API key	Free	Account snapshot + balance
GET	`/api/v1/account/credits`	Bearer / API key	Free	Credit breakdown
GET	`/api/v1/account/usage`	Bearer / API key (`account:read`)	Free	Daily quota usage
GET	`/api/v1/account/history`	Bearer / API key (`account:read`)	Free	Transaction history
GET	`/api/v1/account/subscription`	Bearer / API key (`account:read`)	Free	Plan + trial status
GET	`/api/v1/numbers/buy/status`	Bearer / API key (`numbers:read`)	Free	Poll provisioning job
GET	`/api/v1/sms/inbox`	Bearer / API key / x402	Free	Messages for owned line

Method	Path	Auth	Price	Description
POST	`/api/v1/numbers/buy`	x402	$1.50	Buy a phone number
POST	`/api/v1/verifications/start`	x402	$0.25	Start phone verification
POST	`/api/v1/esim/checkout`	x402	$2.45	Order eSIM data plan

Method	Path	Auth	Description
GET	`/discovery/resources`	None	Bazaar resource catalog
GET	`/.well-known/x402`	None	Protocol metadata
GET	`/api/v1/discovery`	None	Legacy discovery
GET	`/api/health`	None	Health check

All errors follow the format:

{
  "success": false,
  "error": "error_code",
  "message": "Human-readable description"
}

Status	Code	Meaning
400	`validation_error`	Bad request body
400	`invalid_e164_destination`	SMS recipient is not a valid E.164 phone number
401	`missing_token` / `invalid_api_key`	Missing or invalid Bearer token
402	(x402 protocol)	Payment required
402	`insufficient_credits`	Not enough credits — top up or fall back to x402
429	`rate_limited`	Too many requests (60/min)
502	`provider_error`	Upstream provider failure
500	`internal_error`	Unexpected error