[Feature Request] Standardize .well-known/x402 endpoint for direct origin discovery

[1bcMax]

Summary

Propose adding a standard /.well-known/x402 endpoint to the x402 specification, enabling direct discovery of x402-enabled services without relying on facilitators.

Background

Currently, x402 v2 uses Bazaar Discovery via facilitators:

1. Services declare metadata via SDK extensions
2. Facilitators catalog during payment processing
3. Clients query GET {facilitator}/discovery/resources

However, there's no standard way to discover services directly from the origin. Some projects have implemented their own versions:

Live Example: BlockRun

URL: https://blockrun.ai/.well-known/x402

curl https://blockrun.ai/.well-known/x402

Response:

{
  "x402Version": 2,
  "name": "BlockRun",
  "description": "Crypto-native AI gateway for permissionless LLM access via x402 micropayments on Base",
  "version": "0.1.0",
  "resource": {
    "url": "https://api.blockrun.ai",
    "description": "BlockRun AI Gateway API",
    "mimeType": "application/json"
  },
  "services": [
    {
      "name": "LLM Chat Completion",
      "endpoint": "/v1/chat/completions",
      "method": "POST",
      "description": "Access 20+ frontier LLMs with pay-per-request x402 micropayments",
      "models": [
        {
          "id": "openai/gpt-5.2",
          "name": "GPT-5.2",
          "provider": "openai",
          "contextWindow": 400000,
          "maxOutput": 128000,
          "categories": ["chat", "reasoning", "coding", "vision"]
        }
        // ... 20+ more models
      ],
      "pricing": {
        "openai/gpt-5.2": { "inputPerMillionTokens": "2.50", "outputPerMillionTokens": "10.00" }
      },
      "payment": {
        "network": "base",
        "networkName": "Base Mainnet",
        "chainId": 8453,
        "token": "USDC",
        "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "recipient": "0x...",
        "facilitator": "coinbase-cdp",
        "scheme": "exact",
        "maxTimeoutSeconds": 300
      },
      "authentication": {
        "type": "x402-wallet",
        "description": "Sign requests with your wallet private key - no API keys required",
        "walletBased": true
      },
      "features": [
        "OpenAI-compatible API",
        "No accounts or API keys required",
        "Permissionless access",
        "Pay-per-request micropayments"
      ]
    }
  ],
  "documentation": {
    "sdks": [{ "language": "TypeScript", "package": "@blockrun/llm" }]
  },
  "x402Features": [
    "wallet-based-identity",
    "auto-discovery",
    "transparent-pricing",
    "base-mainnet",
    "coinbase-cdp-facilitator"
  ]
}

Benefits of Standardization

1. Direct Discovery - Clients can discover services without querying facilitators
2. Self-Reported Metadata - Origins provide authoritative information
3. Offline Discovery - No dependency on facilitator availability
4. MCP Integration - AI agents can discover x402 services directly
5. Ecosystem Growth - Lower barrier for aggregators and discovery tools

Proposed Structure

interface X402WellKnown {
  // Required
  x402Version: number;
  name: string;

  // Optional metadata
  description?: string;
  version?: string;

  // Services/resources
  resources?: Array<{
    url: string;
    type: "http";
    method: string;
    description?: string;

    // Payment requirements
    accepts: Array<{
      scheme: "exact" | "subscription";
      network: string;  // CAIP-2 format: "eip155:8453"
      asset: string;
      payTo: string;
      maxAmountRequired: string;
      maxTimeoutSeconds: number;
    }>;

    // v2 Bazaar metadata
    metadata?: {
      input?: object;  // Example input
      output?: object; // Example output
      inputSchema?: object;  // JSON Schema
      outputSchema?: object; // JSON Schema
    };
  }>;

  // Optional
  facilitators?: string[];  // Preferred facilitators
  documentation?: {
    url?: string;
    sdks?: Array<{ language: string; package: string }>;
  };
}

Use Cases

1. AI Agent Discovery

// Agent discovers x402 services directly
const response = await fetch('https://api.example.com/.well-known/x402');
const services = await response.json();
// Agent can now understand available endpoints and pricing

2. Aggregator Indexing

// Discovery service probes origins directly
for (const domain of knownOrigins) {
  const wellknown = await fetch(`https://${domain}/.well-known/x402`);
  if (wellknown.ok) {
    await index(domain, await wellknown.json());
  }
}

3. IDE/Tooling Integration

// IDE can show available x402 endpoints with pricing
const x402Info = await fetchWellKnown(projectUrl);
// Display in autocomplete with cost estimates

Questions for Discussion

1. Should this be part of core x402 or an optional extension?
2. How should it interact with Bazaar discovery?
3. Should facilitator preference be includable?
4. Caching recommendations (Cache-Control headers)?

Related

• x402 Bazaar Discovery: https://docs.cdp.coinbase.com/x402/bazaar
• RFC 8615 Well-Known URIs: https://www.rfc-editor.org/rfc/rfc8615
• OAuth 2.0 uses /.well-known/oauth-authorization-server
• OpenID uses /.well-known/openid-configuration

---

[ruhil6789]

Hi @1bcMax,
Great proposal! I'd like to work on implementing the .well-known/x402 endpoint standardization. This would complement the existing Bazaar discovery and enable direct origin discovery as you've outlined.

Implementation Plan:

1. Core Implementation (@x402/core):

   • Add WellKnownX402 type definition matching the proposed interface
   • Add method to x402ResourceServer to generate well-known response from registered routes
   • Add optional configuration for well-known metadata (name, description, etc.)

2. HTTP Integration (@x402/http/ packages):

   • Add automatic route handler for GET /.well-known/x402 in x402HTTPResourceServer
   • Ensure it bypasses payment requirements (public endpoint)
   • Add proper Cache-Control headers as per RFC 8615

3. Framework Integrations:

   • Express: Auto-register .well-known/x402 route
   • Hono: Auto-register .well-known/x402 route
   • Next.js: Auto-register .well-known/x402 route
   • Fetch: Handle in fetch wrapper

4. Specification Update:

   • Add section to specs/x402-specification-v2.md documenting the endpoint
   • Include examples and use cases

5. Tests:

   • Unit tests for well-known response generation
   • Integration tests for each framework
   • Test caching behavior

Questions:

• Should this be opt-in or opt-out? (I'd suggest opt-in via config)
• Should it include all registered routes or allow filtering?
• How should it interact with Bazaar extensions? (Should it include Bazaar metadata if present?)

I can start with the core implementation and TypeScript framework integrations. Would you like me to proceed?