Skip to main content

Installation

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

Quick Start

import express from 'express'
import { credGates } from '@cred-protocol/express'

const app = express()

app.use('/api', credGates({
  apiKey: process.env.CRED_API_KEY,
  policy: 'standard',
}))

app.get('/api/resource', (req, res) => {
  const trust = req.credTrust!
  res.json({ data: '...', tier: trust.trustTier })
})

app.listen(3000)

Configuration

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

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

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

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

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

  // Custom wallet extraction
  extractWallet: (req) => req.headers['x-agent-wallet'] as string,
})

Wallet Address Extraction

By default the middleware checks:
  1. X-Wallet-Address request header
  2. ?wallet= query parameter
Override with extractWallet:
credGates({
  apiKey: process.env.CRED_API_KEY,
  policy: 'standard',
  extractWallet: (req) => {
    // From a JWT, session, or custom header
    return req.headers['x-agent-wallet'] as string || null
  },
})

Accessing Trust Data

The middleware attaches the result to req.credTrust:
app.get('/api/profile', (req, res) => {
  const trust = req.credTrust!

  res.json({
    wallet: trust.walletAddress,
    score: trust.trustScore,
    tier: trust.trustTier,
    confidence: trust.confidence,
    gates: trust.gateResults,
  })
})

Response Headers

When headers: true (default), every response includes:
HeaderExampleDescription
X-Cred-Trust-Score750–100 composite score
X-Cred-Trust-TierverifiedTrust tier classification
X-Cred-Request-Ida1b2c3d4-...Request ID for debugging
X-Cred-Price-Multiplier0.25Price multiplier (if pricing enabled)

Error Handling

The middleware catches errors and passes them to Express error handling:
// Errors from the Cred API are forwarded via next(err)
app.use((err, req, res, next) => {
  console.error('Trust evaluation error:', err)
  res.status(500).json({ error: 'Internal server error' })
})
ResponseWhen
400No wallet address found on the request
402Gates failed, on402: 'challenge' — includes challenge body
403Gates failed with on402: 'deny', or wallet is blocked
429Cred API rate limit exceeded
502Upstream gate provider error