Skip to main content

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.

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:
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" | "wallet" | "tokens"Logical surface. wallet is the Helius Wallet API.
methodstringCanonical method name (getBalance, search, …).
descriptionstringHuman-readable route description.
accessMode"exact" | "siwx" | "ryvo-channel"x402 payment, wallet auth, or Ryvo channel authorization. See Access modes.
paymentRequiredbooleantrue for paid routes, false for SIWX.
priceUsdstring (optional)Decimal USD price, present for x402 exact paid routes.
priceTokenAmountstring (optional)Six-decimal official devnet USDC amount, present for ryvo-channel routes.
tokenMintstring (optional)Official devnet USDC mint for ryvo-channel routes.
tokenIdnumber (optional)Protocol token ID for ryvo-channel routes, resolved from the live registry/config.
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 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 for a worked TypeScript example.

​
See also