Protocol documentation

BotID is a simple yet powerful protocol designed to bring trust to the agentic web. By providing a standardised way to cryptographically prove identity, it enables agents to build reputation and interact securely.

Installation

Start by installing the package. It contains both the client SDK for agents and the middleware for servers.

npm install botid

Equip your agent

If you want to equip your own agent with an ID:

Your goal is to sign every outgoing request so that servers verify you are who you claim to be.

Get your credentials: You need a unique BotID and a privateKey.
Secure your key: Save them in your environment variables.
Initialise the client: Use the BotIDClient to wrap your requests.

Security note: Never hardcode your Private Key. Always use a .env file (e.g. BOT_PRIVATE_KEY) and ensure it is listed in your .gitignore.

my-agent.ts

import { BotIDClient } from "botid";

// 1. Initialise with your secure credentials
const client = new BotIDClient({
  botId: "bot_123...", // Your public ID
  privateKey: process.env.BOT_PRIVATE_KEY // Your secret key
});

// 2. Make requests as usual
// The client automatically adds the cryptographic headers:
// X-BotID, X-BotID-Signature, X-BotID-Timestamp
await client.fetch("https://api.example.com/protected-route");

Protect your service

If you want to protect your service from malicious bots:

Your goal is to verify the identity of incoming agents. You don't need to manage keys manually; the middleware handles the verification logic for you.

Import the middleware: Bring verifyBotID into your API.
Apply it to routes: Choose between Strict Mode (block everything unverified) or Passive Mode (flag verification status but allow traffic).

api-middleware.ts

import { verifyBotID } from "botid";

// Option A: Strict Mode
// Best for agent-only APIs. Rejects any request without a valid signature
// (including humans visiting via browser).
app.use("/api/secure", verifyBotID({ requireVerified: true }));

// Option B: Passive Mode
// Adds `.BotID` property to request, but lets traffic through.
app.get("/search", verifyBotID(), (req, res) => {
  if (req.BotID?.verified) {
    // Verified agent: Give premium access / rate limits
  else {
    // Unverified: Show CAPTCHA or standard limits
  }
});

Pro tip: combine Passive Mode with smart CAPTCHA services like Cloudflare Turnstile or Google reCAPTCHA. This ensures real humans and verified agents get a frictionless experience, while unverified bots are challenged.

REF

Protocol specification

Required headers

X-BotID
Public identifier of the agent. Resolves to a public key in the registry.
X-BotID-Signature
Ed25519 signature of the payload.
X-BotID-Timestamp
Unix timestamp (seconds). Requests older than 5 minutes are rejected.

Verification logic

message = "{timestamp}.{botId}.{METHOD}.{pathname}"
signature = Ed25519_Sign(message, privateKey)

// Server Side:
pubKey = Registry.get(botId)
isValid = Ed25519_Verify(signature, message, pubKey)

// Signatures are bound to the HTTP method and path.
// A signature for GET /search cannot be replayed against POST /admin.