@asterpay/agent-ready

agent-ready

Make any API AI-agent discoverable in one line.

agent-ready auto-generates everything AI agents need to find and use your API:

• robots.txt — welcomes AI crawlers (GPTBot, ClaudeBot, etc.)
• llms.txt — human-readable endpoint catalog
• agent.json — A2A agent card at /.well-known/agent.json
• MCP server card at /.well-known/mcp/server-card.json
• MCP JSON-RPC endpoint at POST /mcp
• Scanner filter — blocks vulnerability scanners
• CORS + security header presets

Works with Fastify, Express, and Next.js.

Install

npm install @asterpay/agent-ready

Quick Start

Fastify

import Fastify from 'fastify';
import { agentReady } from '@asterpay/agent-ready';

const app = Fastify();

await app.register(agentReady, {
  name: 'My API',
  description: 'Weather data for AI agents',
  baseUrl: 'https://api.example.com',
  endpoints: [
    {
      path: '/v1/weather',
      method: 'GET',
      description: 'Get current weather by city',
      free: true,
      params: {
        city: { type: 'string', required: true, description: 'City name' },
      },
    },
  ],
});

await app.listen({ port: 3000 });

Express

import express from 'express';
import { agentReadyExpress } from '@asterpay/agent-ready/express';

const app = express();
app.use(express.json());

app.use(agentReadyExpress({
  name: 'My API',
  description: 'Weather data for AI agents',
  baseUrl: 'https://api.example.com',
  endpoints: [
    {
      path: '/v1/weather',
      method: 'GET',
      description: 'Get current weather by city',
      free: true,
    },
  ],
}));

app.listen(3000);

Next.js (App Router)

// app/robots.txt/route.ts
import { createAgentReadyHandlers } from '@asterpay/agent-ready/nextjs';

const config = {
  name: 'My API',
  description: 'Weather data for AI agents',
  baseUrl: 'https://api.example.com',
  endpoints: [
    { path: '/api/weather', method: 'GET' as const, description: 'Get weather', free: true },
  ],
};

const handlers = createAgentReadyHandlers(config);

export const GET = () => handlers.robotsTxt();

// app/llms.txt/route.ts → export const GET = () => handlers.llmsTxt();
// app/.well-known/agent.json/route.ts → export const GET = () => handlers.agentJson();
// app/mcp/route.ts → export const POST = (req) => handlers.mcpEndpoint(req);
// app/health/route.ts → export const GET = () => handlers.health();

Configuration

interface AgentReadyConfig {
  name: string;             // API name
  description: string;      // What your API does
  baseUrl: string;          // Public URL

  endpoints: EndpointConfig[];  // Your API endpoints

  // Optional
  provider?: { name: string; url?: string; email?: string; organization?: string };
  version?: string;
  documentationUrl?: string;
  protocols?: string[];     // e.g. ['x402', 'mpp']
  chains?: string[];        // e.g. ['base', 'ethereum']
  tokens?: string[];        // e.g. ['USDC']

  features?: {
    robotsTxt?: boolean;      // default: true
    llmsTxt?: boolean;        // default: true
    agentJson?: boolean;      // default: true
    mcpEndpoint?: boolean;    // default: true
    mcpServerCard?: boolean;  // default: true
    scannerFilter?: boolean;  // default: true
    corsPreset?: boolean;     // default: true
    healthCheck?: boolean;    // default: true
  };

  payment?: {
    x402?: boolean;
    settlement?: 'EUR' | 'USD' | 'GBP';
  };

  scannerFilter?: {
    additionalUAs?: string[];
    additionalPaths?: string[];
    onScannerDetected?: (ua: string, path: string) => void;
  };
}

Endpoints

Each endpoint describes one route of your API:

{
  path: '/v1/kya/score',
  method: 'GET',
  description: 'Get AI agent trust score',
  free: true,                              // free = no payment required
  price: 0.01,                             // USD per call (for paid endpoints)
  params: {
    wallet: { type: 'string', required: true, description: 'Agent wallet address' },
  },
}

Scanner Filter

Automatically detects vulnerability scanners by user-agent and request path. Add custom rules:

app.use(agentReadyExpress({
  // ...config
  scannerFilter: {
    additionalUAs: ['my-internal-bot'],
    additionalPaths: ['/admin'],
    onScannerDetected: (ua, path) => {
      console.log(`Blocked scanner: ${ua} at ${path}`);
    },
  },
}));

Access req.isScanner in downstream handlers to conditionally handle scanner traffic.

Standalone Utilities

Use generators individually without the full middleware:

import {
  generateRobotsTxt,
  generateLlmsTxt,
  generateAgentJson,
  generateMcpServerCard,
  handleMcpRequest,
  isScannerUA,
  isScannerPath,
  getCorsPreset,
  getHelmetPreset,
} from '@asterpay/agent-ready';

What Gets Generated

After adding agent-ready, your API serves:

Path	Description
GET /robots.txt	Welcomes AI crawlers
GET /llms.txt	Endpoint catalog
GET /.well-known/agent.json	A2A agent card
GET /.well-known/mcp/server-card.json	MCP server card
POST /mcp	MCP JSON-RPC 2.0
GET /health	Health check

License

MIT