x402 Payments

Wayfinder can be configured to work with the x402 payment protocol for paid gateway services and higher rate limits. This allows you to seamlessly make requests that may require payment without having to manually handle payment flows.

To get started, install the @ar.io/wayfinder-x402-fetch package.

The @ar.io/wayfinder-x402-fetch package is a simple wrapper of the x402-fetch library, which creates a fetch implementation to automatically handles x402 payment flows. You can use this fetch implementation with Wayfinder to enable x402 payments for your requests.

import { createWayfinderClient, StaticRoutingStrategy } from '@ar.io/wayfinder-core';
import { createX402Fetch } from '@ar.io/wayfinder-x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

// Set up your wallet for x402 payments
const privateKey = process.env.X402_PRIVATE_KEY; // Your private key
const account = privateKeyToAccount(privateKey);

// Create x402-enabled fetch implementation
const x402Fetch = createX402Fetch({
  walletClient: account,
});

// Create Wayfinder client with x402 fetch to handle payments
const wayfinder = createWayfinderClient({
  fetch: x402Fetch,
  routingSettings: {
    // Configure to use x402-enabled gateways
    strategy: new StaticRoutingStrategy({
      gateway: 'https://paid-gateway.example.com',
    }),
  },
});

// Requests will now automatically handle x402 payments
const response = await wayfinder.request('ar://transaction-id');

How it works:

When a gateway returns a 402 Payment Required status
The x402 fetch automatically handles the payment flow
The request is retried with payment credentials
You get access to premium gateway services

Use cases:

Higher rate limits on data requests
Access to premium gateway features
Supporting gateway operators through payments

To learn more about x402 payments, visit the x402 documentation.

How is this guide?