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 sits between your client and two kinds of upstreams:
  • Paid Solana RPC and DAS routes from Alchemy and Helius, priced per call in USDC.
  • Wallet-authenticated Tokens API routes, where the gateway holds the upstream key and you authenticate with your Solana wallet.
Everything speaks standard x402 over plain HTTP. If your client library already supports x402, there is nothing new to learn.

​
The shape of a call

┌────────┐   x402 request    ┌────────────────┐   upstream call   ┌────────────┐
│ Client │ ────────────────▶ │  Ryvo Gateway  │ ────────────────▶ │  Provider  │
└────────┘ ◀──────────────── │                │ ◀──────────────── └────────────┘
      ▲      JSON response   │                │   JSON response
      │                      └────────┬───────┘
      │ confirmed on-chain            │ verify / settle
      │                               ▼
      │                      ┌────────────────┐
      └──────────────────────│   Solana L1    │  paid routes only
                             └────────────────┘
On every request the gateway:
  1. Resolves which route you are calling.
  2. Validates your input before touching anything upstream.
  3. Asks for payment (paid routes) or a wallet signature (Tokens API) if you did not include one.
  4. Calls the upstream provider.
  5. Settles the payment only after the upstream responds successfully.
  6. Returns the upstream JSON to you, along with a proof of settlement where applicable.
Paid Solana RPC and DAS routes use the standard x402 exact payment flow:
  1. Client sends the request (for example, POST /v1/x402/solana/mainnet/alchemy/rpc/getBalance).
  2. Gateway returns 402 Payment Required with an envelope describing:
    • scheme: "exact"
    • network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
    • asset: USDC
    • maxAmountRequired - the price in micro-USDC
    • payTo - the gateway’s settlement wallet
  3. Client signs a Solana USDC transfer for that amount, encodes it into PAYMENT-SIGNATURE, and retries the request.
  4. Gateway verifies the signed transfer.
  5. Gateway calls the upstream provider with the real request payload.
  6. Gateway submits the payment on-chain only after a successful upstream response.
  7. Gateway returns the upstream JSON plus the Solana settlement transaction in X-PAYMENT-RESPONSE.
This “verify first, settle on success” ordering is deliberate: clients are never charged for upstream errors.

​
Tokens API - sign in with your wallet

Tokens API routes use the sign-in-with-x extension of x402. No USDC is transferred; you prove ownership of a wallet and the gateway calls the Tokens API on your behalf.
  1. Client sends the request (for example, GET /v1/x402/tokens/health).
  2. Gateway returns 402 Payment Required with a sign-in-with-x challenge declaring:
    • acceptable networks (Solana mainnet and devnet)
    • a sign-in statement
    • an expirationSeconds window (300 seconds)
  3. Client signs a SIWX message with their wallet, encodes it into SIGN-IN-WITH-X, and retries.
  4. Gateway verifies the signature and expiration.
  5. Gateway calls the Tokens API with its server-side credential and returns the response.
No on-chain transaction is created. The wallet signature is the authorization. See Access modes for a side-by-side comparison.

​
Upstream providers

ProviderClustersSurfacesNotes
Alchemymainnet, devnetrpc, das (mainnet only)Pay-as-you-go compute-unit pricing
Heliusmainnet, devnetrpc, das, wallet (wallet is mainnet-only)Pay-as-you-go per-credit pricing
Tokens APIn/atokensWallet sign-in (SIWX) instead of per-call pricing

​
Discovery

  • Every route advertises its price, access mode, and input/output schemas in its 402 challenge.
  • GET /v1/catalog returns the full route list in a single response, ideal for agents and tooling that need to enumerate what is available without probing each endpoint.
  • Paid routes are crawlable by x402 discovery services because they always return 402 on an unpaid probe, never leaking upstream data.
See Route catalog for the exact shape of the discovery response.

​
See also