Skip to main content

Documentation Index

Fetch the complete documentation index at: https://glide-9da73dea.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

ExportDescription
buildUcpProfile(args)Build a spec-conformant profile JSON. Defaults match Glide production surface.
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: 'agents@glide.co',
    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 match Glide’s production surface (USDC/USD/EUR/EURC/IDRX, US/EU/GB/LATAM/APAC, x402 + MPP + Stripe SPT, all three AP2 mandate types). Override any field to match a different deployment.

​
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 (OFAC primary sanctions programs). Override these when operating under a different regulatory posture. 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