Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.payai.network/llms.txt

Use this file to discover all available pages before exploring further.

Getting started with Fetch

Make x402 payments with a Fetch client in 2 minutes.
You can find the full code for this example here.

Step 1: Create a new client

npm (npx)
npx @payai/x402-fetch-starter@latest my-first-client
pnpm
pnpm dlx @payai/x402-fetch-starter@latest my-first-client
bun
bunx @payai/x402-fetch-starter@latest my-first-client
The starter mirrors the upstream fetch example and bootstraps a ready-to-run Fetch client.

Step 2: Set your environment variables

Open your generated project’s .env and set the following:
  • EVM_PRIVATE_KEY: Hex EVM private key of the paying account
  • SVM_PRIVATE_KEY: Base58 Solana private key of the paying account
  • RESOURCE_SERVER_URL: Base URL of the server to call (e.g. http://localhost:4021)
  • ENDPOINT_PATH: Path to a paid endpoint (e.g. /weather)
EVM_PRIVATE_KEY=
SVM_PRIVATE_KEY=
RESOURCE_SERVER_URL=http://localhost:4021
ENDPOINT_PATH=/weather

Step 3: Preview the client code

This is the index.ts the starter generates. It loads your env, creates an x402 client with EVM and SVM schemes, wraps fetch with wrapFetchWithPayment, calls your endpoint, and logs the response body and payment settlement from the PAYMENT-RESPONSE header.
import { config } from "dotenv";
import { x402Client, wrapFetchWithPayment, x402HTTPClient } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

config();

const evmPrivateKey = process.env.EVM_PRIVATE_KEY as `0x${string}`;
const svmPrivateKey = process.env.SVM_PRIVATE_KEY as string;
const baseURL = process.env.RESOURCE_SERVER_URL || "http://localhost:4021";
const endpointPath = process.env.ENDPOINT_PATH || "/weather";
const url = `${baseURL}${endpointPath}`;

/**
 * Example demonstrating how to use @x402/fetch to make requests to x402-protected endpoints.
 *
 * This uses the helper registration functions from @x402/evm and @x402/svm to register
 * all supported networks for both v1 and v2 protocols.
 *
 * Required environment variables:
 * - EVM_PRIVATE_KEY: The private key of the EVM signer
 * - SVM_PRIVATE_KEY: The private key of the SVM signer
 */
async function main(): Promise<void> {
  const evmSigner = privateKeyToAccount(evmPrivateKey);
  const svmSigner = await createKeyPairSignerFromBytes(base58.decode(svmPrivateKey));

  const client = new x402Client();
  registerExactEvmScheme(client, { signer: evmSigner });
  registerExactSvmScheme(client, { signer: svmSigner });

  const fetchWithPayment = wrapFetchWithPayment(fetch, client);

  console.log(`Making request to: ${url}\n`);
  const response = await fetchWithPayment(url, { method: "GET" });
  const body = await response.json();
  console.log("Response body:", body);

  if (response.ok) {
    const paymentResponse = new x402HTTPClient(client).getPaymentSettleResponse(name =>
      response.headers.get(name),
    );
    console.log("\nPayment response:", JSON.stringify(paymentResponse, null, 2));
  } else {
    console.log(`\nNo payment settled (response status: ${response.status})`);
  }
}

main().catch(error => {
  console.error(error?.response?.data?.error ?? error);
  process.exit(1);
});

Step 4: Run the client

npm run dev
Your client is now making x402 payments!

Step 5: Test the client

You can test your client against a local server by running the Express example, Hono example, or Next.js example. You can also test your client against a live merchant for free. You will receive a full refund of any tokens that you send, and PayAI will pay for the network fees.

x402 reference

For a deeper dive into message shapes, headers, verification and settlement responses, see the x402 Reference.

Need help?

Join our Community

Have questions or want to connect with other developers? Join our Discord server.