agentscore-gate

Middleware that gates API access based on AgentScore trust scores.

Install

npm install agentscore-gate

Quick Start

import express from 'express';
import { agentscoreGate } from 'agentscore-gate';

const app = express();
app.use(agentscoreGate({ minGrade: 'C' }));

That's it. Requests from wallets with a grade below C get a 403.

How It Works

1. Extracts the caller's wallet address from request headers (x-payer-address from x402, x-wallet-address, or ?wallet=)
2. Looks up their AgentScore trust score
3. Allows or blocks based on your configured thresholds
4. Blocked requests get 403 with: { error: "insufficient_trust_score", score, grade, required }

Options

agentscoreGate({
  minScore: 50,              // minimum numeric score (default: 0)
  minGrade: 'C',             // minimum letter grade (A, B, C, D, F)
  allowRoles: ['agent'],     // only allow specific roles
  allowUnscored: true,       // allow wallets with no score (default: true)
  denyList: ['0x...'],       // always block these wallets
  allowList: ['0x...'],      // always allow (bypass scoring)
  cache: 300,                // cache TTL in seconds (default: 300)
  apiUrl: 'https://...',     // override API base URL
  failOpen: true,            // allow through if API is down (default: true)
  extractWallet: (req) => req.headers['x-custom'], // custom extraction
  onBlock: (req, scoreData) => console.log('blocked'),
  onError: (req, error) => console.error(error),
})

Examples

Express

import express from 'express';
import { agentscoreGate } from 'agentscore-gate';

const app = express();

// Gate all routes
app.use(agentscoreGate({ minScore: 40, allowUnscored: false }));

// Or gate specific routes
app.use('/api/premium', agentscoreGate({ minGrade: 'B' }));

app.get('/api/data', (req, res) => {
  // Access score data attached to request
  console.log(req.agentScore); // { score, grade, role, ... }
  res.json({ data: 'protected' });
});

Fastify

import Fastify from 'fastify';
import { agentscoreGate } from 'agentscore-gate';

const app = Fastify();
const gate = agentscoreGate({ minGrade: 'C' });

app.addHook('preHandler', (req, reply, done) => {
  gate(req, reply, done);
});

Standalone Score Lookup

import { lookupScore, AgentScoreClient } from 'agentscore-gate';

// One-off lookup
const score = await lookupScore('0x1234...');
console.log(score.grade); // 'B'

// Reusable client (with caching)
const client = new AgentScoreClient({ cache: 600 });
const data = await client.lookup('0x1234...');

Scoring

AgentScore evaluates wallet trust across multiple dimensions — transaction history, on-chain reputation, protocol interactions, and more. Scores range from 0–100 with letter grades A through F.

Learn more at agentscore.sh/docs.

License

MIT