Skip to content

DISCOVERY.md

Latest commit

 

History

History
204 lines (137 loc) · 4.58 KB

DISCOVERY.md

File metadata and controls

204 lines (137 loc) · 4.58 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)
  3. DNS _x402 TXT pointer (compatibility)

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

TL;DR

Discovery precedence used by x402scan:

  1. OpenAPI (/openapi.json, then /.well-known/openapi.json)
  2. /.well-known/x402
  3. DNS _x402 TXT pointer

Runtime 402 behavior is authoritative over static metadata.

A) OpenAPI-First Discovery (Recommended)

Supported URLs:

  • https://yourdomain.com/openapi.json
  • https://yourdomain.com/.well-known/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:
    • pricingMode: "fixed" + price
    • or pricingMode: "range" + minPrice + maxPrice
    • or pricingMode: "quote"

Auth requirements

Use OpenAPI security + components.securitySchemes.

Legacy x-agentcash-auth.mode is accepted as a migration fallback, but is not recommended for new integrations.

Optional top-level metadata

Use x-discovery:

{
  "x-discovery": {
    "ownershipProofs": ["0x..."],
    "llmsTxtUrl": "https://yourdomain.com/llms.txt"
  }
}

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) DNS _x402 Pointer (Compatibility)

Example TXT record:

_x402.yourdomain.com TXT "v=x4021;url=https://yourdomain.com/.well-known/x402"

Notes:

  • DNS is compatibility-only; do not prefer it over OpenAPI.
  • Keep payload URL stable and cache-friendly.

D) 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.

llms.txt Guidance

llms.txt is optional and unstructured.

Use it for concise cross-route human/agent guidance. Keep machine-parseable contract data in OpenAPI.

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 + DNS compat during migration.
  4. Remove compat paths when your consumers no longer depend on them.