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

# Next.js

> Add Foldset payment gating to your Next.js application

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @foldset/nextjs
  ```

  ```bash yarn theme={null}
  yarn add @foldset/nextjs
  ```

  ```bash pnpm theme={null}
  pnpm add @foldset/nextjs
  ```
</CodeGroup>

## Setup

<Steps>
  <Step title="Get your API key">
    Copy your API key from the [Foldset dashboard](https://foldset.com/dashboard/api-keys).
  </Step>

  <Step title="Set the environment variable">
    The SDK reads your API key from the `FOLDSET_API_KEY` environment variable.

    **Local development:** add it to `.env.local` (gitignored by default in Next.js):

    ```
    FOLDSET_API_KEY=sk_live_...
    ```

    **Production:** set it in your hosting provider's environment variable settings (e.g. Vercel, AWS, Railway). Never commit API keys to your repository.

    <Warning>
      Do not use `.env` for secrets. `.env` is often committed to git. Use `.env.local` for local development and your hosting provider's secrets management for production.
    </Warning>
  </Step>

  <Step title="Create the middleware file">
    Create `middleware.ts` in the root of your project:

    ```typescript middleware.ts theme={null}
    import { foldset } from "@foldset/nextjs";

    export default foldset({
      apiKey: process.env.FOLDSET_API_KEY!,
    });
    ```

    If you need to compose Foldset with your own middleware logic, use `withFoldset`. Your function only runs if payment is satisfied:

    ```typescript middleware.ts theme={null}
    import { withFoldset } from "@foldset/nextjs";
    import { NextResponse, type NextRequest } from "next/server";

    export default withFoldset(
      { apiKey: process.env.FOLDSET_API_KEY! },
      async function middleware(request: NextRequest) {
        // Your own logic here (auth, redirects, headers, etc.)
        return NextResponse.next();
      }
    );
    ```

    <Warning>
      Next.js 16 renames `middleware.ts` to `proxy.ts` and the exported function to `proxy`. If you're on Next.js 16 or later, name the file `proxy.ts` instead.
    </Warning>
  </Step>

  <Step title="Configure routes">
    Head to the [rules page](https://foldset.com/dashboard/rules) to choose which paths to protect and set prices.
  </Step>
</Steps>

## How it works

The Foldset middleware runs on every incoming request to your Next.js app:

1. Checks the request path against your configured rules
2. If no payment is required, the request passes through normally
3. If payment is required and no valid x402 payment header is present, returns a `402 Payment Required` response with payment instructions
4. If a valid payment is attached, the request passes through and settlement completes after your route handler responds

### MCP server protection

If your Next.js app hosts an MCP server (Streamable HTTP), Foldset can gate individual tool calls and resource reads. Configure MCP rules in the dashboard by specifying the endpoint path, method, and tool or resource name. Discovery methods like `tools/list` pass through for free with payment metadata attached.

## Update your robots.txt

Once Foldset is active, you want AI agents visiting your site so they can pay for access. If your `robots.txt` blocks AI crawlers, remove those rules. Foldset handles gating at the payment layer.

```
# Remove rules like these:
User-agent: GPTBot
Disallow: /

User-agent: ClaudeBot
Disallow: /
```