# is-real-biz

> **Pay-per-call API that tells AI agents whether a domain is a real business.** Built MCP-first. Two payment rails: x402 (autonomous, zero signup) + prepaid credits (50 free checks, no credit card).

**🚀 Live: https://is-real-biz.is-real-biz.workers.dev** — try it now:
```bash
curl -X POST https://is-real-biz.is-real-biz.workers.dev/billing/signup \
  -H 'content-type: application/json' -d '{"email":"you@example.com"}'
# returns: { api_key: "irb_live_...", credits_cents: 250 } — 50 free checks
```

```
GET /check?domain=stripe.com   →   { verdict: "real", score: 94, signals: { ... } }
```

Use cases: KYB / vendor screening, lead qualification, fraud checks, due diligence — anywhere an agent needs to know "is this domain a legit business or a parked/scam/fake site?"

---

## Why agents will find this

Discovery surfaces (over-served on purpose — every agent looks somewhere different):

| Surface | Path | Spec |
| --- | --- | --- |
| MCP descriptor | `/.well-known/mcp.json` | modelcontextprotocol.io |
| MCP HTTP endpoint | `/mcp` | streamable HTTP |
| OpenAPI 3.1 | `/openapi.json` | OpenAPI |
| llms.txt | `/llms.txt` | llmstxt.org |
| ai.txt | `/ai.txt` | early crawler convention |
| ChatGPT plugin | `/.well-known/ai-plugin.json` | legacy |
| A2A agent card | `/.well-known/agent.json` | A2A v1 |
| agents.json | `/.well-known/agents.json` | Wildcard spec |
| Pricing manifest | `/pricing.json` | this server |
| robots/sitemap | `/robots.txt`, `/sitemap.xml` | SEO |

Plus the tool descriptions in `src/tool-descriptions.ts` are written for **embedding-based tool selection** — the way Claude/ChatGPT/Cursor actually pick which tool to call. Lots of natural-language examples, use-case tags, and example queries.

---

## Why agents can pay it

- **x402** ([spec](https://www.x402.org)) — the HTTP 402 payment protocol pushed by Coinbase + Cloudflare. Agents send an `X-PAYMENT` header, the server verifies + settles via a facilitator in ~2 seconds. **Zero signup. No accounts. Sub-cent calls work.** Default network is **Base Sepolia testnet** (free) — flip `X402_NETWORK = "base_mainnet"` in `wrangler.toml` to take real payments.
- **Prepaid credits** — `POST /billing/signup` with an email returns an API key with **50 free checks**. Need more? Redeem an operator-issued promo code at `/billing/promo`. No credit card, no Stripe, no card-on-file.

Both paths share the same `/check` endpoint, so any agent that speaks either rail just works.

---

## Zero-cost deploy (≈ 5 minutes)

You only need:

1. A free **Cloudflare** account (workers.dev subdomain is free forever) — [sign up](https://dash.cloudflare.com/sign-up)
2. A free **Google AI Studio** key for Gemini 1.5 Flash (no credit card) — [get key](https://aistudio.google.com/app/apikey)

Then:

```bash
git clone <this repo> is-real-biz && cd is-real-biz
npm run setup      # runs deploy.sh — creates D1, KV, applies schema, sets secrets, deploys
```

The script is interactive: it logs you into Cloudflare, provisions D1 + KV, patches `wrangler.toml` with the IDs, asks for your Gemini key, and deploys. You'll have a live URL like `https://is-real-biz.<your-subdomain>.workers.dev`.

### Manual deploy

```bash
npm install
npx wrangler login
npx wrangler d1 create is-real-biz-db          # paste id into wrangler.toml
npx wrangler kv namespace create CACHE         # paste id into wrangler.toml
npx wrangler d1 execute is-real-biz-db --file=./schema.sql --remote
npx wrangler secret put GEMINI_API_KEY
npx wrangler deploy
```

### Optional secrets

```bash
npx wrangler secret put ADMIN_TOKEN     # to mint promo codes via POST /admin/promo
npx wrangler secret put X402_PAY_TO     # your 0x address to enable x402 payments
```

---

## Try it

```bash
# 1. Get a free key (50 checks included)
curl -X POST https://YOUR-WORKER-URL/billing/signup \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com"}'

# 2. Check a domain
curl 'https://YOUR-WORKER-URL/check?domain=stripe.com' \
  -H 'authorization: Bearer irb_live_...'

# 3. Batch
curl -X POST https://YOUR-WORKER-URL/check/batch \
  -H 'authorization: Bearer irb_live_...' \
  -H 'content-type: application/json' \
  -d '{"domains":["stripe.com","openai.com","sketchy.xyz"]}'
```

---

## Use it from Claude / Cursor / Windsurf (MCP)

```jsonc
{
  "mcpServers": {
    "is-real-biz": {
      "url": "https://YOUR-WORKER-URL/mcp",
      "headers": { "Authorization": "Bearer irb_live_..." }
    }
  }
}
```

---

## Issuing promo codes (operator)

```bash
# Mint a 100-credit ($1) code, single use
curl -X POST https://YOUR-WORKER-URL/admin/promo \
  -H "X-Admin-Token: $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"amount_cents":100,"max_uses":1,"note":"HN launch"}'

# Mint a multi-use launch code
curl -X POST https://YOUR-WORKER-URL/admin/promo \
  -H "X-Admin-Token: $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"code":"LAUNCH50","amount_cents":250,"max_uses":500}'
```

---

## How the verdict is computed

| Signal | Source | Cost |
| --- | --- | --- |
| Domain age + registrar | RDAP via `rdap.org` | free |
| SSL validity | Certificate Transparency (`crt.sh`) | free |
| Homepage classification | Gemini 1.5 Flash | free (1500/day) |
| Contact info presence | regex over homepage + `/contact` | free |
| Social-media footprint | regex over homepage | free |

Weighted combination → score 0-100 → verdict {real, likely_real, uncertain, likely_fake, fake}. Cached for 24h in KV.

---

## Submit to MCP registries (after deploy)

- [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) — official, post-deploy submit form
- [smithery.ai](https://smithery.ai/new) — paste the `smithery.yaml`
- [glama.ai/mcp/servers](https://glama.ai/mcp/servers) — submit form
- [mcp.so](https://mcp.so) — open PR
- [mcpservers.org](https://mcpservers.org) — open PR
- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) — open PR
- The **x402 Bazaar** auto-indexes you after the first paid call — no submission needed.

---

## License

MIT.