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

# Quickstart

> Make your first paid call to the live Ryvo Gateway in minutes.

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](/gateway/access-modes) and [Agentic tools](/reference/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.

<Warning>
  The live gateway settles on **Solana mainnet**. Keep the wallet funded with only as much USDC as you intend to spend while testing.
</Warning>

<Info>
  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).
</Info>

## 1. Confirm the gateway is live

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

## 2. Discover routes

```bash theme={null}
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](/gateway/catalog) for the full response shape.

## 3. Inspect a `402` challenge

Hit a paid route with no payment to see the x402 envelope:

```bash theme={null}
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:

```bash theme={null}
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`:

```bash theme={null}
npm install @x402/core @x402/fetch @x402/extensions @x402/svm @solana/kit bs58
```

```ts theme={null}
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

<CardGroup cols={2}>
  <Card title="Access modes" icon="shield-check" href="/gateway/access-modes">
    Understand when the gateway asks for payment vs. a SIWX signature.
  </Card>

  <Card title="All routes" icon="route" href="/gateway/routes/solana-rpc">
    Browse every Solana RPC, DAS, and Tokens route with pricing and schemas.
  </Card>

  <Card title="Integrate in your app" icon="code" href="/gateway/integration-guide">
    Patterns for pay-per-call workers, SIWX clients, and agent wallets.
  </Card>

  <Card title="How it works" icon="diagram-project" href="/gateway/how-it-works">
    Inspect the x402 exact and SIWX flows in detail.
  </Card>
</CardGroup>