Using Dynamic with x402

Learn how to implement x402 payments using Dynamic’s embedded wallets, server wallets, and external wallet adapters

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);