AgentScore Commerce (Node.js)

npm install @agent-score/commerce

npm install hono mppx @x402/core @x402/evm stripe   # whatever your stack needs

import { buildA2AAgentCard, buildUCPProfile, ucpA2AExtension } from '@agent-score/commerce';

// 1. Google A2A v1.0 Signed Agent Card, published at /.well-known/agent-card.json.
//    Per UCP §A2A binding (https://ucp.dev/specification/checkout-a2a/), agents
//    that serve UCP via the A2A transport MUST declare the canonical UCP extension
//    URI in `capabilities.extensions[]` so platforms arriving via A2A detect UCP
//    support without re-fetching the profile. Pass an empty capabilities map when
//    you serve UCP at the discovery layer but have no formal capability bindings
//    yet. Skills declare what the agent can do; they are AgentSkill objects
//    (top-level on the card). Identity claims live in a separate AgentCardSignature
//    (RFC 7515 JWS) wrapping the serialized card, NOT in the card body itself.
const card = buildA2AAgentCard({
  name: 'My Agent Service',
  description: 'Buy products via agent payments.',
  url: 'https://agents.example.com',
  version: '1.0.0',
  skills: [
    { id: 'purchase', name: 'Purchase', description: 'Buy products via agent payments.', tags: ['commerce', 'payment'] },
  ],
  extensions: [ucpA2AExtension()],
});

// 2. Google Universal Commerce Protocol profile, published at /.well-known/ucp
//    Output shape: { ucp: { version, services, capabilities, payment_handlers,
//    name?, supported_versions? }, signing_keys: [...] } — services /
//    capabilities / payment_handlers are MAPS keyed by reverse-DNS service /
//    capability / handler name (UCP spec §3 + §6).
const profile = buildUCPProfile({
  name: 'My Agent Service',
  services: {
    'dev.ucp.shopping': [
      {
        version: '2026-04-08',
        spec: 'https://ucp.dev/2026-04-08/specification/overview',
        transport: 'mcp',
        endpoint: 'https://agents.example.com/api/ucp/mcp',
        schema: 'https://ucp.dev/services/shopping/mcp.openrpc.json',
      },
    ],
  },
  payment_handlers: {
    ...mppPaymentHandler({ networks: [{ network: 'tempo-mainnet', chain_id: 4217, recipient: TEMPO_ADDR }] }),
    ...x402PaymentHandler({ networks: [{ network: 'base-8453', recipient: BASE_ADDR }] }),
    ...stripeSptPaymentHandler({ profile_id: 'profile_5xKvNqM9BaH' }),
  },
  signing_keys: yourJWKS,
  // Optional: declare merchant gate policy as an `sh.agentscore.identity` capability
  // binding inside the public profile. Static policy declaration only — no per-operator
  // claims. Per-operator identity attestation flows through the AP2 risk-signal endpoint.
  agentscore_gate: { require_kyc: true, min_age: 21, allowed_jurisdictions: ['US'] },
});

import {
  buildJWKSResponse,
  generateUCPSigningKey,
  signUCPProfile,
  verifyUCPProfile,
} from '@agent-score/commerce';

// One-time per merchant: generate or load a key. Persist privateJWK in your secrets manager.
const { privateKey, publicJWK } = await generateUCPSigningKey({ kid: 'merchant-2026-05' });

// On every /.well-known/ucp request:
const profile = buildUCPProfile({
  name: 'My Agent Service',
  services: { /* keyed by service name, see above */ },
  payment_handlers: { /* keyed by handler reverse-DNS name, see above */ },
  signing_keys: [publicJWK],
});
const signed = await signUCPProfile(profile, {
  signingKey: privateKey,
  kid: publicJWK.kid,
  alg: 'EdDSA',
});
return c.json(signed);

// On /.well-known/jwks.json:
return c.json(buildJWKSResponse([publicJWK]));

import { Hono } from 'hono';
import { Checkout, pricingResult, validateShippingAgainstPolicy } from '@agent-score/commerce';
import { defaultA2aServices } from '@agent-score/commerce/discovery';

const checkout = new Checkout({
  rails: {
    tempo:     { recipient: process.env.TEMPO_RECIPIENT! },
    x402_base: { recipient: process.env.X402_BASE_RECIPIENT!, network: 'eip155:8453' },
    solana_mpp:{ recipient: process.env.SOLANA_RECIPIENT!,    network: 'solana:mainnet' },
    stripe:    { profileId: process.env.STRIPE_PROFILE_ID! },
  },
  url: 'https://merchant.example/purchase',
  preValidate: async (ctx) => {
    const body = (ctx.request.body ?? {}) as { product_slug?: string; shipping?: { country?: string; state?: string } };
    const product = await lookupProduct(body.product_slug);
    validateShippingAgainstPolicy({ country: body.shipping?.country ?? '', state: body.shipping?.state ?? '', policy: product, productName: product.name });
    return { product };
  },
  computePricing: async (ctx) => pricingResult({
    subtotalCents: ctx.state.product.priceCents,
    taxCents: ctx.state.product.taxCents,
    taxRate: ctx.state.product.taxRate,
    taxState: ctx.state.product.taxState,
  }),
  onSettled: async (ctx, outcome) => ({ ok: true, order_id: ctx.referenceId, tx_hash: outcome.txHash }),
  cdpApiKeyId:     process.env.CDP_API_KEY_ID,
  cdpApiKeySecret: process.env.CDP_API_KEY_SECRET,
  mppxSecretKey:   process.env.MPP_SECRET_KEY,
  gate: {
    apiKey: process.env.AGENTSCORE_API_KEY!,
    merchantName: 'Merchant',
    requireKyc: true, requireSanctionsClear: true, minAge: 21, allowedJurisdictions: ['US'],
  },
  // Optional: empty-body POSTs without a payment header auto-route to a sample 402
  // so x402 crawlers (awal x402 details, x402-proxy, ...) can discover the surface.
  discoveryProbe: {
    realm: 'merchant.example',
    sampleRail: 'tempo-mainnet',
    sampleAmountUsd: 1.0,
    sampleRecipient: process.env.TEMPO_RECIPIENT!,
  },
});

const app = new Hono();

// One-call mount: GET /.well-known/ucp + GET /.well-known/jwks.json + OPTIONS preflights.
// Express / Fastify have the same helper (`mountUcpRoutesExpress` / `mountUcpRoutesFastify`).
// Next.js / Web Fetch use file-based routing — call `buildSignedUcpResponse` directly inside the route handler.
checkout.mountUcpRoutesHono(app, {
  name: 'Merchant',
  wellKnownUcpUrl: 'https://merchant.example/.well-known/ucp',
  services: defaultA2aServices({ agentCardUrl: 'https://merchant.example/.well-known/agent-card.json' }),
  signingKid: 'merchant-2026-05',
});

app.post('/purchase', (c) => checkout.handleHono(c));

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

const gate = agentscoreGate({ apiKey: process.env.AGENTSCORE_API_KEY!, failOpen: true });
app.use('/purchase', gate);

app.post('/purchase', async (c) => {
  const { degraded, infraReason } = getGateDegradedState(c);
  if (degraded) console.warn(`[gate] degraded: ${infraReason}`);
  // ...
});