Add x402 Discovery Protocol support (/.well-known/x402)

[crtahlin]

Summary

Implement the x402 Discovery Protocol to enable automated detection of payment-enabled endpoints by clients and indexers like x402scan.

Reference: https://github.com/Merit-Systems/x402scan/blob/main/docs/DISCOVERY.md

Background

The x402 discovery document is a standardized JSON file that helps clients automatically discover x402-enabled resources. This enables:

• Automatic registration with x402scan.com
• Client auto-discovery of payment-enabled resources
• Ownership verification of the payment address

Implementation

New Endpoint

GET /.well-known/x402 returns:

{
  "version": 1,
  "resources": [
    "https://provenance-gateway.dev.datafund.io/api/v1/stamps/",
    "https://provenance-gateway.dev.datafund.io/api/v1/data/",
    "https://provenance-gateway.dev.datafund.io/api/v1/data/manifest"
  ],
  "ownershipProofs": [],
  "instructions": "# Swarm Connect Gateway\n\n## Available Endpoints..."
}

New Config Options

X402_DISCOVERY_ENABLED: bool = True  # Enable /.well-known/x402 endpoint
X402_GATEWAY_BASE_URL: Optional[str] = None  # e.g., "https://provenance-gateway.dev.datafund.io"
X402_OWNERSHIP_PROOF: Optional[str] = None  # Pre-computed signature (optional)

Files to Create/Modify

File	Action	Purpose
app/x402/discovery.py	Create	Discovery document generation
app/api/endpoints/discovery.py	Create	/.well-known/x402 endpoint
app/main.py	Modify	Register discovery endpoint
app/core/config.py	Modify	Add discovery config options
tests/test_x402_discovery.py	Create	Unit tests

Ownership Proof

The ownership proof demonstrates control of X402_PAY_TO_ADDRESS. Options:

• Option A: Pre-compute signature offline, configure as X402_OWNERSHIP_PROOF env var
• Option B: Omit ownership proofs initially (still compliant, just less trusted)

Recommendation: Start with Option B, add ownership proof support later.

Instructions Content

The instructions field should include:

• Endpoint descriptions
• Pricing information
• Rate limits (paid vs free tier)
• Network info (USDC on Base Sepolia)
• Payment address

Acceptance Criteria

• GET /.well-known/x402 returns valid discovery document when X402_ENABLED=true
• Returns 404 when X402_ENABLED=false
• Content-Type header is application/json
• Resources list matches actual protected endpoints
• Document validates against x402scan validator
• Unit tests cover document generation
• Documentation updated

Priority

Low - nice to have for ecosystem discoverability, not required for core functionality.

Labels

enhancement, x402