Agentic Commerce Quickstart

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

A single middleware call gates 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:

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.
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.
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 attached, or when the buyer asks for a verification session:

import { shouldRunConditionalGate } from '@agent-score/commerce/payment';

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

app.use('/purchase', async (c, next) => {
  if (!shouldRunConditionalGate(c.req.raw)) { await next(); return; }
  return _gate(c, next);
});

conditionalAgentscoreGate (and the equivalent variant on every adapter) does exactly this for you. 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. A buyer without an AgentScore identity can also get the verification link before preparing a payment: sending the same request with X-Verification-Session: create and no identity or payment credential runs the gate and returns the session 403 (verify_url, session_id, poll_secret, poll_url). This matters most on the Stripe Shared Payment Token rail, where the alternative is minting a token only to learn the buyer must verify first. Advertise the path in your 402 by including buildIdentityBootstrap() as identity_bootstrap (the Checkout orchestrator does this automatically). Flask, FastAPI, Express, etc. all support the same wrap (should_run_conditional_gate in Python); the test is “is one of payment-signature / x-payment / Authorization: Payment present on this request, or does it carry X-Verification-Session: create with no identity?”

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.com/dashboard (free tier covers hobby usage, including 20 /v1/assess calls a month; paid tiers raise the quota).

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@x.y.z)"
  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://www.agentscore.com/verify?session=sess_abc123",
  "session_id": "sess_abc123",
  "poll_secret": "ps_secret_xyz",
  "poll_url": "https://api.agentscore.com/v1/sessions/sess_abc123",
  "agent_instructions": "{\"action\":\"deliver_verify_url_and_poll\",\"steps\":[\"...\"],\"user_message\":\"...\"}"
}

The agent’s job:

Show verify_url to the user (it’s a ready-to-open URL with the session token embedded; don’t modify it).
While the user verifies, poll poll_url every 5 seconds with header X-Poll-Secret: {poll_secret}.
When the poll returns status: "verified", extract operator_token from the response.
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.code: "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://www.agentscore.com/verify?session=sess_test',
        poll_secret: 'ps_test',
        poll_url: 'https://api.agentscore.com/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.code).toBe('identity_verification_required');
    expect(body.session_id).toBe('sess_test');
    expect(body.poll_url).toBe('https://api.agentscore.com/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({ decision: data!.decision }),
);

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 {'decision': assess['decision']}

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.

Field	Type	Examples	Description
`requireKyc`	`boolean`	`true`	Require a completed Stripe Identity verification
`requireSanctionsClear`	`boolean`	`true`	Fail when the operator’s name matched a sanctions list at KYC. Wallet-address OFAC screening of the payment signer runs regardless of this flag
`minAge`	`number`	`18`, `21`	Minimum age. Verified ages are `18+` or `21+` brackets, so a value above 21 always denies
`allowedJurisdictions`	`string[]`	`['US']`, `['US', 'CA']`	Allowlist of ISO country codes; all others denied
`blockedJurisdictions`	`string[]`	`['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.

Watch usage in the dashboard

Dashboard → Usage shows your quota used, rate limit and plan, daily API calls, and the successful versus error split. For allow/deny decisions and their reason codes, log the assess result the gate attaches to each request (getAgentScoreData(c)) alongside the order. 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 gate 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

Compliance gating reference; policy fields deep dive
AgentScore Commerce (Node.js) reference; all 5 framework adapters (Hono, Express, Fastify, Next.js, Web Fetch) plus payment + discovery + challenge + Stripe multichain helpers
AgentScore Commerce (Python) reference; all 6 framework adapters (FastAPI, Flask, Django, AIOHTTP, Sanic, generic ASGI) plus payment + discovery + challenge + Stripe multichain helpers
API Reference: /v1/assess; what the gate calls under the hood

Getting Started

Guides

API Reference

Integrations

MCP

Agentic Commerce Quickstart

The pattern

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

End-to-end Hono walkthrough

1. Install

2. Mount AgentScore Gate

3. Access assess data in the handler

4. What the agent sees on 403

5. Testing with mocked gate outcomes

The same pattern in every framework

Express

Next.js App Router

Fastify

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

FastAPI (native `Depends()`)

Flask

Django

Compliance policy reference

Common vertical policies

Advanced: per-request session context

Post-payment: capture the signer wallet

Watch usage in the dashboard

Live example: buy a wine

Next steps

​The pattern

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

​End-to-end Hono walkthrough

​1. Install

​2. Mount AgentScore Gate

​3. Access assess data in the handler

​4. What the agent sees on 403

​5. Testing with mocked gate outcomes

​The same pattern in every framework

​Express

​Next.js App Router

​Fastify

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

​FastAPI (native Depends())

​Flask

​Django

​Compliance policy reference

​Common vertical policies

​Advanced: per-request session context

​Post-payment: capture the signer wallet

​Watch usage in the dashboard

​Live example: buy a wine

​Next steps

The pattern

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

End-to-end Hono walkthrough

1. Install

2. Mount AgentScore Gate

3. Access assess data in the handler

4. What the agent sees on 403

5. Testing with mocked gate outcomes

The same pattern in every framework

Express

Next.js App Router

Fastify

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

FastAPI (native `Depends()`)

Flask

Django

Compliance policy reference

Common vertical policies

Advanced: per-request session context

Post-payment: capture the signer wallet

Watch usage in the dashboard

Live example: buy a wine

Next steps