> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# x402

# Using x402 payments with Privy

Enable users to pay for APIs and content using x402, an open HTTP payment protocol. Privy's x402 integration helps integrate x402 payment authorizations from embedded wallets in both client-side React apps and server-side Node.js applications. Payment settlement is handled by the selected facilitator.

## What is x402?

[x402](https://x402.org) is an open payment protocol that enables instant, automatic payments for APIs and digital content over HTTP. When a resource requires payment, the server responds with `402 Payment Required`. The client constructs an `X-PAYMENT` header with a signed payment authorization and retries the request.

## Installation

<Tabs>
  <Tab title="React">
    ```bash theme={"system"}
    npm install @privy-io/react-auth
    ```

    The `useX402Fetch` hook is built into `@privy-io/react-auth` (v3.7.0+).
  </Tab>

  <Tab title="Node.js">
    ```bash theme={"system"}
    npm install @privy-io/node @x402/fetch
    ```

    The `createX402Client` function is available in `@privy-io/node`.
  </Tab>
</Tabs>

## Usage

### Basic example

<Tabs>
  <Tab title="React">
    ```tsx theme={"system"}
    import {useX402Fetch, useWallets} from '@privy-io/react-auth';

    function MyComponent() {
      const {wallets} = useWallets();
      const {wrapFetchWithPayment} = useX402Fetch();

      async function fetchPremiumContent() {
        // Wrap fetch with your wallet
        const fetchWithPayment = wrapFetchWithPayment({
          walletAddress: wallets[0]?.address,
          fetch
        });

        // Use exactly like native fetch - automatically handles 402 payments
        const response = await fetchWithPayment('https://api.example.com/premium');
        const data = await response.json();

        return data;
      }

      return <button onClick={fetchPremiumContent}>Fetch Premium Content</button>;
    }
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={"system"}
    import {createX402Client} from '@privy-io/node/x402';
    import {wrapFetchWithPayment} from '@x402/fetch';

    // Get wallet details
    const wallet = await privy.wallets().get({walletId: 'your-wallet-id'});

    // Create x402 client (chain type is inferred from address)
    const x402client = createX402Client(privy, {
      walletId: wallet.id,
      address: wallet.address,
    });

    // Wrap fetch - 402 payments are handled automatically
    const fetchWithPayment = wrapFetchWithPayment(fetch, x402client);
    const response = await fetchWithPayment('https://api.example.com/premium');
    const data = await response.json();
    ```
  </Tab>
</Tabs>

### Using default connected wallet

<Tabs>
  <Tab title="React">
    ```tsx theme={"system"}
    import {useX402Fetch} from '@privy-io/react-auth';

    function MyComponent() {
      const {wrapFetchWithPayment} = useX402Fetch();

      async function fetchPremiumContent() {
        // Omit walletAddress to use first connected wallet
        const fetchWithPayment = wrapFetchWithPayment({fetch});

        const response = await fetchWithPayment('https://api.example.com/premium');
        const data = await response.json();

        return data;
      }

      return <button onClick={fetchPremiumContent}>Fetch Premium Content</button>;
    }
    ```
  </Tab>
</Tabs>

### With maximum payment protection

<Tabs>
  <Tab title="React">
    ```typescript theme={"system"}
    import {useX402Fetch, useWallets} from '@privy-io/react-auth';

    const {wallets} = useWallets();
    const {wrapFetchWithPayment} = useX402Fetch();

    const fetchWithPayment = wrapFetchWithPayment({
      walletAddress: wallets[0].address,
      fetch,
      maxValue: BigInt(1000000) // Max 1 USDC (6 decimals)
    });
    ```
  </Tab>
</Tabs>

### With gas-sponsored wallets

<Tabs>
  <Tab title="React">
    If your app uses Privy's gas sponsorship, pass `signatureOptions: { type: 'erc1271' }` to `wrapFetchWithPayment`.

    ```tsx theme={"system"}
    import {useX402Fetch, useWallets} from '@privy-io/react-auth';

    function MyComponent() {
      const {wallets} = useWallets();
      const {wrapFetchWithPayment} = useX402Fetch();

      async function fetchPremiumContent() {
        const fetchWithPayment = wrapFetchWithPayment({
          walletAddress: wallets[0]?.address,
          fetch,
          signatureOptions: {type: 'erc1271'},
        });

        const response = await fetchWithPayment('https://api.example.com/premium');
        const data = await response.json();

        return data;
      }

      return <button onClick={fetchPremiumContent}>Fetch Premium Content</button>;
    }
    ```
  </Tab>

  <Tab title="Node.js">
    If your app uses Privy's gas sponsorship, pass `signatureOptions: { type: 'erc1271' }` to `createX402Client`.

    ```typescript theme={"system"}
    import {PrivyClient} from '@privy-io/node';
    import {createX402Client} from '@privy-io/node/x402';
    import {wrapFetchWithPayment} from '@x402/fetch';

    const privy = new PrivyClient({appId, appSecret});
    const wallet = await privy.wallets().get('your-wallet-id');

    const x402client = createX402Client(privy, {
      walletId: wallet.id,
      address: wallet.address,
      signatureOptions: {type: 'erc1271'},
    });

    const fetchWithPayment = wrapFetchWithPayment(fetch, x402client);
    const response = await fetchWithPayment('https://api.example.com/premium');
    const data = await response.json();
    ```
  </Tab>
</Tabs>

## Key details

**Requirements:**

* Users need USDC in their Privy embedded wallet on the correct network (e.g. Base, Base Sepolia, or Solana)
* The facilitator pays gas fees (users only need USDC, not ETH or SOL)

**Testing:**

* For testnet: Get free USDC from [Circle's faucet](https://faucet.circle.com/)

## x402 facilitators

Facilitators are services that verify payment authorizations and submit transactions onchain on behalf of users. They handle gas fees and transaction settlement, allowing users to pay only with USDC without needing native tokens like ETH or SOL. Several x402 facilitators are available, including:

* Pay AI: [facilitator](https://facilitator.payai.network/), [docs](https://docs.payai.network/x402/reference)
* Corbits: [facilitator](https://facilitator.corbits.dev/), [docs](https://docs.corbits.dev/)
* Coinbase: [facilitator](http://api.cdp.coinbase.com/platform/v2/x402), [docs](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/x402-facilitator/x402-facilitator)

## Example x402-enabled APIs

CoinGecko and Allium provide x402-enabled data APIs for agent workflows.

### CoinGecko

* x402 docs: [docs.coingecko.com/x402](https://docs.coingecko.com/x402)
* Example endpoint: `https://pro-api.coingecko.com/api/v3/x402/simple/price`

### Allium

* AgentHub: [agents.allium.so](https://agents.allium.so/)
* API docs: [docs.allium.so](https://docs.allium.so/)

## Learn more

* [x402 docs](https://x402.gitbook.io/x402)
* [Privy sign typed data](https://docs.privy.io/wallets/using-wallets/ethereum/sign-typed-data)
* [EIP-3009 standard](https://eips.ethereum.org/EIPS/eip-3009)

You can find more x402-enabled APIs at [x402scan.com](http://x402scan.com).