Skip to main content
This quickstart walks through the two things every x402 gateway integration needs:
  1. An unpaid probe to inspect the 402 Payment Required challenge.
  2. A real call that completes the x402 flow, either paying with USDC (exact) or signing in with a wallet (siwx).
You can follow along with plain curl to understand the wire format, then switch to @x402/fetch in TypeScript for a real integration. For Ryvo payment-channel routes under /v1/ryvo-channel/..., use the channel flow in Access modes and Agentic tools.

​
Prerequisites

  • A Solana mainnet wallet with a small USDC balance and a little SOL for fees.
  • The wallet must be different from the gateway’s payTo wallet, x402 exact SVM will reject a self-transfer.
  • Node.js 20+ if you use the TypeScript example below.
The live gateway settles on Solana mainnet. Keep the wallet funded with only as much USDC as you intend to spend while testing.
For every x402 paid route, the advertised price includes the upstream PAYG cost plus a fixed $0.0006 gateway settlement surcharge (to cover the on-chain settlement transaction fee).

​
1. Confirm the gateway is live

curl https://gateway.Ryvo.network/healthz
# {"ok":true,"service":"ryvo-gateway","status":"healthy"}

​
2. Discover routes

curl https://gateway.Ryvo.network/v1/catalog | jq '.routes | length'
Every live route, including its price, access mode, input schema, and output schema, is listed in the catalog. See Catalog for the full response shape.

​
3. Inspect a 402 challenge

Hit a paid route with no payment to see the x402 envelope: 
curl -i -X POST https://gateway.Ryvo.network/v1/x402/solana/mainnet/alchemy/rpc/getBalance
You should get back 402 Payment Required with an accepts[0] entry describing:
  • scheme: "exact"
  • network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
  • maxAmountRequired: the price in micro-USDC
  • payTo: the gateway’s settlement wallet
  • facilitator.url: the x402 facilitator endpoint
Do the same for a SIWX route to see the auth-only challenge: 
curl -i https://gateway.Ryvo.network/v1/x402/tokens/health
Here accepts[0] describes a sign-in-with-x challenge with accepted Solana networks and a 300-second expiry.

​
4. Make a paid call in TypeScript

Any x402-compatible client works. The example below uses @x402/fetch: 
npm install @x402/core @x402/fetch @x402/extensions @x402/svm @solana/kit bs58

import bs58 from "bs58";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { wrapFetchWithPayment } from "@x402/fetch";
import { ExactSvmScheme, SOLANA_MAINNET_CAIP2 } from "@x402/svm";
import { createSIWxPayload, encodeSIWxHeader } from "@x402/extensions/sign-in-with-x";

const signer = await createKeyPairSignerFromBytes(
  bs58.decode(process.env.SOLANA_PRIVATE_KEY_BASE58!),
);

const gatewayFetch = wrapFetchWithPayment(fetch, {
  signer,
  schemes: [{ scheme: ExactSvmScheme, network: SOLANA_MAINNET_CAIP2 }],
  extensions: {
    "sign-in-with-x": async ({ challenge }) => {
      const network = Array.isArray(challenge.network) ? challenge.network[0] : challenge.network;
      const payload = await createSIWxPayload({
        signer,
        network,
        statement: challenge.statement,
        expirationSeconds: challenge.expirationSeconds,
        resource: challenge.resource,
      });
      return encodeSIWxHeader(payload);
    },
  },
});

// Paid route - pays in USDC on Solana mainnet
const paid = await gatewayFetch(
  "https://gateway.Ryvo.network/v1/x402/solana/mainnet/alchemy/rpc/getBalance",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      params: ["86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY"],
    }),
  },
);
console.log("result:", (await paid.json()).result);
console.log("settlement tx:", paid.headers.get("x-payment-response"));

// Auth-only Tokens route - no USDC is transferred
const tokens = await gatewayFetch(
  "https://gateway.Ryvo.network/v1/x402/tokens/assets/search?q=solana&limit=5",
);
console.log("search:", (await tokens.json()).result);
wrapFetchWithPayment transparently handles both flows:
  • Paid routes: reads the 402 envelope, builds and signs an exact USDC transfer, retries with PAYMENT-SIGNATURE, and returns the upstream response plus settlement tx in X-PAYMENT-RESPONSE.
  • Tokens routes: reads the sign-in-with-x challenge, signs a SIWX message with your wallet, retries with SIGN-IN-WITH-X, and returns the upstream response.

​
Next steps

Access modes

Understand when the gateway asks for payment vs. a SIWX signature.

All routes

Browse every Solana RPC, DAS, and Tokens route with pricing and schemas.

Integrate in your app

Patterns for pay-per-call workers, SIWX clients, and agent wallets.

How it works

Inspect the x402 exact and SIWX flows in detail.