Skip to main content

Installation

Quick Start

Configuration

Evaluate Options

Using a Policy Template

The simplest way to evaluate — pick a template that matches your use case:

Using Custom Gates

For full control, specify individual gates:

With Dynamic Pricing

Compute trust-based pricing for your API:

With Reputation Data

Response Types

TrustResult

The evaluate() method returns a TrustResult:

GateScoreBreakdown

Error Handling

Screen x402 payers (Know Your Agent)

If you sell over x402 with @x402/core v2, one line screens every paying agent with Know Your Agent before its payment settles:
The facilitator verifies the payment first, so only a payer who really signed it is looked up. If your policy refuses the payer, the payment is aborted before settlement and no funds move. The payer gets a 402 whose error is one of: registerCredKya covers every x402 payment flow. authorization (the default for EVM exact) is screened after verify, and upfront/escrow before their early settle. If you only use authorization, server.onAfterVerify(credKyaHook(options)) is equivalent.

Where the check runs

The hooks registerCredKya installs run between the facilitator’s verify and settle. Refusals never settle, so no funds move.

Policy

  • Cost. A KYA lookup costs 10 Cred Units; a wallet with no agent is a free 404, then a 1 CU screen.
  • Caching. Decisions are cached per payer: 15 minutes, or 1 hour for a refusal on sanctions (the lists refresh hourly). An incomplete check is never cached. Concurrent payments from one payer share one lookup.
  • Fail open, but not past sanctions. With onError: 'accept' the hook still runs the fast OFAC screen and refuses a sanctioned payer. It accepts unchecked only if that screen fails too.
  • Slow first lookups. A first lookup on a new wallet can take several seconds. Past timeoutMs, the onError policy decides that payment. The lookup keeps running, so the payer’s next payment gets the full answer.
  • Never throws. x402 ignores a hook that throws and settles anyway, so every failure becomes an explicit accept or refuse.
CredKyaClient exposes the same calls directly: kyaByWallet, kyaByAgentId and sanctionsScreen.

Choosing a policy

Framework Middleware

The core SDK is used by all framework middleware packages. If you’re using Hono, Express, Next.js, or FastAPI, see the dedicated middleware guides — they handle wallet extraction, 402 challenges, and trust headers automatically.

Hono

Drop-in Hono middleware

Express

Express middleware

Next.js

Next.js proxy and middleware

Python

Python + FastAPI