Skip to main content

​
Overview

This guide shows you how to implement x402 payments using Dynamic’s wallet infrastructure. We use the x402-fetch library in the example; you can also use x402-axios or other HTTP clients that support x402. Dynamic supports multiple wallet options with x402, from embedded MPC wallets to external wallet integrations.

​
The x402 protocol

The x402 payment protocol defines how onchain payment is negotiated over HTTP 402 responses: the server returns payment requirements; the client signs and retries the request (often with an X-Payment header); a facilitator can verify and help settle onchain. The Coinbase Developer Platform (CDP) runs facilitator infrastructure used by many x402 integrations, including:
  • Zero-fee USDC payments on Base
  • Onchain settlement
  • Compliance and risk screening
  • Official client libraries (x402-fetch, x402-axios—see Installation)
For how 402 flows work in general and when to choose x402 versus Tempo MPP, see the HTTP 402 overview.

​
Prerequisites

Before implementing x402 with Dynamic, ensure you have:
  • A Dynamic project set up with your API keys
  • Basic understanding of HTTP status codes and request/response patterns
  • Familiarity with Dynamic’s wallet SDKs
  • x402 fetch library installed (or axios/other HTTP library)

​
Installation

Install the x402 libraries. These libraries add simple request middleware to wrap your HTTP calls with x402 payment handling. 
npm install x402-fetch
# or
npm install x402-axios
The x402 libraries are the official packages from Coinbase Developer Platform. You can also use other HTTP libraries with x402, but the official packages provide the best integration experience.

​
Implementation Options

​
Client-Side Implementation (React SDK)

For client-side applications, use Dynamic’s React SDK: 
import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
import { isEthereumWallet } from '@dynamic-labs/ethereum';
import { wrapFetchWithPayment, decodeXPaymentResponse } from 'x402-fetch';

const { primaryWallet } = useDynamicContext();

const x402PaymentUrl = 'https://example.com/x402-payment';

// Universal x402 payment handler
async function handleX402Payment(url, options = {}) {
  try {    
    if (isEthereumWallet(primaryWallet)) {
      // Get wallet client for Ethereum wallets
      const walletClient = await primaryWallet.getWalletClient();

      // Wrap fetch with x402 payment handling
      const fetchWithPayment = wrapFetchWithPayment(fetch, walletClient);

      // Make the request - x402 will handle payment automatically
      const response = await fetchWithPayment(url, options);

      // Optional: Decode payment response for debugging
      const paymentResponse = decodeXPaymentResponse(
        response.headers.get("x-payment-response")
      );
      if (paymentResponse) {
        console.log('Payment details:', paymentResponse);
      }
      
      return response;
    }
  } catch (error) {
    console.error('Payment failed:', error);
    throw error;
  }
}

// Make the request using the x402 payment handler
const response = await handleX402Payment(x402PaymentUrl);