> ## 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.

# How it works

> What happens when you call the Ryvo Gateway from the client's point of view.

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](https://x402.org) 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 routes - pay per call in USDC

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 `network`s (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](/gateway/access-modes) for a side-by-side comparison.

## Upstream providers

| Provider   | Clusters            | Surfaces                                        | Notes                                             |
| ---------- | ------------------- | ----------------------------------------------- | ------------------------------------------------- |
| Alchemy    | `mainnet`, `devnet` | `rpc`, `das` (mainnet only)                     | Pay-as-you-go compute-unit pricing                |
| Helius     | `mainnet`, `devnet` | `rpc`, `das`, `wallet` (wallet is mainnet-only) | Pay-as-you-go per-credit pricing                  |
| Tokens API | n/a                 | `tokens`                                        | Wallet 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](/gateway/catalog) for the exact shape of the discovery response.

## See also

* [Access modes](/gateway/access-modes)
* [Pricing](/gateway/pricing)
* [Route catalog](/gateway/catalog)
* [Rate limiting & guardrails](/gateway/rate-limiting)
* [Settlement](/gateway/facilitator)