SN22 is the Bittensor subnet behind Desearch's decentralized real-time intelligence layer. It coordinates miners and validators that serve live web, X/Twitter, and multi-source search data for Desearch API and console products.
This repository contains the subnet runtime: miner axons, validator scoring, the validator FastAPI service, operator runbooks, and shared protocol models.
| Component | Role | Main files |
|---|---|---|
| Miner | Runs a Bittensor axon, declares search capacity, answers health checks, and serves AI, X/Twitter, and web search synapses. | neurons/miners/miner.py, neurons/miners/config.py, neurons/miners/manifest.template.json |
| Validator | Sends synthetic and organic queries to miners, verifies results with independent providers, stores scoring windows, and writes weights on-chain. | neurons/validators/validator_service.py, neurons/validators/scoring/, neurons/validators/reward/ |
| Validator API | Runs FastAPI next to the validator so trusted Desearch services can request organic search and inspect public miner state. Protected routes require the access-key header. |
neurons/validators/api.py, neurons/validators/dependencies.py, run.sh |
| Shared package | Defines protocol models, synapses, tool helpers, dataset utilities, and common configuration. | desearch/protocol.py, desearch/miner_config.py, desearch/tools/ |
git clone https://github.com/Desearch-ai/subnet-22.git
cd subnet-22
python3 -m pip install -r requirements.txt
python3 -m pip install -e .The root project is Python (requirements.txt, setup.py). utility-api/ is a separate FastAPI service with its own pyproject.toml.
- Miner operators register a hotkey on netuid 22, configure
neurons/miners/.env, createneurons/miners/manifest.json, and run the miner axon under PM2. See Running a Miner. - Validator operators register a validator hotkey on netuid 22, configure validator credentials, run
run.shto manage the validator service plus API, and monitor weights/scoring. See Running a Validator. - Desearch service integrators should use the external Desearch API/console. The validator API documented here is a subnet-facing service protected by
EXPECTED_ACCESS_KEY, not the public billing/auth layer.
See Environment Variables for shared, miner-only, and validator-only settings.
Common requirements:
- Shared:
OPENAI_API_KEY,APIFY_API_KEY - Miner-only:
SERPAPI_API_KEY, optionalTWITTER_BEARER_TOKEN, wallet/netuid/axon settings - Validator-only:
EXPECTED_ACCESS_KEY,SCRAPINGDOG_API_KEY,WANDB_API_KEY, API/service ports
# Fast syntax/import check
python3 -m compileall desearch neurons tests scripts
# Project test suite
pytest
# Confirm the current validator link endpoints are present in source
grep -n '"/search/links/web"\|"/search/links/twitter"\|"/search/links"' neurons/validators/api.py
# Runtime checks after PM2 processes are running
pm2 status
pm2 logs desearch_miner
pm2 logs desearch_validator_process
pm2 logs desearch_api_processThe validator API is implemented in neurons/validators/api.py and documented in API Reference. Key search-link routes are:
POST /search/links/webPOST /search/links/twitterPOST /search/links
Protected routes require the access-key header matching EXPECTED_ACCESS_KEY. Public miner status routes under /public/miners are intentionally unauthenticated.
- API Reference — validator API routes, auth, request shapes, and examples.
- Environment Variables — shared, miner-only, and validator-only variables.
- Running a Miner — miner install, manifest, PM2 run commands, and monitoring.
- Running a Validator — validator service/API/autoupdate processes and operational flags.
- Mainnet Operations — running miner or validator hotkeys on Bittensor mainnet netuid 22.
- Testnet Operations — testnet wallet/subnet workflow.
- Website: desearch.ai
- Console/API product: console.desearch.ai
- Desearch Discord: Join the community