@glideco/ucp-profile

Builder and parser for the Universal Commerce Profile (UCP) v0.1-2026-04. Publishes the /.well-known/ucp.json discovery document for buyer-agent runtimes.

Builder and parser for the Universal Commerce Profile (UCP), the discovery layer defined by Google and Shopify that sits above AP2 (mandates) and ACP (commerce). UCP-aware agent runtimes — Google’s commerce-router, Shopify Sidekick, and 20+ endorsed partners including Wayfair, Target, and Walmart — fetch /.well-known/ucp.json on first contact to learn which mandate types, payment rails, currencies, regions, and agent-identity formats a merchant supports before choosing whether to engage.

This package is a wire-format adapter, not the source of truth for the UCP spec. When UCP ships a new version that breaks the profile schema, a new minor is published and UCP_SPEC_VERSION is bumped. Because this package imports AP2_SPEC_VERSION from @glideco/ap2-adapter and ACP_SPEC_VERSION from @glideco/acp-merchant, a version bump in either underlying spec propagates to the published profile automatically.

Install

npm install @glideco/ucp-profile

npmjs.com/package/@glideco/ucp-profile

What the profile covers

The profile is a JSON document at /.well-known/ucp.json that answers the questions an agent runtime asks before initiating a commerce session:

• Rails — which payment rails are accepted (x402, mpp-tempo, stripe-spt, etc.)
• Protocols — which commerce protocols the merchant speaks (ap2, acp, mcp, x402, mpp)
• Endpoints — URL + pinned spec version per protocol
• Mandates — which AP2 mandate types are accepted (IntentMandate, CartMandate, PaymentMandate)
• Agent identities — trusted DID schemes (did:key, did:web, erc-8004)
• Compliance — whether OFAC/sanctions screening and KYA checks are active
• Regions / currencies — accepted ISO 3166-1 + ISO 4217 / stablecoin ticker sets

The profileSupports function lets a smart-router filter profile documents against required capabilities without loading the full schema each time.

Spec version

Pinned to UCP 0.1-2026-04 — exported as UCP_SPEC_VERSION. The ucpVersion field in the served JSON must equal this constant; strict UCP validators (Google’s commerce-router, Shopify Sidekick) reject profiles with an unrecognized version.

The protocols field uses a closed enum from the UCP spec: ap2, acp, mcp, x402, mpp. Custom or legacy protocol identifiers must go under an x-<vendor>: extension namespace, not in the closed enum.

API surface

Export	Description
buildUcpProfile(args)	Build a spec-conformant profile JSON. Defaults require deployment-specific verification.
parseUcpProfile(input)	Parse + Zod-validate a remote profile (for smart-router filtering). Throws on schema violation.
profileSupports(profile, required)	Return true if a profile satisfies a required capability set.
UCP_SPEC_VERSION	'0.1-2026-04' — version constant echoed in the profile.
UCP_PROFILE_PATH	'/.well-known/ucp.json' — canonical publish path.

Serving the profile

// apps/web/src/app/.well-known/ucp.json/route.ts
import { buildUcpProfile } from '@glideco/ucp-profile';

export async function GET() {
  const profile = buildUcpProfile({
    domain: 'glide.co',
    name: 'Glide',
    contactEmail: '[e-mail]',
    compliance: {
      sanctionsScreening: true,
      kya: true,
      sanctionsProvider: 'chainalysis',
    },
    sla: { uptime: '99.95%', responseP95Ms: 280 },
  });

  return Response.json(profile, {
    headers: { 'Cache-Control': 'public, max-age=3600' },
  });
}

The default rails, currencies, regions, endpoints and acceptedMandates are package metadata. Set them to the capabilities actually enabled in your deployment before publishing the profile. They do not establish consumer corridor availability; see Send money.

Filtering profiles in the smart-router

import { parseUcpProfile, profileSupports } from '@glideco/ucp-profile';

async function findCompatibleMerchant(candidates: string[]) {
  for (const domain of candidates) {
    const res = await fetch(`https://${domain}/.well-known/ucp.json`);
    let profile;
    try {
      profile = parseUcpProfile(await res.json());
    } catch {
      continue; // schema violation → skip
    }

    if (profileSupports(profile, {
      rails: ['x402'],
      currencies: ['USDC'],
      regions: ['US'],
      mandates: ['IntentMandate'],
    })) {
      return profile;
    }
  }
  return null;
}

Compliance posture defaults

buildUcpProfile defaults compliance.sanctionsScreening and compliance.kya to true, and compliance.sanctionsProvider to 'chainalysis'. The default excludedRegions list includes IR, KP, SY, and CU as package defaults. These defaults are not a current legal determination. Configure the profile to match your screening service and applicable requirements.

Country and currency fields are validated as uppercase — lowercase 'us' or 'usd' throws at build time because UCP-aware agent runtimes use byte-equality on those strings, not case-insensitive comparison.

Reading list

• ConnectorManifest standard — how protocol capabilities are declared for Glide connectors.
• @glideco/ap2-adapter — mandate protocol whose version is re-exported by this package.
• @glideco/acp-merchant — commerce protocol whose version is re-exported by this package.
• Source on GitHub