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

# Access Modes

> x402 exact, wallet-authenticated SIWX, and Ryvo channel routes.

Every gateway route reports its authorization mode as `accessMode` in the catalog.

| Access mode    | Header                                  | Settles on-chain?                   | Used for                                                 |
| -------------- | --------------------------------------- | ----------------------------------- | -------------------------------------------------------- |
| `exact`        | `PAYMENT-SIGNATURE` (aka `X-PAYMENT`)   | Yes - USDC on Solana mainnet        | Paid Solana RPC and DAS routes                           |
| `siwx`         | `SIGN-IN-WITH-X`                        | No                                  | Tokens API routes                                        |
| `ryvo-channel` | `X-Ryvo-Request-Id` + `RYVO-COMMITMENT` | Settled later through Ryvo Protocol | Channel-backed Solana RPC, DAS, and Helius Wallet routes |

The `exact` and `siwx` modes use the x402 request-challenge-retry pattern. The `ryvo-channel` mode uses an already-open Ryvo payment channel and a signed cumulative commitment per request.

## `exact` - pay-per-call with USDC

Used by every Alchemy and Helius Solana RPC / DAS route.

### Challenge

The first unauthenticated request to a paid route returns `402 Payment Required` with an envelope like:

```json theme={null}
{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "maxAmountRequired": "<micro-USDC>",
      "resource": "https://gateway.Ryvo.network/v1/x402/solana/mainnet/alchemy/rpc/getBalance",
      "description": "Fetch the lamport balance for an account.",
      "mimeType": "application/json",
      "payTo": "<gateway payTo wallet>",
      "asset": {
        "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "symbol": "USDC",
        "decimals": 6
      },
      "facilitator": { "url": "<facilitator url>" },
      "extensions": { "...": "discovery extension" }
    }
  ]
}
```

### Response

The client builds an SVM `exact` transfer for `maxAmountRequired` to `payTo` and includes it in `PAYMENT-SIGNATURE`. The gateway:

1. Verifies the signed transfer.
2. Forwards the request to the upstream provider.
3. Settles the transfer only after the upstream returns a successful response.
4. Returns the upstream JSON along with an `X-PAYMENT-RESPONSE` header carrying the Solana settlement transaction.

If the upstream fails, settlement is skipped. No funds move.

## `ryvo-channel` - channel-backed gateway calls

Used by `/v1/ryvo-channel/...` routes. The agent opens a channel to the gateway merchant participant, locks official devnet USDC, and sends a signed cumulative commitment with each request.

Required request headers:

* `X-Ryvo-Request-Id`: stable idempotency key for the request.
* `RYVO-COMMITMENT`: base64 JSON envelope containing the signed `ryvo-cmt-v5` cumulative commitment payload.

The gateway verifies that the commitment targets the gateway merchant, live devnet program, correct cluster, correct message domain, and official devnet USDC token. It then checks channel headroom as:

```text theme={null}
effectiveLocked = max(0, lockedBalance - pendingUnlockAmount)
maxAuthorized = settledCumulative + effectiveLocked
remainingHeadroom = max(0, maxAuthorized - latestAcceptedCommitted)
```

The gateway settles accepted commitments with `settleCommitmentBundle`, not BLS. Tokens SIWX routes remain free/auth-only and do not enter channel authorization.

## `siwx` - wallet authentication without payment

Used by every `/v1/x402/tokens/...` route. The gateway holds the Tokens API key server-side; clients never see it. Instead, they prove ownership of a Solana wallet and the gateway calls the Tokens API on their behalf.

### Challenge

The first unauthenticated request returns `402 Payment Required` with a SIWX extension:

```json theme={null}
{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "sign-in-with-x",
      "network": ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"],
      "statement": "Sign in with your wallet to access TokensAPI through Ryvo.",
      "expirationSeconds": 300,
      "resource": "https://gateway.Ryvo.network/v1/x402/tokens/health"
    }
  ]
}
```

### Response

The client constructs a SIWX message, signs it with their Solana wallet, base64-encodes the payload, and retries the request with `SIGN-IN-WITH-X`. The gateway:

1. Verifies the wallet signature.
2. Enforces the 300-second expiration window and rejects replays.
3. Calls the Tokens API on your behalf using its server-side credential.
4. Returns the Tokens API JSON response.

No USDC transfer is created. No `X-PAYMENT-RESPONSE` header is returned.

## Why these modes

The modes solve different problems the gateway needs to bridge:

* **Paid Solana RPC/DAS** comes from providers that already have a well-defined PAYG cost per request, and clients want per-call payment without managing a provider-specific API key. `exact` x402 is the natural match.
* **Tokens API** is priced at the account level, not per request, and needs a trusted origin to hold the shared API key. Asking clients to pay per request would misrepresent the upstream cost. SIWX gives clients wallet-level identity without pretending each call has an independent on-chain price.
* **Payment-channel gateway calls** are best for agents that repeatedly call RPC, DAS, or wallet routes and want to amortize settlement with Ryvo Protocol instead of paying an on-chain transfer per request.

The x402 flows use standard x402 extensions, so any x402-compatible client library (including `@x402/fetch`) supports them out of the box. Channel-backed calls use Ryvo-specific protocol tooling; see [Agentic tools](/reference/agentic-tools).

## See also

* [Pricing](/gateway/pricing)
* [Catalog](/gateway/catalog)
* [Payment headers reference](/gateway/reference/payment-headers)