Skip to main content
Your API serves agents. An agent hits POST /purchase on behalf of a user who may or may not be KYC-verified, old enough, in an allowed jurisdiction, or on a sanctions list. You need to verify the human behind the agent before you deliver, without breaking the agent’s retry loop. This guide shows the drop-in pattern using @agent-score/commerce (Node.js) or agentscore-commerce (Python). We’ll walk through Martin Estate’s wine commerce API as the worked example because it exercises every gate (KYC, age, sanctions, jurisdiction); same pattern applies to any merchant. Sayer & Stone (agents.sayerandstone.com) is the unrestricted-goods counterpoint: same SDK, no identity gate on /purchase at all.

​
The pattern

Three lines of middleware config gate your route: 
import { agentscoreGate } from '@agent-score/commerce/identity/hono';

app.use('/purchase', agentscoreGate({
  apiKey: process.env.AGENTSCORE_API_KEY!,
  userAgent: `my-api/${VERSION}`,
  requireKyc: true,
  requireSanctionsClear: true,
  minAge: 21,
  allowedJurisdictions: ['US'],
  createSessionOnMissing: { apiKey: process.env.AGENTSCORE_API_KEY! },
}));
Here’s what happens:
  1. Agent hits /purchase with an X-Operator-Token or X-Wallet-Address header. The gate extracts the identity, calls POST /v1/assess with your policy, and either passes the request through (with assess data attached) or returns a 403 with reason codes.
  2. If no identity header is present, the gate auto-mints a verification session via POST /v1/sessions and returns a 403 carrying verify_url, session_id, poll_secret, poll_url, and agent-polling instructions. The agent opens verify_url for the user, polls poll_url with X-Poll-Secret: {poll_secret} in the background, and retries once the user finishes Stripe Identity. Zero additional merchant code.
  3. If identity fails a compliance check (age, sanctions, jurisdiction), the default 403 includes the denial reasons + a verify_url for resolvable cases (e.g. KYC expired).
No hand-rolled fetches, no session-creation boilerplate, no decision === 'deny' branches.

​
AgentScore Gate, conditional variant: support any x402 wallet (Coinbase awal, Phantom, etc.)

The mount above runs the gate on every request to /purchase. That’s correct when the only buyers are agents that already carry an AgentScore credential. If you want any spec-compliant x402 wallet to discover prices anonymously and pay (Coinbase awal, Phantom, Solflare, …), wrap the gate so it fires only when a payment credential is already attached: 
import { hasPaymentHeader } from '@agent-score/commerce/payment';

const _gate = agentscoreGate({ /* same options as above */ });

app.use('/purchase', async (c, next) => {
  if (!hasPaymentHeader(c.req.raw)) { await next(); return; }
  return _gate(c, next);
});
Anonymous browsers fall through to the handler unauthenticated; they get the full 402 with rails + per-order pricing without an AgentScore account. The gate runs at settle time on the retry leg (when X-Payment / Authorization: Payment arrives), and createSessionOnMissing still auto-mints a verification session so the agent can bootstrap KYC and replay the same payment authorization within its TTL window. Flask, FastAPI, Express, etc. all support the same wrap; the test is purely “is one of payment-signature / x-payment / Authorization: Payment present on this request?”

​
End-to-end Hono walkthrough

Martin Estate’s POST /purchase is the canonical integration. What follows is a trimmed version of their src/routes/purchase.ts with the exact gate setup.

​
1. Install

bun install @agent-score/commerce hono
# or: npm install @agent-score/commerce hono
Grab an API key at agentscore.sh/dashboard (free tier covers hobby usage; paid tier enables /v1/assess policy evaluation).

​
2. Mount AgentScore Gate

import { Hono } from 'hono';
import { agentscoreGate, getAgentScoreData } from '@agent-score/commerce/identity/hono';

const app = new Hono();

app.use('/purchase', agentscoreGate({
  apiKey: process.env.AGENTSCORE_API_KEY!,
  // Prepends your app's identifier to outbound User-Agent for traceability in
  // AgentScore's server logs. Format: "{userAgent} (@agent-score/commerce@1.0.0)"
  userAgent: `your-merchant/${VERSION}`,
  // Wine-specific compliance policy. See the policy reference below.
  requireKyc: true,
  requireSanctionsClear: true,
  minAge: 21,
  allowedJurisdictions: ['US'],
  // Auto-create a verification session when no identity header is present.
  createSessionOnMissing: {
    apiKey: process.env.AGENTSCORE_API_KEY!,
    context: 'wine-purchase',
    productName: 'Martin Estate wine',
  },
}));
That’s it for the compliance layer. Everything else below is your existing route code.

​
3. Access assess data in the handler

app.post('/purchase', async (c) => {
  // The gate populated this via c.set('agentscore', data) before calling next().
  const assess = getAgentScoreData(c);
  console.log('identity method:', assess?.identity_method); // 'wallet' | 'operator_token'
  console.log('policy checks:', assess?.policy_result?.checks);

  // ... your normal payment + fulfillment logic ...

  return c.json({ order_id: '...', status: 'completed' });
});
getAgentScoreData(c) returns the full /v1/assess response; decision, decision_reasons, operator_verification, policy_result, and any resolvable verify_url. Record it alongside the order for audit purposes.

​
4. What the agent sees on 403

When identity is missing, the default response is: 
{
  "error": {
    "code": "identity_verification_required",
    "message": "Identity verification is required to access this resource. Visit verify_url to complete KYC."
  },
  "verify_url": "https://agentscore.sh/verify?session=sess_abc123",
  "session_id": "sess_abc123",
  "poll_secret": "ps_secret_xyz",
  "poll_url": "https://api.agentscore.sh/v1/sessions/sess_abc123",
  "agent_instructions": "Please complete identity verification at the verify_url."
}
The agent’s job:
  1. Show verify_url to the user (it’s a ready-to-open URL with the session token embedded; don’t modify it).
  2. While the user verifies, poll poll_url every 5 seconds with header X-Poll-Secret: {poll_secret}.
  3. When the poll returns status: "verified", extract operator_token from the response.
  4. Retry POST /purchase with header X-Operator-Token: {operator_token}.
The retry should pass through; same request body, just with the verified identity. If identity is present but fails policy with an UNFIXABLE reason (age_insufficient, sanctions_flagged, jurisdiction_restricted), the 403 has error: "wallet_not_trusted" with reasons[] and agent_instructions.action: "contact_support". Fixable reasons (kyc_required, kyc_pending, kyc_failed) never surface as wallet_not_trusted; the gate auto-mints a verification session and re-routes to identity_verification_required with verify_url + poll_secret, identical UX to the no-identity path above. (jurisdiction_restricted is unfixable because the API only emits it after KYC is verified; the user’s KYC’d country is in the merchant’s blocked list, and re-doing KYC won’t change it.)

​
5. Testing with mocked gate outcomes

The gate calls POST /v1/assess via global.fetch. Mock it in Vitest: 
import { describe, expect, it, vi } from 'vitest';
import app from '../src/app';

describe('POST /purchase', () => {
  it('returns 403 when identity is missing', async () => {
    // Mock the session-creation call the gate makes on missing identity.
    global.fetch = vi.fn().mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: vi.fn().mockResolvedValueOnce({
        session_id: 'sess_test',
        verify_url: 'https://agentscore.sh/verify?session=sess_test',
        poll_secret: 'ps_test',
        poll_url: 'https://api.agentscore.sh/v1/sessions/sess_test',
        expires_at: '2026-04-22T13:00:00Z',
      }),
    });

    const res = await app.request('/purchase', {
      method: 'POST',
      body: JSON.stringify({ product_id: '...', quantity: 1 }),
    });

    expect(res.status).toBe(403);
    const body = await res.json();
    expect(body.error).toBe('identity_verification_required');
    expect(body.session_id).toBe('sess_test');
    expect(body.poll_url).toBe('https://api.agentscore.sh/v1/sessions/sess_test');
  });

  it('lets the request through when identity passes policy', async () => {
    global.fetch = vi.fn().mockResolvedValueOnce({
      ok: true,
      status: 200,
      json: vi.fn().mockResolvedValueOnce({
        decision: 'allow',
        decision_reasons: [],
        operator_verification: { level: 'kyc_verified' },
      }),
    });

    const res = await app.request('/purchase', {
      method: 'POST',
      headers: { 'X-Operator-Token': 'opc_test' },
      body: JSON.stringify({ product_id: '...', quantity: 1 }),
    });

    expect(res.status).toBe(200);
  });
});

​
The same pattern in every framework

Each adapter ships with the same option shape. Pick yours. The gate-conditional wrap applies identically to all of them; wrap the gate handler instead of mounting it directly when you want anonymous x402 wallets to discover prices.

​
Express

import express from 'express';
import { agentscoreGate } from '@agent-score/commerce/identity/express';

const app = express();
app.use('/purchase', agentscoreGate({
  apiKey: process.env.AGENTSCORE_API_KEY!,
  requireKyc: true, minAge: 21, allowedJurisdictions: ['US'],
  createSessionOnMissing: { apiKey: process.env.AGENTSCORE_API_KEY! },
}));

​
Next.js App Router

// app/api/purchase/route.ts
import { withAgentScoreGate } from '@agent-score/commerce/identity/nextjs';

export const POST = withAgentScoreGate(
  {
    apiKey: process.env.AGENTSCORE_API_KEY!,
    requireKyc: true, minAge: 21, allowedJurisdictions: ['US'],
    createSessionOnMissing: { apiKey: process.env.AGENTSCORE_API_KEY! },
  },
  async (_req, { data }) => Response.json({ score: data!.score.value }),
);

​
Fastify

import Fastify from 'fastify';
import agentscoreGate from '@agent-score/commerce/identity/fastify';

const app = Fastify();
await app.register(agentscoreGate, {
  apiKey: process.env.AGENTSCORE_API_KEY!,
  requireKyc: true, minAge: 21, allowedJurisdictions: ['US'],
});

​
Web Fetch (Cloudflare Workers / Deno / Bun / edge)

import { createAgentScoreGate } from '@agent-score/commerce/identity/web';

const guard = createAgentScoreGate({
  apiKey: env.AGENTSCORE_API_KEY,
  requireKyc: true, minAge: 21, allowedJurisdictions: ['US'],
});

export default {
  async fetch(req: Request) {
    const r = await guard(req);
    if (!r.allowed) return r.response;
    return handle(req, r.data);
  },
};

​
FastAPI (native Depends())

from fastapi import Depends, FastAPI
from agentscore_commerce.identity.fastapi import AgentScoreGate, get_agentscore_data

app = FastAPI()
gate = AgentScoreGate(
    api_key=os.environ['AGENTSCORE_API_KEY'],
    require_kyc=True, min_age=21, allowed_jurisdictions=['US'],
)

@app.post('/purchase', dependencies=[Depends(gate)])
async def purchase(assess = Depends(get_agentscore_data)):
    return {'score': assess['score']['value']}

​
Flask

from agentscore_commerce.identity.flask import agentscore_gate

agentscore_gate(
    app,
    api_key=os.environ['AGENTSCORE_API_KEY'],
    require_kyc=True, min_age=21, allowed_jurisdictions=['US'],
)

​
Django

# settings.py
MIDDLEWARE = ['agentscore_commerce.identity.django.AgentScoreMiddleware']
AGENTSCORE_GATE = {
    'api_key': os.environ['AGENTSCORE_API_KEY'],
    'require_kyc': True, 'min_age': 21, 'allowed_jurisdictions': ['US'],
}
Starlette, Litestar, Quart all work via the generic ASGI adapter: from agentscore_commerce.identity import AgentScoreGate. AIOHTTP and Sanic ship native adapters at agentscore_commerce.identity.aiohttp / agentscore_commerce.identity.sanic.

​
Compliance policy reference

All policy fields are optional; set only what your vertical requires.
FieldTypeExamplesDescription
requireKycbooleantrueRequire a completed Stripe Identity verification
requireSanctionsClearbooleantrueFail on OFAC / UN / EU sanctions matches
minAgenumber18, 21Minimum age bracket enforced by the KYC provider
allowedJurisdictionsstring[]['US'], ['US', 'CA']Allowlist of ISO country codes; all others denied
blockedJurisdictionsstring[]['KP', 'IR', 'CU']Blocklist; takes precedence over allowedJurisdictions

​
Common vertical policies

Wine / alcohol / age-restricted goods (Martin Estate): 
{ requireKyc: true, requireSanctionsClear: true, minAge: 21, allowedJurisdictions: ['US'] }
Financial services / lending / regulated crypto: 
{ requireKyc: true, requireSanctionsClear: true, minAge: 18 }
Restricted exports (US): 
{ requireSanctionsClear: true, blockedJurisdictions: ['KP', 'IR', 'CU', 'RU', 'SY'] }
Marketplace trust gate (non-regulated): 
{ requireKyc: true } // just prove the agent is backed by a real human

​
Advanced: per-request session context

For the flagship case; where the verify page should show the specific product the agent was buying; use the getSessionOptions and onBeforeSession hooks: 
app.use('/purchase', agentscoreGate({
  apiKey: process.env.AGENTSCORE_API_KEY!,
  requireKyc: true, minAge: 21, allowedJurisdictions: ['US'],
  createSessionOnMissing: {
    apiKey: process.env.AGENTSCORE_API_KEY!,
    // Compute session options per-request. Hook receives the framework context so
    // it can read body/headers/state a prior middleware stashed.
    getSessionOptions: async (c) => {
      const body = await c.req.json();
      const product = await lookupProduct(body.product_id);
      return { productName: product.name }; // "2022 Cabernet Sauvignon" not "wine"
    },
    // Side-effect hook that runs after the session mints. Return value merges
    // into the 403 response, use it to attach a merchant-specific resume token
    // (e.g. a pending-order id).
    onBeforeSession: async (c, session) => {
      const pendingOrderId = await createPendingOrder(await c.req.json(), session);
      return { order_id: pendingOrderId };
    },
  },
}));
Martin Estate uses this exact pattern to pre-create pending_identity orders before the 403 fires; agents can then retry with just { operator_token, order_id } instead of re-sending the full body.

​
Post-payment: capture the signer wallet

After a successful payment, report the wallet that signed it back to AgentScore. Builds a cross-merchant credential↔wallet profile: the agent’s opc_... token you gated on gets linked to every wallet it’s been observed paying from, across every merchant using AgentScore. 
import { captureWallet } from '@agent-score/commerce/identity/hono';

app.post('/purchase', async (c) => {
  // ... compliance gate passed, payment settled ...
  const signer = extractPaymentSigner(paymentCredential); // e.g. EIP-3009 `from`
  await captureWallet(c, {
    walletAddress: signer,
    network: 'evm',                     // or 'solana'
    idempotencyKey: paymentIntentId,    // prevents retry double-count
  });
  return c.json({ ok: true });
});
Fire-and-forget; no-ops silently if the request was wallet-authenticated (no operator_token to link) or the API call fails. See the Credentials reference for the endpoint shape.

​
Agent-side integration

Your merchant wiring is done. On the other side of the wire, the agent calling your API needs to know how to pick an identity header, handle the new denial codes, and persist the agent_memory hint for cross-merchant reuse. That’s a separate concern; different audience, different code; and lives in a dedicated guide: Agent identity integration. Merchants don’t need to know the agent-side details to wire the gate, but it’s worth scanning once so your llms.txt and 402 challenge copy matches what the agent guide tells agents to expect.

​
Observe denials in the dashboard

Every denial is logged against your API key. Open Dashboard → Usage to see:
  • Total gated requests, allow/deny split
  • Top denial reason codes (so you can tune minAge, allowedJurisdictions, etc.)
  • Sessions created via createSessionOnMissing, completion rate
Wallets captured via captureWallet surface at Dashboard → Identity as a unified list with source labels (claimed, captured, both).

​
Live example: buy a wine

Drop this into your agent:
“Buy me wine; see https://agents.martinestate.com/skill.md.”
That’s the whole prompt. The agent fetches /skill.md (the merchant’s skill manifest), learns the catalog endpoint, payment rails (Tempo MPP / x402 Base / Solana MPP / Stripe SPT), and identity requirements (KYC + 21+ + US-only), then asks which wine, takes a shipping address, walks through verification, pays, and ships real wine to your door, all gated by the five-line config above.
This needs an agent that can make HTTP calls; Claude Code, a Slack/Discord agent like OpenClaw, or any custom SDK-driven agent. The chat-only surfaces (chatgpt.com, claude.ai) won’t work.

​
Next steps