Catalog

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.Ryvo.network/v1/catalog | jq .

A response includes the full route list plus provider categories:

{
  "ok": true,
  "version": 1,
  "payment": {
    "modes": ["exact", "siwx", "ryvo-channel"],
    "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.Ryvo.network/v1/catalog?provider=alchemy" },
      { "id": "helius", "label": "Helius", "routeCount": 18, "href": "https://gateway.Ryvo.network/v1/catalog?provider=helius" },
      { "id": "tokens", "label": "TokensAPI", "routeCount": 19, "href": "https://gateway.Ryvo.network/v1/catalog?provider=tokens" }
    ]
  },
  "routes": [ /* ... CatalogRouteEntry[] ... */ ]
}

Filtering by provider

To fetch only one provider’s routes:

curl "https://gateway.Ryvo.network/v1/catalog?provider=alchemy"
curl "https://gateway.Ryvo.network/v1/catalog?provider=helius"
curl "https://gateway.Ryvo.network/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:

Field	Type	Notes
`path`	`string`	Fully-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" \| "wallet" \| "tokens"`	Logical surface. `wallet` is the Helius Wallet API.
`method`	`string`	Canonical method name (`getBalance`, `search`, …).
`description`	`string`	Human-readable route description.
`accessMode`	`"exact" \| "siwx" \| "ryvo-channel"`	x402 payment, wallet auth, or Ryvo channel authorization. See Access modes.
`paymentRequired`	`boolean`	`true` for paid routes, `false` for SIWX.
`priceUsd`	`string` (optional)	Decimal USD price, present for x402 `exact` paid routes.
`priceTokenAmount`	`string` (optional)	Six-decimal official devnet USDC amount, present for `ryvo-channel` routes.
`tokenMint`	`string` (optional)	Official devnet USDC mint for `ryvo-channel` routes.
`tokenId`	`number` (optional)	Protocol token ID for `ryvo-channel` routes, resolved from the live registry/config.
`authNetworks`	`string[]` (optional)	SIWX networks, present for SIWX routes.
`paymentNetwork`	`string` (optional)	CAIP-2 of the settlement network (paid routes only).
`paymentAsset`	`{ symbol, mint, decimals }` (optional)	Asset descriptor (paid routes only).
`enabled`	`boolean`	Always `true` for routes returned here.
`inputSchema`	`object`	JSON Schema for the request input.
`outputSchema`	`object`	JSON Schema for the response body.
`pathParamsSchema`	`object` (optional)	JSON Schema for `:param` path segments.

Catalog envelope

The top-level catalog object reports:

Field	Meaning
`catalog.totalRoutes`	Total number of routes across every provider.
`catalog.returnedRoutes`	Number of routes returned given the current filter.
`catalog.filters.provider`	The 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:

Fetch GET /v1/catalog once on startup (or per reload).
Render routes grouped by categories.providers.
For each user action, look up the matching CatalogRouteEntry, build the request according to inputSchema, and fire it.
If accessMode: "exact", let your x402 client library handle payment using the price from the 402 challenge.
If accessMode: "ryvo-channel", send X-Ryvo-Request-Id and RYVO-COMMITMENT with the next cumulative channel amount.
If accessMode: "siwx", let your client handle SIWX using the authNetworks from the 402 challenge.

See the Integration guide for a worked TypeScript example.

Introduction

Concepts

Routes

Integrate

Agentic

Reference

Fetching the catalog

Filtering by provider

Route entry shape

Catalog envelope

Using the catalog

See also

​Fetching the catalog

​Filtering by provider

​Route entry shape

​Catalog envelope

​Using the catalog

​See also

Fetching the catalog

Filtering by provider

Route entry shape

Catalog envelope

Using the catalog

See also