API discovery

Paid APIs on ax402 gateways publish discovery documents automatically. Agents and indexes (AgentCash, X402Scan) fetch them from the gateway hostname — not the seller API.

Gateway routes (public, unpaid)

Route	Format
`GET https://{api-host}/openapi.json`	OpenAPI 3.1 + `x-payment-info` (AgentCash)
`GET https://{api-host}/.well-known/x402.json`	Origin manifest (x402 #2582)

{api-host} is the platform subdomain ({slug}.{platform_domain}) or any verified custom domain. Documents regenerate on each request from live endpoint config.

Ephemeral (TTL) and disabled endpoints are excluded.

Validate

npx -y @agentcash/discovery@latest check "https://myapi.example.com/"
npx -y @agentcash/discovery@latest discover "https://myapi.example.com/"

ax402 discovery urls --api-id API_ID --json
ax402 discovery check --url "https://myapi.example.com" --json

check validates a specific origin or route. discover catalogs paid routes from the origin OpenAPI.

API fields

API (`POST /apis`, `PUT /apis/{id}`)

Field	Type	Notes
`discovery_guidance`	string?	Maps to OpenAPI `info.x-guidance`
`discovery_contact_email`	string?	Overrides `info.contact.email`
`openapi_version`	string?	OpenAPI `info.version` (default `1.0.0`)

Contact email resolution: API override → verified owner email → omit.

Endpoint (`POST/PUT .../endpoints`)

Field	Type	Notes
`request_schema`	object?	JSON Schema for request body
`response_schema`	object?	JSON Schema for 200 response
`schema_source`	string?	Read-only: `openapi` \| `inferred` \| `manual`
`clear_schemas`	bool?	On update: clear and re-infer

Write semantics:

Create without schemas → infer minimal schemas (schema_source: inferred)
OpenAPI import → extract schemas when present (openapi)
Update with schemas → manual
clear_schemas: true → re-infer

Set or import a response_schema so AgentCash can advertise output shape on 402 probes.

`GET /apis/{id}/discovery`

{
  "primary_host": "myapi.example.com",
  "hosts": ["myapi.example.com", "api.mycompany.com"],
  "openapi_url": "https://myapi.example.com/openapi.json",
  "well_known_url": "https://myapi.example.com/.well-known/x402.json",
  "endpoint_count": 12,
  "discoverable_endpoint_count": 10,
  "host_urls": [
    {
      "host": "myapi.example.com",
      "openapi_url": "https://myapi.example.com/openapi.json",
      "well_known_url": "https://myapi.example.com/.well-known/x402.json",
      "is_primary": true
    }
  ]
}

Auth: apis:read.

SDK

Discovery fields are accepted on create and update.

TypeScript

await client.apis.create({
  name: "Search",
  slug: "search",
  upstream_base_url: "https://upstream.example.com",
  discovery_guidance: "Use POST /search with a query field.",
  discovery_contact_email: "support@example.com",
  openapi_version: "1.0.0",
});
const urls = await client.apis.discovery(apiId);
await client.endpoints.update(apiId, endpointId, {
  request_schema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
  response_schema: { type: "object", additionalProperties: true },
});

Go

api, err := client.CreateAPI(ctx, ax402.CreateAPIInput{
  Name: "Search", Slug: "search", UpstreamBaseURL: "https://upstream.example.com",
  DiscoveryGuidance: "Use POST /search with a query field.",
  DiscoveryContactEmail: "support@example.com",
})
disc, err := client.GetAPIDiscovery(ctx, api.ID)

Python

api = client.apis.create({
  "name": "Search",
  "slug": "search",
  "upstream_base_url": "https://upstream.example.com",
  "discovery_guidance": "Use POST /search with a query field.",
  "discovery_contact_email": "support@example.com",
})
urls = client.apis.discovery(api.id)

Language guides: TypeScript · Go · Python

CLI

ax402 apis create --name Search --slug search --upstream https://upstream.example.com \
  --discovery-guidance "Use POST /search." --discovery-contact-email support@example.com

ax402 apis discovery --id API_ID --json
ax402 discovery urls --api-id API_ID --json

ax402 endpoints update --api-id API_ID --endpoint-id EP \
  --request-schema '{"type":"object","properties":{"query":{"type":"string"}}}' \
  --response-schema '{"type":"object","additionalProperties":true}'

Full command list: CLI reference

MCP

Tool	Purpose
`ax402_discovery_urls`	`GET /apis/{id}/discovery`
`ax402_set_discovery_guidance`	Set guidance / contact / OpenAPI version
`ax402_update_endpoint_schemas`	Set or clear endpoint JSON Schemas
`ax402_create_api`	Create API; optional discovery fields on create
`ax402_import_openapi`	Import ops; schemas persisted when present

Full tool list: MCP server

On this page