Skip to content

DISCOVERY.md

Latest commit

 

History

History
175 lines (118 loc) · 3.86 KB

DISCOVERY.md

File metadata and controls

175 lines (118 loc) · 3.86 KB

x402scan Discovery & Registration Spec

This spec defines how x402scan discovers and registers resources.

If you want reliable pickup, implement discovery in this order:

  1. OpenAPI-first (recommended)
  2. /.well-known/x402 (compatibility)

If you cannot expose discovery yet, endpoint-only manual registration still works.

TL;DR

Discovery precedence used by x402scan:

  1. OpenAPI (/openapi.json)
  2. /.well-known/x402

Runtime 402 behavior is authoritative over static metadata.

A) OpenAPI-First Discovery (Recommended)

Supported URLs:

  • https://yourdomain.com/openapi.json

Required top-level fields

  • openapi (string)
  • info.title (string)
  • info.version (string)
  • paths (object)

Per-paid-operation requirements

For each paid operation:

  • declare x-payment-info
  • include a 402 response in responses
  • include x-payment-info.protocols (for example "x402")
  • include valid pricing metadata via x-payment-info.price:
    • fixed: { mode: "fixed", currency: "USD", amount: "0.05" }
    • dynamic: { mode: "dynamic", currency: "USD", min: "0.01", max: "1.00" }

Auth requirements

Use OpenAPI security + components.securitySchemes.

Optional top-level metadata

Use x-discovery:

{
  "x-discovery": {
    "ownershipProofs": ["0x..."]
  }
}

B) /.well-known/x402 Fan-Out (Compatibility)

Endpoint:

GET https://yourdomain.com/.well-known/x402

Minimal payload:

{
  "version": 1,
  "resources": [
    "https://yourdomain.com/api/route-1",
    "https://yourdomain.com/api/route-2"
  ]
}

Optional fields:

{
  "version": 1,
  "resources": ["https://yourdomain.com/api/route-1"],
  "ownershipProofs": ["0x..."],
  "instructions": "Optional legacy guidance"
}

C) Endpoint-Only Registration (Fallback)

Use this when discovery docs are not available yet.

A route is registerable when probing returns 402 with a parseable x402 challenge.

Accepted challenge transport:

  • Payment-Required header (x402 v2), or
  • JSON response body (legacy compatibility)

For payable indexing in x402scan, challenge data should include:

  • non-empty accepts
  • Bazaar-style input schema (extensions.bazaar.info + schema-derived input)

Compatibility behavior:

  • 402 + accepts: [] + extensions["sign-in-with-x"] => SIWX auth-only, marked skipped.
  • Missing input schema => strict non-invocable, marked skipped.

Ownership Proofs

Accepted locations:

  • OpenAPI x-discovery.ownershipProofs (preferred)
  • /.well-known/x402 ownershipProofs (compatibility)

Registration Flow in x402scan

When a user clicks Add Server:

  1. Run discovery with precedence above.
  2. Probe discovered URLs with method-aware fallback.
  3. Parse x402 challenge.
  4. Register valid routes.
  5. Mark non-conformant routes as failed/skipped with explicit reasons.

When a user clicks Register This URL Only:

  • Skip fan-out.
  • Register only that endpoint.
  • Useful for partial rollouts and rate-limited providers.

Common Failure Reasons

  • Expected 402, got 404/405/429
  • parseResponse: Accepts must contain at least one valid payment requirement
  • parseResponse: Missing input schema
  • discovery fetch/parse failures for OpenAPI or /.well-known/x402

429 responses are upstream provider limits, not generated by x402scan.

Validation Commands

Full discovery audit:

npx -y @agentcash/discovery yourdomain.com -v

Single endpoint probe:

curl -i -X POST https://yourdomain.com/api/route
curl -i -X GET https://yourdomain.com/api/route

Recommended Migration Order

  1. Ensure routes return valid x402 challenges (402, parseable, non-empty accepts for payable routes).
  2. Add OpenAPI discovery + x-payment-info + security declarations.
  3. Keep /.well-known/x402 compat during migration.
  4. Remove compat paths when your consumers no longer depend on them.