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

Updated 2026-10-30.

## First call

```bash
curl -H "Authorization: Bearer $BEWARY_API_KEY" "https://api.bewary.app/v1/url?u=http%3A%2F%2Fpaypal-login-secure.top%2Fverify%3Faccount%3Dupdate"
```

It answers:

```json
{
  "verdict": "scam",
  "p_scam": 0.9116,
  "reason_codes": [
    "DOMAIN_BRAND_ON_ABUSED_TLD",
    "DOMAIN_LOOKALIKE_BRAND_WORD"
  ]
}
```

Act on it in Python:

```python
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"))   # block
```

## Pick the right call

| Job | Call | Credits | Speed |
|---|---|---|---|
| [Is this link safe to open?](https://bewary.app/docs/url.md) | `GET /v1/url` | 1 credit, deep=true 30 | median 477 ms |
| [How old is this domain, and does it imitate a brand?](https://bewary.app/docs/domain.md) | `GET /v1/domain/{host}` | 1 credit, deep=true 30 | median 449 ms |
| [Is this phone number reported for scams?](https://bewary.app/docs/phone.md) | `GET /v1/phone/{number}` | 1 credit, line_type=true 10 | median 115 ms |
| [Who sends texts from this short code?](https://bewary.app/docs/shortcode.md) | `GET /v1/shortcode/{country}/{code}` | 1 credit | median 113 ms |
| [Is this email address disposable?](https://bewary.app/docs/email.md) | `GET /v1/email/{address}` | 1 credit | median 211 ms |
| [Who runs this IP address, and is it on a scam list?](https://bewary.app/docs/ip.md) | `GET /v1/ip/{ip}` | 1 credit | median 260 ms |
| [Is this crypto wallet on a scam list?](https://bewary.app/docs/wallet.md) | `GET /v1/wallet/{chain}/{address}` | 1 credit | median 127 ms |
| [Is this IBAN valid, and which bank is it at?](https://bewary.app/docs/iban.md) | `GET /v1/iban/{iban}` | 1 credit | - |
| [Is this app still live on its store?](https://bewary.app/docs/app.md) | `GET /v1/app/{store}/{app_id}` | 1 credit | - |
| [Does this Cash App, PayPal or Venmo handle exist?](https://bewary.app/docs/payment-handle.md) | `GET /v1/payment-handle/{provider}/{handle}` | 1 credit | - |
| [Which other domains run on the same setup?](https://bewary.app/docs/related.md) | `GET /v1/domain/{host}/related` | 5 credits | - |
| [Do a new seller's contact points check out?](https://bewary.app/docs/assess.md) | `POST /v1/assess` | 1 credit | - |
| [Check up to 1,000 values in one request](https://bewary.app/docs/batch.md) | `POST /v1/batch` | 1 credit | - |

## Basics

- Base URL: https://api.bewary.app. Auth: `Authorization: Bearer <key>` or `X-Api-Key` on every call.
- Free: a free key gets 1,000 credits a month, no card. Every call needs a key.
- Rate limit: 600 requests a minute per key.
- Types: OpenAPI at https://api.bewary.app/v1/openapi.json, TypeScript at https://bewary.app/types/bewary.d.ts, Python at https://bewary.app/types/bewary_models.py.
- MCP: https://api.bewary.app/mcp (15 tools). Setup: https://bewary.app/mcp
- CLI: npx bewary (one command per MCP tool, no install). Guide: https://bewary.app/docs/cli
- Number directory: https://bewary.app/area-codes (FTC and FCC complaints per US area code and phone number; every number page has a JSON twin, https://bewary.app/number/<10 digits>.json, and the API serves the same data free at https://api.bewary.app/v1/directory/)

## Guides

- [Scam checks for AI agents](https://bewary.app/docs/ai-agents.md): An AI agent in Claude, ChatGPT or Cursor checks a link, phone number or payment handle with Bewary's MCP server before it acts.
- [Bewary CLI](https://bewary.app/docs/cli.md): The Bewary CLI checks links, phone numbers, emails and wallets for scams in a terminal with npx bewary, no install. Its --fail-on flag fails a CI step.
- [Act on a verdict](https://bewary.app/docs/verdicts.md): What to do with each Bewary verdict in an inbox, a sign-up form, a link preview or an AI agent, with copy-paste Python and TypeScript, retries and timeouts.
- [Keys, limits and errors](https://bewary.app/docs/authentication.md): Call the Bewary scam check API with an API key: a free key gets credits every month. Credits, rate limits, response headers and error codes.
- [Response format](https://bewary.app/docs/response.md): Every check and lookup returns the same typed JSON envelope. Each entity carries typed facts. Each signal includes its source class and weight.
- [Reason codes](https://bewary.app/docs/reason-codes.md): The full list of Bewary signal codes, from DOMAIN_LOOKALIKE_BRAND_WORD to LISTED_BLOCKLIST, with severity, the entity each one attaches to, and whether it is live.
- [Watches, events and webhooks](https://bewary.app/docs/watches.md): Watch a domain, phone number, wallet or brand and get an event when it changes: new IP or name servers, down, expired, re-registered, listed, a new lookalike. 1 credit a day per watch.
- [Bulk files and backtests](https://bewary.app/docs/bulk.md): Download Bewary's listed domains, links, numbers and wallets as CSV, an RPZ zone, STIX 2.1 or a TAXII collection, updated hourly, with deltas. Backtest your own list against our history.
- [Datasets and calibration](https://bewary.app/docs/datasets.md): Every dataset Bewary answers from, with its geography and live counts, free at GET /v1/datasets. How each answer names its dataset, and the published calibration of the site score.
- [Changelog](https://bewary.app/docs/changelog.md): What changed in the Bewary scam check API, by date. The v1 contract only grows: new fields, enum values and codes, never removals.

## Questions

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