Proposal: dev.ucp.shopping.eligibility — Machine-Readable Product Preconditions for Agent Commerce

[zologic]

Authors: Almin Zolotic ([Zologic](https://zologic.nl) / [UCPReady](#297)) · Douglas Borthwick ([Skye Meta](https://skyemeta.com) / [InsumerAPI](https://insumermodel.com))

---

Summary

We propose a new UCP capability extension — dev.ucp.shopping.eligibility — that enables businesses to declare machine-readable product preconditions in their UCP manifest and product catalog. AI agents can discover these conditions, obtain signed attestations autonomously, and satisfy them at checkout without human interaction.

---

Motivation

UCP currently has no mechanism for a business to declare that a product requires proof of eligibility before it can be purchased. This gap affects a wide range of real commerce scenarios:

• Token-gated products — wholesale pricing for wallets holding ≥$500 in stablecoins; NFT holder exclusives; community membership passes
• Credential-gated products — professional license required; age verification; KYC/compliance attestation
• Membership catalogs — products only available to subscribers or verified members

Today these requirements are enforced by human-interactive flows (a person clicks "Connect Wallet" or "Verify Identity" in a browser). AI agents cannot participate — they can discover the product but cannot obtain or present the required proof autonomously.

The result is that gated commerce is entirely excluded from the agentic commerce ecosystem UCP is building.

---

Prior Art

This proposal builds on the attestation_url pattern contributed to [KCP RFC-0004: Trust, Provenance, and Compliance](https://github.com/Cantara/knowledge-context-protocol/blob/main/RFC-0004-Trust-and-Compliance.md), which defines how AI agents discover and satisfy credential requirements before accessing structured knowledge. The pattern is mechanism-agnostic — on-chain tokens, Verifiable Credentials, OIDC, and SPIFFE all fit. We apply the same principle to commerce: conditions are declared in the manifest, attestations are obtained by the agent, verification happens server-side.

---

Proposed Design

1. Capability declaration in /.well-known/ucp

"dev.ucp.shopping.eligibility": [{
  "version": "2026-03-14",
  "extends": "dev.ucp.shopping.checkout",
  "config": {
    "jwks_uri": "https://api.insumermodel.com/.well-known/jwks.json",
    "supported_condition_types": [
      "token_balance",
      "nft_ownership",
      "eas_attestation",
      "farcaster_id"
    ],
    "precondition_field": "meta.attestation_jwt"
  }
}]

The jwks_uri points to the public key set used to verify attestation JWTs offline. The precondition_field tells agents where to include the JWT in their checkout request. The manifest declares the capability exists — the product declares the specific conditions.

2. Product-level eligibility block in catalog responses

{
  "id": "product_123",
  "title": "Wholesale Bundle",
  "price": 49900,
  "in_stock": true,
  "eligibility": {
    "gate_level": "purchase",
    "attestation_provider": "https://api.insumermodel.com/v1/attest",
    "conditions": [
      {
        "type": "token_balance",
        "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "chainId": 1,
        "threshold": 500,
        "decimals": 6,
        "label": "Hold ≥500 USDC on Ethereum"
      }
    ]
  }
}

gate_level has two values:

• "discovery" — product is hidden from catalog entirely until attestation is presented
• "purchase" — product is visible with conditions declared, but create_checkout rejects without a valid attestation JWT

For AI agents, "purchase" is the correct default: the agent needs to see the conditions to know what attestation to obtain.

3. Agent flow

ucp_list_products → sees eligibility block on product
                 → reads gate_level, conditions, attestation_provider
                 → calls attestation_provider with buyer wallet + conditions
                 → receives ECDSA/ES256-signed JWT
                 → calls create_checkout with meta.attestation_jwt = <JWT>

Business validates JWT offline:
  1. Fetch JWKS from jwks_uri (cached, 24h TTL)
  2. Verify ES256 signature
  3. Check exp (30 min validity window)
  4. Check sub matches checkout session's linked wallet identity
  5. Check jti has not been used (replay prevention)
  6. Verify conditionHash matches product's declared conditions
  7. Check pass = true
  → proceed / reject

No runtime call to the attestation provider at validation time — verification is entirely offline using cached public keys.

4. Attestation JWT structure (InsumerAPI reference implementation)

{
  "sub": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "jti": "ATST-7F2A9E3B1C8D4056",
  "iat": 1742825600,
  "exp": 1742827400,
  "conditionHash": "0x3a7f...",
  "pass": true,
  "results": [
    {
      "met": true,
      "chainId": 1,
      "type": "token_balance",
      "label": "Hold ≥500 USDC on Ethereum"
    }
  ]
}

conditionHash canonicalisation (for independent verification):

• Build evaluatedCondition object with fields: type, chainId, contractAddress, operator, threshold, decimals
• Sort keys alphabetically (Unicode code point order)
• JSON.stringify compact (no whitespace)
• SHA-256 → hex → prefix 0x

PHP (note: ksort() sorts in place and returns bool — two statements required):

ksort( $evaluated_condition );
$canonical = wp_json_encode( $evaluated_condition, JSON_UNESCAPED_SLASHES );
$computed  = '0x' . hash( 'sha256', $canonical );

(Thanks to [@douglasborthwick-crypto](https://github.com/douglasborthwick-crypto) for catching the one-liner bug — json_encode(ksort($condition), ...) would encode true, not the sorted array.)

---

Backwards Compatibility

• eligibility is an optional field on catalog items — omitting it is valid for all existing retail implementations
• dev.ucp.shopping.eligibility is declared only when the capability is active — stores that don't use it have no manifest changes
• No new required MCP tools — agents that don't support eligibility simply cannot purchase gated products, which is the correct degradation behaviour
• No changes to existing checkout state machine — rejection on missing/invalid attestation is a standard 400 with a precondition_failed message

---

Reference Implementations

UCPReady (WooCommerce) — implements the business-side: manifest capability declaration, product eligibility block surfacing, offline JWT validation via ucpready_checkout_preconditions filter, JWKS caching. Live endpoint: https://houseofparfum.nl/.well-known/ucp

InsumerAPI / SkyeWoo (Skye Meta) — implements the attestation-provider side: POST /v1/attest across 32 chains, ES256-signed JWTs, JWKS at /.well-known/jwks.json, per-product condition configuration in WooCommerce via SkyeWoo plugin. Zero merchant registration required — conditions are declared per product, evaluated dynamically. MCP server available: npx -y mcp-server-insumer

---

Scope and Generalisability

The capability is deliberately mechanism-agnostic. The attestation_provider URL on each product means any attestation provider can be used — on-chain token verification (InsumerAPI), Verifiable Credentials, OIDC identity tokens, Gitcoin Passport, or custom enterprise credential systems. The JWT structure with sub, jti, exp, conditionHash, and pass is a minimal standard that any provider can implement.

This generalises beyond token-gating to:

• Professional licensing — a medical supplier gates regulated products behind a verified pharmacist credential
• Age verification — an alcohol retailer requires an age attestation before checkout proceeds
• Geographic restrictions — a digital product gated behind a country attestation
• B2B procurement — wholesale pricing gated behind a verified business credential

All of these follow the identical agent flow: discover conditions → obtain attestation → present at checkout → validate offline.

---

Open Questions for the TC

1. Should gate_level: "discovery" require a separate query parameter for agents to present an attestation at catalog-query time, or is this out of scope for this proposal?
2. Should jti replay prevention be handled by the business (store the jti and reject reuse) or by the attestation provider (single-use codes)? We've implemented both — UCPReady stores used jti values with the session ID; InsumerAPI issues single-use attestations by default.
3. Should the capability support multiple attestation providers per product (AND/OR logic on conditions from different providers)?

---

We are both actively building on this — feedback and co-contributors welcome. Happy to draft a formal Enhancement Proposal if the TC finds this direction worth pursuing.

— Almin Zolotic ([zologic](https://github.com/zologic)) · Douglas Borthwick ([douglasborthwick-crypto](https://github.com/douglasborthwick-crypto))

[douglasborthwick-crypto]

Co-author here. This accurately reflects our technical discussion in #297 — the JWT structure, conditionHash canonicalization, and two-level gating model are all verified against the working implementation. Happy to answer questions on the attestation provider side.