Scam detection API documentation
Bewary is a scam detection API. Send a link, domain, phone number, SMS short code, email address, crypto wallet, IBAN, app or payment handle, and get back a typed verdict (scam, suspicious, safe or unknown), the probability that it is a scam, the facts behind it and reason codes your code can branch on. It is a REST API and an MCP server for AI agents. Every call needs an API key, and a free key gets 1,000 credits a month.
Your first call
curl -H "Authorization: Bearer $BEWARY_API_KEY" \
"https://api.bewary.app/v1/url?u=http%3A%2F%2Fpaypal-login-secure.top%2Fverify%3Faccount%3Dupdate"Two real answers from the live API: a brand lookalike and a real site.
{ "verdict": "scam", "p_scam": 0.9116, "reason_codes": [ "DOMAIN_BRAND_ON_ABUSED_TLD", "DOMAIN_LOOKALIKE_BRAND_WORD" ], "entities": [ { "type": "url", "value": "http://paypal-login-secure.top/verify?account=update", "verdict": "scam" }, { "type": "domain", "value": "paypal-login-secure.top", "verdict": "scam" } ]}{ "verdict": "safe", "p_scam": 0, "reason_codes": [ "DOMAIN_ALLOWLISTED" ], "entities": [ { "type": "url", "value": "https://www.usps.com/manage/", "verdict": "safe" }, { "type": "domain", "value": "www.usps.com", "verdict": "safe" } ]}Trimmed to the fields you act on. The full answer is on Link.
Act on it
import os, requests
def link_action(url):
"""block, warn or allow, for a link preview or before an agent opens a page"""
key = os.environ["BEWARY_API_KEY"] # a free key: bewary.app/account
headers = {"Authorization": f"Bearer {key}"}
try:
r = requests.get("https://api.bewary.app/v1/url", params={"u": url},
headers=headers, timeout=10)
r.raise_for_status()
except requests.RequestException:
return "warn" # never fail open
verdict = r.json()["verdict"]
return {"scam": "block", "safe": "allow"}.get(verdict, "warn")
print(link_action("http://paypal-login-secure.top/verify")) # blockimport type { Envelope } from "./bewary"
export async function linkAction(url: string): Promise<"block" | "warn" | "allow"> {
const key = process.env.BEWARY_API_KEY! // a free key: bewary.app/account
const headers: Record<string, string> = { Authorization: `Bearer ${key}` }
try {
const res = await fetch("https://api.bewary.app/v1/url?u=" + encodeURIComponent(url),
{ headers, signal: AbortSignal.timeout(10_000) })
if (!res.ok) return "warn" // never fail open
const r: Envelope = await res.json()
return r.verdict === "scam" ? "block" : r.verdict === "safe" ? "allow" : "warn"
} catch { return "warn" }
}Pick the right call
GET/v1/url 1 credit · deep=true 30 median 477 ms How old is this domain, and does it imitate a brand? GET/v1/domain/{host} 1 credit · deep=true 30 median 449 ms Is this phone number reported for scams? GET/v1/phone/{number} 1 credit · line_type=true 10 median 115 ms Who sends texts from this short code? GET/v1/shortcode/{country}/{code} 1 credit median 113 ms Is this email address disposable? GET/v1/email/{address} 1 credit median 211 ms Who runs this IP address, and is it on a scam list? GET/v1/ip/{ip} 1 credit median 260 ms Is this crypto wallet on a scam list? GET/v1/wallet/{chain}/{address} 1 credit median 127 ms Is this IBAN valid, and which bank is it at? GET/v1/iban/{iban} 1 credit per item Is this app still live on its store? GET/v1/app/{store}/{app_id} 1 credit per item Does this Cash App, PayPal or Venmo handle exist? GET/v1/payment-handle/{provider}/{handle} 1 credit per item Which other domains run on the same setup? GET/v1/domain/{host}/related 5 credits per item Do a new seller's contact points check out? POST/v1/assess 1 credit per item Check up to 1,000 values in one request POST/v1/batch 1 credit per item The basics
- Base URL
https://api.bewary.app- Free key
- 1,000 credits a month, no card. Every call needs a key. Keys, limits and errors
- Every answer
- Lookups and batches return a
verdict. Related domains return relations, assess returns a decision and watches produce events. Response format - Types
- OpenAPI, TypeScript, Python
- AI agents
- MCP server with 15 tools, and tool definitions for OpenAI, Claude, Vercel AI SDK and LangChain. AI agents
Try it
Free from this page: 10 lookups a dayQuestions
Is there one API that checks links, phone numbers, emails and wallets for scams?
Yes, Bewary looks up links, domains, IP addresses, phone numbers, SMS short codes, email addresses, crypto wallets, IBANs, mobile apps and payment handles, finds related domains and assesses a seller's contact points with POST /v1/assess. A free API key gets 1,000 credits a month, and paid credits come in prepaid packs and never expire.
What API should an AI agent call before it opens a link or pays someone?
lookup_url for a link, lookup_phone for a number, and lookup_wallet, lookup_iban or lookup_payment_handle before sending money. They are on Bewary's MCP server at https://api.bewary.app/mcp and as REST endpoints. The agent should stop on scam, ask the user on suspicious, and never treat unknown as safe.
Is it free?
A free key gets 1,000 credits a month without a card, on every endpoint. Prepaid credit packs start at $20 for 10,000 credits and never expire.
How accurate is it?
p_scam is a probability from 0 to 1, not yet calibrated against labelled data. site.p_scam_site is Bewary's verdict on a page its worker read in the last 90 days. Every check and lookup returns reason_codes and each signal's source class and weight.
Where does the data come from?
Bewary reads RDAP registration data, its hourly DNS history and certificates, phishing and malware URL feeds, national lists (CERT Polska, Taiwan's 165 line, Germany's Federal Network Agency and the US Treasury's OFAC list), FTC Do Not Call and FCC complaints, app stores, the public profile pages of Cash App, PayPal and Venmo, national bank-code lists and its researched US short code directory. GET /v1/datasets lists each dataset with its geography. Bewary returns its own verdict without passing through a source's output unchanged.
Updated · This page as Markdown · Changelog