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.

Every gateway route reports its authorization mode as accessMode in the catalog.
Access modeHeaderSettles on-chain?Used for
exactPAYMENT-SIGNATURE (aka X-PAYMENT)Yes - USDC on Solana mainnetPaid Solana RPC and DAS routes
siwxSIGN-IN-WITH-XNoTokens API routes
ryvo-channelX-Ryvo-Request-Id + RYVO-COMMITMENTSettled later through Ryvo ProtocolChannel-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: 
{
  "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: 
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: 
{
  "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.

​
See also