x402-avm-axios

IMPORTANT: This package is temporary and works until the x402 Algorand specification and following implementation PR are reviewed and merged by Coinbase. Until then, this package contains X402 core protocol plus support for Algorand-specific types and utilities.

A utility package that extends Axios to automatically handle 402 Payment Required responses using the x402 payment protocol. This package enables seamless integration of payment functionality into your applications when making HTTP requests with Axios.

Installation

npm install x402-avm-axios

Quick Start

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { withPaymentInterceptor } from "x402-avm-axios;
import axios from "axios";
import { baseSepolia } from "viem/chains";

// Create a wallet client
const account = privateKeyToAccount("0xYourPrivateKey");
const client = createWalletClient({
  account,
  transport: http(),
  chain: baseSepolia,
});

// Create an Axios instance with payment handling
const api = withPaymentInterceptor(
  axios.create({
    baseURL: "https://api.example.com",
  }),
  client,
);

// Make a request that may require payment
const response = await api.get("/paid-endpoint");
console.log(response.data);

Algorand Wallets

Provide any object that implements the Algorand signer interface (address plus signTransactions) and the interceptor will automatically target Algorand (or Algorand Testnet) payment requirements when they are offered.

import { withPaymentInterceptor } from "x402-avm-axios";

const algorandWallet = {
  address: account.address,
  signTransactions: async (transactions: Uint8Array[]) => {
    return peraWallet.signTransactions([transactions]);
  },
};

const api = withPaymentInterceptor(axios.create({ baseURL: API_URL }), algorandWallet);

Features

• Automatic handling of 402 Payment Required responses
• Automatic retry of requests with payment headers
• Payment verification and header generation
• Exposes payment response headers

API

withPaymentInterceptor(axiosClient, walletClient)

Adds a response interceptor to an Axios instance to handle 402 Payment Required responses automatically.

Parameters

• axiosClient: The Axios instance to add the interceptor to
• walletClient: The wallet client used to sign payment messages (must implement the x402 wallet interface)

Returns

The modified Axios instance with the payment interceptor that will:

1. Intercept 402 responses
2. Parse the payment requirements
3. Create a payment header using the provided wallet client
4. Retry the original request with the payment header
5. Expose the X-PAYMENT-RESPONSE header in the final response