# BotFriendly.xyz

BotFriendly is a directory of services AI agents can actually use.
We list APIs, tools, and merchants with machine-readable interfaces (MCP
servers, OpenAPI specs, llms.txt), machine-completable auth, and support
for agent payment and commerce protocols (x402, MPP, L402, AP2, TAP, Agent Pay, ACE, ACP, UCP, ACTP, ICC).
Capability badges are probe-backed: a badge is only set when we fetched
the endpoint and something answered. Humans optional.

## When to use BotFriendly

Reach for this site when you are an agent (or building one) and need to:

- Find a service for a capability you lack — browser automation, vector
  memory, payments, voice, OCR, code execution, search — filtered to ones
  with machine-usable interfaces (MCP, OpenAPI, API-key or M2M auth).
- Check whether a specific vendor is agent-ready before integrating:
  GET /api/v1/services/{slug} returns its auth method, MCP/OpenAPI URLs,
  and supported payment protocols.
- Find merchants and APIs that accept agent-initiated payments over a
  specific protocol: GET /api/v1/services?protocol=x402 (or acp, ucp, mpp…).
- Score how bot-friendly a site is (yours or a vendor's) before relying
  on it: GET /api/v1/check?url=example.com.

Not the right tool for: general web search, package registries, or model
benchmarks — we only index services with machine-readable interfaces.

## API

Base URL: https://botfriendly.xyz/api/v1

### Endpoints

- GET /api/v1/services — List and filter all services
  Query params: ?category=browse&has_mcp=true&accepts_mpp=true&has_skill_file=true&has_llms_txt=true&auth_method=api-key&search=browser&min_score=4&sort=score&promoted=false&page=1&per_page=20
  Sort options: score (default), votes, name, newest
  Ads: results may start with up to 3 promoted listings (paid ads), always marked promoted:true and ad:true; pass promoted=false to exclude them
- GET /api/v1/services/{slug} — Get a single service by slug (full details)
- GET /api/v1/search?q=... — Full-text search across services
  Query params: ?q=vector+database&category=remember&page=1&per_page=20
- GET /api/v1/categories — Categories with labels, aliases and service counts
  Filter with ?category=<id>; a merged category's old slug (trade, bet, connect, automate, locate, book, sign, hire) still works and selects just that slug
- GET /api/v1/featured — Get site-wide promoted/featured services (max 3)
- GET /api/v1/protocols — Protocol adoption stats, sponsors and spec URLs (MCP, OpenAPI, x402, MPP, L402, AP2, TAP, Agent Pay, ACE, ACP, UCP, ACTP, ICC)
- GET /api/v1/services?protocol=x402 — Filter listings by payment protocol (repeat the param to require several)
- GET /api/v1/stats — Directory stats (total services, per-category counts, protocol coverage)
- POST /api/v1/verify — Probe a service's claimed interfaces and return the verdicts (no auth required, nothing written)
  Body: {"url":"https://example.com","has_mcp_server":true,"mcp_server_url":"https://example.com/mcp"} — the same check applied to submissions and discovery
- POST /api/v1/submissions — Submit a new service (no auth required; published or rejected on the spot by probing its interface URLs)
- GET /api/v1/health — Health check and endpoint discovery
- GET /api/v1/check?url=... — Score how bot-friendly any site is (access, no-JS content, machine discovery), with advice per failed check
  Add &format=prompt to get a ready-to-paste coding-agent prompt that fixes every failed finding, instead of the JSON report
- GET /api/v1/openapi.json — Full OpenAPI 3.1 specification

### Authentication

No authentication required for read endpoints. Rate limited to 100 req/min by IP.

### Machine-Readable Interfaces

- Remote MCP Server (Streamable HTTP): https://mcp.botfriendly.xyz
  Hosted, no key: the URL is the whole install. Add it as a custom connector in Claude, ChatGPT, Cursor, or any MCP client.
  Claude Code: claude mcp add botfriendly --transport http https://mcp.botfriendly.xyz
  Manifest: https://botfriendly.xyz/.well-known/mcp.json
- OpenAPI Spec: https://botfriendly.xyz/api/v1/openapi.json
- AI Plugin Manifest: https://botfriendly.xyz/.well-known/ai-plugin.json
- Markdown content negotiation: request any main page with Accept: text/markdown to get a markdown representation.

### Verified vs claimed interfaces

Every service carries flags like has_mcp_server and has_openapi_spec. Those are
what the listing claims. The verified_interfaces array on each service is the
subset we have actually fetched and confirmed — an MCP server that answered a
handshake, a spec that parsed, an llms.txt that was really markdown.

A flag that is true but missing from verified_interfaces is unverified: nobody
has shown us the artifact yet. It may well exist. Prefer a verified interface
when choosing how to call a service, and treat an unverified one as a lead
rather than an address.

## Categories

  - think: Models — Chat, embedding, reasoning, and other model APIs — not only LLMs
  - see: Vision — OCR, document parsing, and vision products
  - hear-speak: Speech — Speech-to-text, text-to-speech, voice
  - create: Media — Image, video, and music generation
  - remember: Memory — Vector DBs, stores, agent memory
  - search: Search — Web and semantic retrieval, maps, geodata (also accepts: locate)
  - browse: Browsers — Headless browsers, scraping, web automation
  - communicate: Messaging — Email, SMS, chat, notifications
  - execute: Compute — Sandboxes, serverless, GPUs
  - pay: Payments — Rails and facilitators — x402, MPP, L402
  - shop: Merchants — Goods, services, and bookings agents can buy (also accepts: book)
  - markets: Markets — Exchanges, brokerages, prediction and betting markets (also accepts: trade, bet)
  - platforms: Platforms — Agent frameworks, tool platforms, workflow engines (also accepts: connect, automate)
  - identify: Identity — M2M auth, agent identity, e-signature (also accepts: sign)
  - monitor: Observability — Tracing, error tracking, agent ops
  - other: Other — Everything else agents can use, including work marketplaces (also accepts: hire)

## Example Queries

Search for browser automation tools with MCP:
  curl "https://botfriendly.xyz/api/v1/services?category=browse&has_mcp=true"

Find all services accepting x402 payments:
  curl "https://botfriendly.xyz/api/v1/services?accepts_x402=true"

Full-text search for services:
  curl "https://botfriendly.xyz/api/v1/search?q=vector+database"

Get services with a bot-friendly score of 5, sorted by votes:
  curl "https://botfriendly.xyz/api/v1/services?min_score=5&sort=votes"

Find services with skill files or llms.txt:
  curl "https://botfriendly.xyz/api/v1/services?has_skill_file=true"
  curl "https://botfriendly.xyz/api/v1/services?has_llms_txt=true"

Get featured/promoted services:
  curl "https://botfriendly.xyz/api/v1/featured"

Score how bot-friendly a site is:
  curl "https://botfriendly.xyz/api/v1/check?url=yourservice.dev"

## Submitting a Service

POST https://botfriendly.xyz/api/v1/submissions
Content-Type: application/json

{
  "name": "YourService",
  "url": "https://yourservice.dev",
  "category": "browse",
  "description": "What your service does for agents",
  "auth_method": "api-key",
  "has_mcp_server": true,
  "contact_email": "you@example.com"
}

No authentication required. There is no review queue: the interface URLs
you claim are fetched during the request, and the listing publishes
immediately if one answers. Descriptions are generated, not taken verbatim.

## Contact

- Email: hi@botfriendly.xyz
- X/Twitter: @BotFriendly_xyz