How to Screen Payer Wallets in a Paid x402 Route

x402 verifies the payment. It does not answer the question that comes right before work starts: should this wallet be allowed through the route at all?

If you run a paid x402 route, an unknown wallet can arrive with a valid payment signature and still be a bad counterparty. That wallet might be brand new, part of a sybil cluster, or just not strong enough to trust for expensive work.

The simplest production pattern is to keep x402 exactly where it is for payment verification, then add one middleware layer right after it for wallet screening.

The Smallest Useful Integration

npm install hono @x402/core @x402/evm @x402/hono x402-agent-score

import { HTTPFacilitatorClient } from '@x402/core/server'
import { ExactEvmScheme } from '@x402/evm/exact/server'
import { paymentMiddlewareFromConfig } from '@x402/hono'
import { Hono } from 'hono'
import { agentScoreGate } from 'x402-agent-score'

const app = new Hono()
const facilitator = new HTTPFacilitatorClient({ url: 'https://x402.org/facilitator' })

app.use(
  paymentMiddlewareFromConfig(
    {
      'GET /research': {
        accepts: {
          scheme: 'exact',
          network: 'eip155:8453',
          payTo: '0xYourPayToAddress',
          price: '$0.05',
        },
        description: 'Premium research endpoint',
      },
    },
    facilitator,
    [{ network: 'eip155:8453', server: new ExactEvmScheme() }],
  ),
)

app.use(
  agentScoreGate({
    minScore: 25,
    onUnknown: 'allow',
    cacheTtl: 300_000,
  }),
)

The important detail is ordering. Run the screening middleware after x402 verification so it reads a verified payer wallet, not an untrusted client-supplied header.

What Happens On The First Request?

The safest pilot behavior is onUnknown: 'allow'. A wallet you have never seen before should not be hard-blocked just because the score cache is empty.

Practical rollout: let the first request through, warm the score cache in the background, and add decision headers immediately. The second request is where you can start enforcing policy cleanly.

Every response includes:

X-Agent-Score for the numeric score or unscored
X-Agent-Tier for the wallet tier
X-Agent-Recommendation for the suggested action

The Safe Pilot Policy

Do not start with an aggressive rule set. Start small:

Phase 1: headers only, nothing blocked
Phase 2: block the obvious red zone, usually scores below 25
Phase 3: treat the middle band as review in logs or dashboards before you automate more

That rollout gives you real traffic, a false-positive review loop, and a concrete proof point without turning billing policy into a production outage.

Why This Pattern Matters

x402 already solves a real problem: autonomous payment over HTTP. But a merchant or route operator still needs one more decision before serving the request. That decision is not “did the wallet pay?” It is “does this wallet look trustworthy enough for this route?”

That is the wedge for AgentScore in the x402 stack. x402 handles settlement. AgentScore handles pre-transaction wallet screening.

Use the published middleware, the reference Hono example, or the live docs.

npm i x402-agent-score

Open Docs

If you run a paid x402 route and want help choosing a conservative threshold for a pilot, reach out via the design-partner form on the homepage.