Skip to main content
The gateway publishes a single discovery endpoint: 
GET /v1/catalog
Clients should use this endpoint instead of hard-coding route lists. Any route that is live, its price, its access mode, and its input/output schema are all available here.

​
Fetching the catalog

curl https://gateway.agonx402.com/v1/catalog | jq .
A response includes the full route list plus provider categories: 
{
  "ok": true,
  "version": 1,
  "payment": {
    "modes": ["exact", "siwx"],
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "pricingModel": "mixed",
    "asset": {
      "symbol": "USDC",
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "decimals": 6
    }
  },
  "catalog": {
    "totalRoutes": 45,
    "returnedRoutes": 45,
    "filters": { "provider": null }
  },
  "categories": {
    "providers": [
      { "id": "alchemy", "label": "Alchemy", "routeCount": 18, "href": "https://gateway.agonx402.com/v1/catalog?provider=alchemy" },
      { "id": "helius", "label": "Helius", "routeCount": 18, "href": "https://gateway.agonx402.com/v1/catalog?provider=helius" },
      { "id": "tokens", "label": "TokensAPI", "routeCount": 19, "href": "https://gateway.agonx402.com/v1/catalog?provider=tokens" }
    ]
  },
  "routes": [ /* ... CatalogRouteEntry[] ... */ ]
}

​
Filtering by provider

To fetch only one provider’s routes: 
curl "https://gateway.agonx402.com/v1/catalog?provider=alchemy"
curl "https://gateway.agonx402.com/v1/catalog?provider=helius"
curl "https://gateway.agonx402.com/v1/catalog?provider=tokens"
Aliases accepted for the Tokens provider: tokens, tokensapi, tokens-api. An unknown value returns 400 with supportedProviders listed in the body.

​
Route entry shape

Each item in routes[] is a CatalogRouteEntry:
FieldTypeNotes
pathstringFully-qualified route path (supports :param templating).
httpMethod"GET" | "POST" | "HEAD"Canonical HTTP method for the route.
cluster"mainnet" | "devnet" (optional)Only present for Solana routes.
provider"alchemy" | "helius" | "tokens"Upstream provider identifier.
surface"rpc" | "das" | "tokens"Logical surface.
methodstringCanonical method name (getBalance, search, …).
descriptionstringHuman-readable route description.
accessMode"exact" | "siwx"Payment vs. auth-only. See Access modes.
paymentRequiredbooleantrue for paid routes, false for SIWX.
priceUsdstring (optional)Decimal USD price, present for paid routes.
authNetworksstring[] (optional)SIWX networks, present for SIWX routes.
paymentNetworkstring (optional)CAIP-2 of the settlement network (paid routes only).
paymentAsset{ symbol, mint, decimals } (optional)Asset descriptor (paid routes only).
enabledbooleanAlways true for routes returned here.
inputSchemaobjectJSON Schema for the request input.
outputSchemaobjectJSON Schema for the response body.
pathParamsSchemaobject (optional)JSON Schema for :param path segments.

​
Catalog envelope

The top-level catalog object reports:
FieldMeaning
catalog.totalRoutesTotal number of routes across every provider.
catalog.returnedRoutesNumber of routes returned given the current filter.
catalog.filters.providerThe active provider filter (null if unfiltered).
Backwards compatibility: clients that only read routes continue to work unchanged. The additional envelope fields are additive.

​
Using the catalog

Typical client flow:
  1. Fetch GET /v1/catalog once on startup (or per reload).
  2. Render routes grouped by categories.providers.
  3. For each user action, look up the matching CatalogRouteEntry, build the request according to inputSchema, and fire it.
  4. If paymentRequired: true, let your x402 client library handle the exact flow using the price from the 402 challenge.
  5. If paymentRequired: false and accessMode: "siwx", let your client handle SIWX using the authNetworks from the 402 challenge.
See the Integration guide for a worked TypeScript example.

​
See also