> ## Documentation Index
> Fetch the complete documentation index at: https://sigil-10dddbf2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js

> Protect Next.js App Router route handlers with Sigil credential verification.

## Install

```bash theme={null}
npm install @sigil-xyz/x402 next
```

## Import

```ts theme={null}
import { withSigilAuth } from '@sigil-xyz/x402/next'
```

`@sigil-xyz/x402/next` is a separate subpath — do not import from `@sigil-xyz/x402` for Next.js usage.

## Basic usage

Wrap your route handler with `withSigilAuth`:

```ts theme={null}
// app/api/generate/route.ts
import { withSigilAuth } from '@sigil-xyz/x402/next'
import { NextRequest, NextResponse } from 'next/server'
import { Connection } from '@solana/web3.js'
import BN from 'bn.js'

const connection = new Connection(process.env.SOLANA_RPC_URL!, 'confirmed')

export const POST = withSigilAuth(
  async (req) => {
    const agentPubkey = req.sigilAgent // verified agent pubkey (base58)
    return NextResponse.json({ result: 'generated', agent: agentPubkey })
  },
  {
    connection,
    serverWallet,
    requiredCapability: 'image-generation',
    spendAmount: new BN(50_000), // 0.05 USDC per request
  }
)
```

## TypeScript: sigilAgent type

The wrapped handler receives a `NextRequest` extended with `sigilAgent?: string`. This is already typed inside `withSigilAuth` — no extra declaration needed.

## Verification only

```ts theme={null}
export const GET = withSigilAuth(
  async (req) => {
    return NextResponse.json({ agent: req.sigilAgent })
  },
  {
    connection,
    serverWallet,
    requiredCapability: 'read',
    // no spendAmount → verify only, no on-chain spend recorded
  }
)
```

## Sharing config

Define the middleware config once and reuse it across routes:

```ts theme={null}
// lib/sigil.ts
import { SigilMiddlewareConfig } from '@sigil-xyz/x402'
import { Connection } from '@solana/web3.js'
import BN from 'bn.js'

export const connection = new Connection(process.env.SOLANA_RPC_URL!, 'confirmed')

export const baseConfig: Omit<SigilMiddlewareConfig, 'requiredCapability' | 'spendAmount'> = {
  connection,
  serverWallet,
}
```

```ts theme={null}
// app/api/generate/route.ts
import { withSigilAuth } from '@sigil-xyz/x402/next'
import { baseConfig } from '@/lib/sigil'
import BN from 'bn.js'

export const POST = withSigilAuth(handler, {
  ...baseConfig,
  requiredCapability: 'image-generation',
  spendAmount: new BN(50_000),
})
```

## Building agent headers

Use `buildSigilHeaders` from `@sigil-xyz/x402` in your agent code to construct the signed headers:

```ts theme={null}
import { buildSigilHeaders } from '@sigil-xyz/x402'
import { Keypair } from '@solana/web3.js'
import BN from 'bn.js'

const headers = buildSigilHeaders({
  agentKeypair: myAgentKeypair,
  method: 'POST',
  path: '/api/generate',
  spendAmount: new BN(50_000),
})

await fetch('https://api.example.com/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', ...headers },
  body: JSON.stringify({ prompt: 'a red fox' }),
})
```

## Error responses

On failure the middleware returns `402 Payment Required`:

```json theme={null}
{
  "protocol": "sigil-v1",
  "message": "Agent Sigil is invalid or lacks the 'image-generation' capability",
  "requiredCapability": "image-generation",
  "spendAmount": "50000",
  "credentialProgram": "ZFK63KBXDhGCYm5orVo5QiTBaBhWD4PUcUDBG6fjTkH",
  "network": "devnet",
  "docs": "https://docs.sigil.xyz/x402"
}
```