agents402

What it is

agents402 is the small contract between two parties on the agent web: a site offering machine-readable paid capabilities, and an AI agent empowered to buy them. It is a thin layer above the Lightning HTTP 402 Payment Required standard (L402), shaped for autonomous use rather than human-checkout flows.

The smallest implementation is a static JSON file at /.well-known/agents402.json, a route handler that issues an L402 challenge, and a wallet on either end. Everything else — pricing, policy, receipts, reputation — composes from there.

Install the agent side

The reference MCP server is published as @agents402/mcp. Drop it into any MCP-aware client and the first time your agent hits a paywall, it will walk you through pairing a Lightning wallet.

{
  "mcpServers": {
    "faregate": {
      "command": "npx",
      "args": [
        "-y",
        "@agents402/mcp"
      ]
    }
  }
}

The shape of it

{
  "version": "0.1",
  "service": {
    "name":     "Example Pub",
    "homepage": "https://example.com"
  },
  "actions": [
    {
      "id":            "ask.site_agent",
      "type":          "site_agent_query",
      "endpoint":      "https://example.com/api/actions/ask.site_agent",
      "method":        "POST",
      "price_msats":   3000,
      "input_schema":  { "type": "object", "properties": { "question": { "type": "string" } } },
      "risk":          "low"
    }
  ],
  "receipts": {
    "pubkey_hex": "302a300506032b6570032100…",
    "algorithm":  "ed25519"
  }
}

An agent fetches that manifest, picks an action, and POSTs to the endpoint with its input. The first request returns 402 with an L402 macaroon and a Lightning invoice. The agent pays the invoice, retries with the proof, and gets the result plus a signed receipt.

Why now

• ·Agent traffic dominates. A growing share of HTTP requests come from autonomous LLM agents, not humans. Consent and monetization are unsolved.
• ·Card rails fail at this scale. Sub-cent payments are uneconomic on Visa/Mastercard. CAPTCHA, 3DS, and account creation are hostile to agents.
• ·Stablecoins re-centralize.Most are controlled by a single issuer who sets rules and can freeze funds. The agent web shouldn't depend on anyone's permission.
• ·Lightning is finally fast and small.Mainnet settlements complete in < 2 s at fractions of a cent — across borders, with no gateway. The rail finally fits the customer.

What's in / out of scope

agents402 specifies the wire format for discovery, payment challenge, retry-with-proof, and signed receipts. It does not specify a wallet implementation, a reputation graph, or a global registry. Those are intentionally separate — wallets are pluggable, reputation is local-first, and there is no central authority.

Where to go next