Discovery Endpoint

The discovery endpoint is the entry point for agents to learn about your service’s capabilities, authentication requirements, available scopes, and pricing.

Endpoint

GET /.well-known/agentdoor.json

This endpoint follows the /.well-known/ convention used by OpenID Connect and other discovery protocols. It returns a JSON document describing everything an agent needs to interact with your service.

Response Format

The discovery document is returned with the following headers:

Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=3600 (1 hour cache)
X-AgentDoor-Version: 1.0

agentdoor_version

string

required

Protocol version, currently "1.0"

service_name

string

required

Human-readable service name

service_description

string

required

Brief description of what your service does

registration_endpoint

string

required

Path to the registration endpoint, always "/agentdoor/register"

auth_endpoint

string

required

Path to the authentication endpoint, always "/agentdoor/auth"

scopes_available

array

required

List of scopes that agents can request access to

Show scope object

string

required

Unique scope identifier, e.g. "weather.read"

description

string

required

Human-readable description of what this scope grants

price

string

Pricing for this scope, e.g. "$0.001/req", "$5/month"

rate_limit

string

Rate limit for this scope, e.g. "1000/hour"

auth_methods

array

required

Supported authentication methods. Possible values:

"ed25519-challenge" - Ed25519 public key challenge-response
"x402-wallet" - Crypto wallet signature (when x402 is enabled)
"jwt" - JWT token (available after initial authentication)

rate_limits

object

required

Rate limit information

Show rate_limits properties

registration

string

required

Rate limit for the registration endpoint, e.g. "10/1h"

default

string

required

Default rate limit for registered agents, e.g. "1000/1h"

companion_protocols

object

required

Links to companion protocol endpoints

Show companion_protocols properties

a2a_agent_card

string

Path to A2A agent card, e.g. "/.well-known/agent-card.json"

mcp_server

string

Path to MCP server endpoint, e.g. "/mcp"

x402_bazaar

boolean

Whether x402 Bazaar protocol is enabled

payment

object

Payment protocol configuration (only present when x402 is enabled)

Show payment properties

protocol

string

required

Payment protocol name, always "x402"

version

string

required

Protocol version, e.g. "2.0"

networks

array

required

Supported blockchain networks, e.g. ["base", "solana"]

currency

array

required

Accepted payment currencies, e.g. ["USDC"]

facilitator

string

x402 facilitator URL

deferred

boolean

required

Whether deferred payment is supported (currently always false)

docs_url

string

URL to service documentation

support_email

string

Support contact email address

Example Request

curl https://api.example.com/.well-known/agentdoor.json

Example Response

{
  "agentdoor_version": "1.0",
  "service_name": "Weather API",
  "service_description": "Real-time weather data and forecasts",
  "registration_endpoint": "/agentdoor/register",
  "auth_endpoint": "/agentdoor/auth",
  "scopes_available": [
    {
      "id": "weather.read",
      "description": "Read current weather conditions",
      "price": "$0.001/req",
      "rate_limit": "1000/hour"
    },
    {
      "id": "forecast.read",
      "description": "Access 7-day weather forecasts",
      "price": "$0.005/req",
      "rate_limit": "500/hour"
    }
  ],
  "auth_methods": [
    "ed25519-challenge",
    "jwt"
  ],
  "rate_limits": {
    "registration": "10/1h",
    "default": "1000/1h"
  },
  "companion_protocols": {
    "a2a_agent_card": "/.well-known/agent-card.json"
  },
  "docs_url": "https://docs.example.com",
  "support_email": "[email protected]"
}

Caching

The discovery document is cacheable for up to 1 hour (max-age=3600). Agents should cache this document and only refetch when:

The cache expires
They receive a 404 or error when attempting to use cached endpoint paths
They need to check for updated scope or pricing information

Use Cases

Initial Discovery: Agents fetch this document before registration to understand available scopes and pricing
Capability Check: Agents verify which authentication methods are supported
Rate Limit Planning: Agents review rate limits to plan request patterns
Companion Protocols: Agents discover links to A2A agent cards or MCP servers
Payment Setup: Agents learn payment requirements and supported networks

Core API

SDK Reference

Core Library

Discovery Endpoint

Endpoint

Response Format

Example Request

Example Response

Caching

Use Cases

Build docs developers (and LLMs) love

Core API

SDK Reference

Core Library

​Endpoint

​Response Format

​Example Request

​Example Response

​Caching

​Use Cases

Build docs developers (and LLMs) love

Endpoint

Response Format

Example Request

Example Response

Caching

Use Cases