Agentic Commerce Quickstart

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! },
}));

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);
});

bun install @agent-score/commerce hono
# or: npm install @agent-score/commerce hono

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',
  },
}));

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' });
});

{
  "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": "Please complete identity verification at the verify_url."
}

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).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);
  });
});

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! },
}));

// 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 }),
);

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'],
});

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);
  },
};

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']}

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'],
)

# 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'],
}

{ requireKyc: true, requireSanctionsClear: true, minAge: 21, allowedJurisdictions: ['US'] }

{ requireKyc: true, requireSanctionsClear: true, minAge: 18 }

{ requireSanctionsClear: true, blockedJurisdictions: ['KP', 'IR', 'CU', 'RU', 'SY'] }

{ requireKyc: true } // just prove the agent is backed by a real human

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 };
    },
  },
}));

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 });
});