> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryvo.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog

> Discover every gateway route, its price, and its schema via GET /v1/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

```bash theme={null}
curl https://gateway.Ryvo.network/v1/catalog | jq .
```

A response includes the full route list plus provider categories:

```json theme={null}
{
  "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:

```bash theme={null}
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](/gateway/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:

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 `accessMode: "exact"`, let your x402 client library handle payment using the price from the `402` challenge.
5. If `accessMode: "ryvo-channel"`, send `X-Ryvo-Request-Id` and `RYVO-COMMITMENT` with the next cumulative channel amount.
6. If `accessMode: "siwx"`, let your client handle SIWX using the `authNetworks` from the `402` challenge.

See the [Integration guide](/gateway/integration-guide) for a worked TypeScript example.

## See also

* [Access modes](/gateway/access-modes)
* [Pricing](/gateway/pricing)
* [Endpoints reference](/gateway/reference/endpoints)