Skip to main content
This quickstart walks through the two things every 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.

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

​
1. Confirm the gateway is live

curl https://gateway.agonx402.com/healthz
# {"ok":true,"service":"agon-gateway","status":"healthy"}

​
2. Discover routes

curl https://gateway.agonx402.com/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.agonx402.com/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 CDP facilitator endpoint
Do the same for a SIWX route to see the auth-only challenge: 
curl -i https://gateway.agonx402.com/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.agonx402.com/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.agonx402.com/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.