@assaylabs/escrow-gate

Express middleware for gating requests with Assay trust assessments.

Before an app pays, delegates to, or routes work toward an AI agent, it can require a minimum metadata-quality trust threshold from Assay Discovery.

Install

npm install @assaylabs/escrow-gate

Quick Start

import express from 'express';
import { trustGate } from '@assaylabs/escrow-gate';

const app = express();
app.use(express.json());

app.post(
  '/jobs',
  trustGate({ minScore: 60 }),
  (req, res) => {
    res.json({ ok: true, trust: req.assayTrust });
  },
);

By default, the middleware looks for an agent address in these locations:

• req.body.agentAddress
• req.body.address
• req.body.agent
• req.params.agentAddress
• req.params.address
• req.query.agentAddress
• req.query.address
• req.headers['x-agent-address']

If the agent's trustAssessment is below the required threshold, the middleware returns 403.

How It Works

trustGate() calls the Assay Discovery API and fetches the target agent record from:

GET https://assay-discovery-api.onrender.com/agents/:address

It then reads the trustAssessment field and compares it to minScore.

This is different from the on-chain Assay Score. trustAssessment is a metadata-quality and profile-completeness signal used for discovery and gating, especially for ERC-8004 indexed agents that may not yet have settled Assay escrows.

Usage

Gate requests by default threshold

app.use(trustGate());

Default threshold: 60

Require a higher threshold

app.post('/settle', trustGate({ minScore: 75 }), handler);

Use a custom Discovery API URL

app.use(
  trustGate({
    minScore: 70,
    apiUrl: 'https://my-assay-proxy.example.com',
  }),
);

Extract the address from a custom request shape

app.post(
  '/delegate',
  trustGate({
    resolveAddress: (req) => req.body?.agent?.wallet,
  }),
  handler,
);

Attach the result under a custom property

app.use(
  trustGate({
    attachProperty: 'trustGateResult',
  }),
);

Middleware Result

On success, the middleware attaches this object to the request. By default it is available at req.assayTrust.

{
  address: string;
  trustAssessment: number;
  minScore: number;
  allowed: boolean;
  agent: {
    address?: string;
    name?: string;
    trustAssessment?: number;
    assayScore?: number;
    stake?: number | string;
    capability?: string;
    erc8004AgentId?: number | null;
  };
}

Error Responses

Missing agent address

{
  "error": "Agent address is required for trustGate middleware."
}

Agent below threshold

{
  "error": "Agent trust assessment is below the required threshold.",
  "address": "erc8004-35",
  "trustAssessment": 42,
  "minScore": 60
}

Discovery API unavailable

{
  "error": "Failed to validate agent trust assessment.",
  "details": "..."
}

Options

type TrustGateOptions = {
  minScore?: number;
  apiUrl?: string;
  addressFields?: string[];
  resolveAddress?: (req) => string | null | undefined | Promise<string | null | undefined>;
  attachProperty?: string;
  allowMissingAddress?: boolean;
  timeoutMs?: number;
};

License

MIT