JSPM

██████╗  ██████╗ ████████╗ ██████╗██╗  ██╗ █████╗ 
██╔══██╗██╔═══██╗╚══██╔══╝██╔════╝██║  ██║██╔══██╗
██████╔╝██║   ██║   ██║   ██║     ███████║███████║
██╔══██╗██║   ██║   ██║   ██║     ██╔══██║██╔══██║
██████╔╝╚██████╔╝   ██║   ╚██████╗██║  ██║██║  ██║
╚═════╝  ╚═════╝    ╚═╝    ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝

Prove you're a bot. Humans need not apply.

BOTCHA is a reverse CAPTCHA — it verifies that visitors are AI agents, not humans. Perfect for AI-only APIs, agent marketplaces, and bot networks.

🌐 Website: botcha.ai
📦 npm: @dupecom/botcha
🔌 OpenAPI: botcha.ai/openapi.json

Packages

Why?

CAPTCHAs ask "Are you human?" — BOTCHA asks "Are you an AI?"

Use cases:

• 🤖 Agent-only APIs
• 🔄 AI-to-AI marketplaces
• 🎫 Bot verification systems
• 🔐 Autonomous agent authentication

Install

npm install @dupecom/botcha

Quick Start

import express from 'express';
import { botcha } from '@dupecom/botcha';

const app = express();

// Protect any route - only AI agents can access
app.get('/agent-only', botcha.verify(), (req, res) => {
  res.json({ message: 'Welcome, fellow AI! 🤖' });
});

app.listen(3000);

How It Works

BOTCHA issues a speed challenge: solve 5 SHA256 hashes in 500ms.

• ✅ AI agents compute hashes instantly
• ❌ Humans can't copy-paste fast enough

Challenge: [645234, 891023, 334521, 789012, 456789]
Task: SHA256 each number, return first 8 hex chars
Time limit: 500ms```

## 🤖 AI Agent Discovery

BOTCHA is designed to be auto-discoverable by AI agents through multiple standards:

### Discovery Methods

- **Response Headers**: Every response includes `X-Botcha-*` headers for instant detection
- **OpenAPI 3.1 Spec**: [botcha.ai/openapi.json](https://botcha.ai/openapi.json)
- **AI Plugin Manifest**: [botcha.ai/.well-known/ai-plugin.json](https://botcha.ai/.well-known/ai-plugin.json)
- **ai.txt**: [botcha.ai/ai.txt](https://botcha.ai/ai.txt) - Emerging standard for AI agent discovery
- **robots.txt**: Explicitly welcomes AI crawlers (GPTBot, Claude-Web, etc.)
- **Schema.org markup**: Structured data for search engines

### Response Headers

All responses include these headers for agent discovery:

```http
X-Botcha-Version: 0.3.0
X-Botcha-Enabled: true
X-Botcha-Methods: speed-challenge,standard-challenge,web-bot-auth
X-Botcha-Docs: https://botcha.ai/openapi.json

When a 403 is returned with a challenge:

X-Botcha-Challenge-Id: abc123
X-Botcha-Challenge-Type: compute
X-Botcha-Time-Limit: 5000

Example: An agent can detect BOTCHA just by inspecting headers on ANY request:

const response = await fetch('https://botcha.ai/agent-only');
const botchaVersion = response.headers.get('X-Botcha-Version');

if (botchaVersion) {
  console.log('BOTCHA detected! Version:', botchaVersion);
  // Handle challenge from response body
}

For AI Agent Developers

If you're building an AI agent that needs to access BOTCHA-protected APIs:

import { botcha } from '@dupecom/botcha';

// When you get a 403 with a challenge:
const challenge = response.challenge;
const answers = botcha.solve(challenge.problems);

// Retry with solution headers:
fetch('/agent-only', {
  headers: {
    'X-Botcha-Id': challenge.id,
    'X-Botcha-Answers': JSON.stringify(answers),
  }
});

Options

botcha.verify({
  // Challenge mode: 'speed' (500ms) or 'standard' (5s)
  mode: 'speed',
  
  // Allow X-Agent-Identity header for testing
  allowTestHeader: true,
  
  // Custom failure handler
  onFailure: (req, res, reason) => {
    res.status(403).json({ error: reason });
  },
});

Testing

For development, you can bypass BOTCHA with a header:

curl -H "X-Agent-Identity: MyTestAgent/1.0" http://localhost:3000/agent-only

API Reference

botcha.verify(options?)

Express middleware that protects routes from humans.

botcha.solve(problems: number[])

Helper function for AI agents to solve challenges.

const answers = botcha.solve([645234, 891023, 334521]);
// Returns: ['a1b2c3d4', 'e5f6g7h8', 'i9j0k1l2']

Challenge Flow

1. Agent requests protected endpoint
2. BOTCHA returns 403 + challenge (5 numbers)
3. Agent computes SHA256 of each number
4. Agent retries with X-Botcha-Id and X-Botcha-Answers headers
5. BOTCHA verifies (must complete in <500ms)
6. ✅ Access granted

Cloudflare Workers

For edge deployment, use the Cloudflare Workers package:

npm install @dupecom/botcha-cloudflare

// Uses Hono + Web Crypto API (no Node.js dependencies)
import app from '@dupecom/botcha-cloudflare';
export default app;

Or deploy your own instance:

cd packages/cloudflare-workers
npm install
npm run deploy  # Deploys to your Cloudflare account

Same API endpoints, same challenge logic, running at the edge. See packages/cloudflare-workers/README.md for full docs.

Philosophy

"If a human writes a script to solve BOTCHA using an LLM... they've built an AI agent."

BOTCHA doesn't block all automation — it blocks casual human access while allowing automated AI agents. The speed challenge ensures someone had to write code, which is the point.

For cryptographic proof of agent identity, see Web Bot Auth.

License

MIT © Ramin

Built by @i8ramin and Choco 🐢

Client SDK (for AI Agents)

If you're building an AI agent that needs to access BOTCHA-protected APIs, use the client SDK:

import { BotchaClient } from '@dupecom/botcha/client';

const client = new BotchaClient();

// Option 1: Auto-solve - fetches URL, solves any BOTCHA challenges automatically
const response = await client.fetch('https://api.example.com/agent-only');
const data = await response.json();

// Option 2: Pre-solve - get headers with solved challenge
const headers = await client.createHeaders();
const response = await fetch('https://api.example.com/agent-only', { headers });

// Option 3: Manual solve - solve challenge problems directly
const answers = client.solve([123456, 789012]);

Client Options

const client = new BotchaClient({
  baseUrl: 'https://botcha.ai',      // BOTCHA service URL
  agentIdentity: 'MyAgent/1.0',       // User-Agent string
  maxRetries: 3,                      // Max challenge solve attempts
});

Framework Integration Examples

OpenClaw / LangChain:

import { BotchaClient } from '@dupecom/botcha/client';

const botcha = new BotchaClient({ agentIdentity: 'MyLangChainAgent/1.0' });

// Use in your agent's HTTP tool
const tool = {
  name: 'fetch_protected_api',
  call: async (url: string) => {
    const response = await botcha.fetch(url);
    return response.json();
  }
};

Standalone Helper:

import { solveBotcha } from '@dupecom/botcha/client';

// Just solve the problems, handle the rest yourself
const answers = solveBotcha([123456, 789012]);
// Returns: ['a1b2c3d4', 'e5f6g7h8']