Next.js Middleware

Installation

npm install @cred-protocol/nextjs @cred-protocol/sdk

Quick Start

Next.js 16 renamed middleware to proxy. credGates works with both; only the file and export name differ. Create the file in your project root (or in src/, next to app/ or pages/):

Next.js 16+ (proxy.ts)
Next.js 14 and 15 (middleware.ts)

// proxy.ts
import { credGates } from '@cred-protocol/nextjs'

export const proxy = credGates({
  apiKey: process.env.CRED_API_KEY!,
  policy: 'standard',
  matcher: ['/api/:path*'],
})

export const config = {
  matcher: ['/api/:path*'],
}

Proxy runs on the Node.js runtime.

// middleware.ts
import { credGates } from '@cred-protocol/nextjs'

export const middleware = credGates({
  apiKey: process.env.CRED_API_KEY!,
  policy: 'standard',
  matcher: ['/api/:path*'],
})

export const config = {
  matcher: ['/api/:path*'],
}

Middleware runs on the edge runtime by default (Node.js is also available from Next.js 15.5).

Every request to /api/* is evaluated before reaching your route handler. Wallets that fail the trust check receive a 402 or 403 response before your route runs, so your API handlers only see trusted traffic.

Upgrading to Next.js 16? Next’s codemod renames the file and export for you: npx @next/codemod@canary middleware-to-proxy .

Configuration

credGates({
  // Required
  apiKey: process.env.CRED_API_KEY!,

  // Policy (pick one)
  policy: 'standard',
  // gates: ['human', 'verified'],
  // operator: 'AND',

  // Route matching
  matcher: ['/api/:path*'],        // Only gate these routes

  // Dynamic pricing
  pricing: {
    enabled: true,
    curve: 'step',
    basePriceUsdc: 0.01,
  },

  // Failure handling
  on402: 'challenge',              // 'challenge' (402), 'deny' (403), 'pass'
  onBlocked: 'deny',               // 'deny' (403), 'challenge' (402), 'pass'

  // Response headers
  headers: true,                   // X-Cred-Trust-Score, X-Cred-Trust-Tier

  // Custom wallet extraction
  extractWallet: (req) => req.headers.get('x-agent-wallet'),

  // Callback for logging/analytics (runs on denials too)
  onEvaluation: (result, req) => {
    console.log(`${result.walletAddress}: ${result.trustTier} (${result.trustScore})`)
  },
})

Wallet Address Extraction

By default the middleware checks:

X-Wallet-Address request header
?wallet= query parameter

Override with extractWallet:

credGates({
  apiKey: process.env.CRED_API_KEY!,
  policy: 'standard',
  matcher: ['/api/:path*'],
  extractWallet: (req) => {
    return req.headers.get('x-agent-wallet')
      || req.nextUrl.searchParams.get('address')
  },
})

Response Headers

When headers: true (default), every evaluated request gets these headers set on the response, 402 and 403 denials included:

Header	Example	Description
`X-Cred-Trust-Score`	`75`	0–100 composite score
`X-Cred-Trust-Tier`	`verified`	Trust tier classification
`X-Cred-Request-Id`	`a1b2c3d4-...`	Request ID for debugging
`X-Cred-Price-Multiplier`	`0.25`	Price multiplier (if pricing enabled)

Read these in your API route handlers:

// app/api/resource/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function GET(req: NextRequest) {
  const trustScore = req.headers.get('x-cred-trust-score')
  const trustTier = req.headers.get('x-cred-trust-tier')

  return NextResponse.json({
    data: '...',
    trustScore,
    trustTier,
  })
}

Route Matching

The matcher option controls which routes are trust-gated. Routes that don’t match pass through without evaluation.

credGates({
  apiKey: process.env.CRED_API_KEY!,
  policy: 'standard',
  matcher: [
    '/api/:path*',          // All API routes
    '/protected/:path*',    // Protected pages
  ],
})

Also set config.matcher in your proxy.ts (or middleware.ts) so Next.js only invokes credGates on matching routes. Without it, Next.js calls it on every request, including static files.

Failure Responses

Response	When
`400`	No wallet address found on the request
`402`	Gates failed, `on402: 'challenge'` — includes challenge body
`403`	Gates failed with `on402: 'deny'`, or wallet is `blocked`
`429`	Cred API rate limit exceeded
`502`	Upstream gate provider error

With on402: 'deny' the 403 body is:

{
  "error": "Trust requirements not met",
  "trustTier": "untrusted",
  "trustScore": 25,
  "failedGates": ["verified"]
}

SDKs

Framework Adapters

Installation

Quick Start

Configuration

Wallet Address Extraction

Response Headers

Route Matching

Failure Responses

​Installation

​Quick Start

​Configuration

​Wallet Address Extraction

​Response Headers

​Route Matching

​Failure Responses

Installation

Quick Start

Configuration

Wallet Address Extraction

Response Headers

Route Matching

Failure Responses