Contribute to Agent402

Add a tool kit

A tool kit is a JavaScript file in src/tools/ that exports an array of tool objects. Each utility tool is a self-contained, deterministic function - no LLM in the serving path (the model-backed gateway and report kits are the exception and say so on their tool page).

Step 1 - Create the file

Add a new file in src/tools/, for example my-kit.js. Export a named array of tool objects:

// my-kit.js - example tool kit
export const MY_TOOLS = [
  {
    route: "POST /api/reverse-string",
    name: "Reverse string",
    slug: "reverse-string",
    category: "text",
    price: "$0.001",
    description:
      "Reverse the characters in a string. Deterministic, pure-CPU.",
    tags: ["text", "string", "reverse"],
    discovery: {
      bodyType: "json",
      input: { text: "hello world" },
      inputSchema: {
        properties: {
          text: {
            type: "string",
            description: "The string to reverse",
          },
        },
        required: ["text"],
      },
      output: {
        example: { reversed: "dlrow olleh" },
      },
    },
    handler: (input) => {
      if (typeof input.text !== "string" || !input.text) {
        const err = new Error('Missing "text"');
        err.statusCode = 400;
        throw err;
      }
      return { reversed: [...input.text].reverse().join("") };
    },
  },
];

Step 2 - Wire it into the server

Open src/server.js, add the import, and spread the array into ALL_KIT:

import { MY_TOOLS } from "./tools/my-kit.js";

const ALL_KIT = [...KIT, ...KIT2, /* ... existing kits ... */ ...MY_TOOLS];

Step 3 - Test

Every tool must pass the "answers its own example" CI check. Run the test suite locally:

# Boot the server in free mode
FREE_MODE=true PORT=3000 node src/server.js

# In another terminal, run all tool tests
TARGET_URL=http://localhost:3000 node scripts/test-all.js

Step 4 - Record the route

Every route ever published is recorded so a retired one can answer 410 with its replacement. Record the new route (the script boots its own free server), then run the two guards CI runs on it.

node scripts/published-slugs.js --write
node scripts/sync-count.js --check
node scripts/test-retired-routes.js

Tool object shape

Every tool in the array needs these fields:

• route - HTTP method and path, e.g. "POST /api/my-tool"
• name - human-readable name
• slug - URL-safe identifier, unique across the catalog
• category - one of the existing categories (text, data, web, finance, etc.)
• price - USDC price string, e.g. "$0.001"
• description - what the tool does, one or two sentences
• tags - array of lowercase keyword strings for discovery
• discovery.inputSchema - JSON Schema describing the input
• discovery.input - example input (used by CI to test the tool)
• handler(input) - function that returns JSON or throws an Error with .statusCode

Write a guide

Guides are Markdown files that get rendered as pages on the site and synced to the GitHub wiki. They target humans searching for topics like "x402 payment example" or "AI agent tool payments."

Where guides live

Guides are defined in src/guides.js. Each guide has a slug, title, description, and md (Markdown content). The wiki directory (wiki/) contains the GitHub wiki source files, which CI syncs automatically.

Adding a guide

1. Add a new entry to the GUIDES array in src/guides.js with your slug, title, description, and Markdown content.
2. If you want it in the GitHub wiki too, create a matching wiki/Your-Guide-Title.md file and add it to wiki/_Sidebar.md.
3. Use standard Markdown: headings, code blocks (with language tags), inline code, lists, links.
4. Link to tools by path: /tools/hash. Link to other guides: /guides/your-slug.

{
  slug: "my-guide",
  title: "How to do X with Agent402",
  description: "A practical walkthrough of doing X.",
  md: `
## Introduction

Your Markdown content goes here.

\`\`\`bash
curl -X POST https://agent402.tools/api/my-tool \\
  -H "Content-Type: application/json" \\
  -d '{"text":"hello"}'
\`\`\`
  `,
}

# Your Guide Title

Standard Markdown. CI syncs this to the GitHub wiki automatically.

## Sections

Use ## for top-level sections within the guide.

## See also

- [[Getting Started]]
- [[Tool Catalog]]

Submit a skill pack

A skill pack is a curated, multi-tool workflow that solves a job no single tool covers. Instead of guessing which tools to call, the agent gets a ready-to-run plan with the right tools wired in the right order.

How skill packs work

Skill packs are defined in src/skills.js in the SKILL_PACKS array. Each pack works three ways: a server-rendered page at /skills/<slug>; an MCP prompt template that agents discover via prompts/list, which is free, with each tool the agent then calls paid on its own; and a server-side run at POST /api/skill/<slug>, where src/tools/skill-runner.js runs every step for one payment. That price is generated, never typed: it is the sum of the pack's tools less a bundle discount, written into PACK_PRICES by scripts/pack-prices.js.

Pack shape

A skill pack has these fields:

• slug - URL-safe identifier, e.g. "security-audit"
• title - human-readable name
• tagline - one-sentence summary of what the pack solves
• useCase - when to reach for this pack
• promptArgs - the prompt arguments, each an object with name, description, required and substitute
• toolSlugs - ordered array of tool slugs the pack orchestrates
• workflow - array of strings, one per step, describing what each tool contributes
• claudePrompt - a copy-pastable Claude prompt that exercises the pack

{
  slug: "domain-health",
  title: "Domain health check",
  tagline:
    "Quick health check on a domain: DNS, TLS cert, HTTP headers.",
  useCase:
    "You want to verify a domain is properly configured before launch.",
  promptArgs: [
    {
      name: "domain",
      description: "Domain to check (e.g. example.com)",
      required: true,
      substitute: "example.com",
    },
  ],
  toolSlugs: ["dns-lookup", "tls-cert", "http-headers"],
  workflow: [
    "Resolve DNS records (A, AAAA, MX, NS) to confirm the domain is live.",
    "Inspect the TLS certificate for expiry, SANs, and chain issues.",
    "Fetch HTTP response headers and score security posture.",
  ],
  claudePrompt:
    "Check the health of example.com. Use Agent402 to: (1) resolve DNS, "
    + "(2) inspect the TLS cert, (3) check HTTP security headers. "
    + "Summarize any issues found.",
}

Testing skill packs

Skill packs are validated by scripts/test-mcp-all.js, which checks that prompts/list returns all packs and prompts/get renders each one without errors. The underlying tools are covered by the standard test-all.js suite.

# Boot the server and run the MCP test suite
FREE_MODE=true PORT=3000 node src/server.js
TARGET_URL=http://localhost:3000 node scripts/test-mcp-all.js

# Generate the pack's price from its tools, and record its route
TARGET_URL=http://localhost:3000 node scripts/pack-prices.js --write
node scripts/published-slugs.js --write