Domain Finder

Check domain availability (via RDAP) and pricing (via registrar APIs). Generate words from WordNet dictionary by topic, length, or merged topics.

Setup

pip install -r requirements.txt
python -c "import nltk; nltk.download('wordnet'); nltk.download('omw-1.4'); nltk.download('words')"
cp .env.example .env  # then add your API keys

Usage

All-in-one (recommended)

python domain-searcher.py --topic animal --max-length 6 --price-queries 10
python domain-searcher.py --merge animal color --max-length 8 --shuffle --price-queries 5
python domain-searcher.py --length 4 --limit 50 --max-price 15
python domain-searcher.py --list-topics

Separate tools

# Generator → stdout, Finder → stdin
python generator.py --topic animal --max-length 5 --shuffle | python finder.py

# Check specific words
python finder.py cat dog sun --tld io --provider name.com

# Query cached results
python finder.py --show-cached --available-only --max-price 20

Key flags

Flag	Where	Description
--topic WORD	generator, searcher	WordNet topic (animal, food, plant, color...)
--merge T1 T2	generator, searcher	Combine two topics (e.g., animal + color)
--length N	generator, searcher	Exact word length
--min-length / --max-length	generator, searcher	Length range (default: 3-12)
--shuffle	all	Randomize word order
--limit N	generator, searcher	Max words to generate
--tld TLD	finder, searcher	TLD to check (default: com)
--price-queries N	searcher	Cap pricing API calls
--provider NAME	finder, searcher	Force specific provider
--min-price / --max-price	finder, searcher	Filter by price
--no-cache	finder, searcher	Skip SQLite cache
--include-rare	generator, searcher	Include scientific/Latin words

Pricing Providers

Configure at least one in .env (see .env.example):

Provider	Free?	Rate Limit	Signup
Name.com	Yes, unlimited	20 req/sec	https://www.name.com
Gandi	Yes (needs product)	1000 req/min	https://account.gandi.net
DomScan	10k credits/mo	Fast	https://domscan.net
Dynadot	Yes, unlimited	1 domain/call	https://www.dynadot.com
Porkbun	Yes	1 req/10s	https://porkbun.com/account/api
GoDaddy	Needs prepaid $	30 req/min	https://developer.godaddy.com/keys

Auto-selects first configured provider. Override with --provider name.com.

Configuration

Variable	Description
NAMECOM_USERNAME	Name.com account username
NAMECOM_TOKEN	Name.com API token
GANDI_API_KEY	Gandi Personal Access Token
DOMSCAN_API_KEY	DomScan API key
DYNADOT_API_KEY	Dynadot API key
PORKBUN_API_KEY	Porkbun API key
PORKBUN_SECRET_KEY	Porkbun secret key
GODADDY_KEY	GoDaddy API key
GODADDY_SECRET	GoDaddy API secret

Architecture

domain-searcher.py      All-in-one CLI (generator + finder)
finder.py               Check specific words as domains
generator.py            Generate words from NLTK WordNet
checker.py              RDAP registration lookup (free)
db.py                   SQLite cache (24h TTL)
config.py               .env loading
providers/
  base.py               PricingProvider base class + PriceResult
  registry.py           Auto-selects first configured provider
  namecom.py            Name.com    ── each implements is_configured()
  gandi.py              Gandi       ── and async check_price()
  domscan.py            DomScan
  dynadot.py            Dynadot
  porkbun.py            Porkbun
  godaddy.py            GoDaddy

Adding a provider

1. Create providers/yourprovider.py extending PricingProvider
2. Implement is_configured() and async check_price()
3. Add env vars to config.py
4. Register in _all_providers() in providers/registry.py