Universal Commerce Protocol

UCP Integration

Solid# implements Google's open Universal Commerce Protocol (UCP) as a hierarchical agent graph. Buyer-agents discover, browse, and transact with Solid# tenants over a signed wire format — gated by an explicit owner consent ladder.

UCP is the public buyer-agent interface. If you're an operator of your own Solid# tenant and want your AI editor (Claude Desktop, Cursor, Windsurf) to drive the platform, you want MCP instead.

Quick Start — Discovery

Every UCP integration starts with a discovery hit on the platform profile. No auth required for read-only discovery.

Platform profile

curl https://api.solidnumber.com/.well-known/ucp

Returns a signed platform_profile envelope (ECDSA P-256, RFC 9421-aligned). Use the embedded signing_keys[] to verify.

Tenant business profile

curl https://api.solidnumber.com/co/{company_id}/.well-known/ucp

Returns 404 until that tenant's owner has walked rung-1 of the consent ladder. Returns the signed business_profile (with capabilities[]) once enabled.

Three-Tier Hierarchy

Stock UCP assumes one merchant = one checkout endpoint. Solid# is multi-tenant and multi-agent — we expose the agent graph through UCP, not just a checkout endpoint.

Platform

Solid# itself. Single platform_profile at api.solidnumber.com/.well-known/ucp. Discovery layer; declares Solid# as a marketplace, not a single merchant.

Company

Per-tenant business_profile. One owner UCP agent (default ADA) per company. Per-company signing keys.

Sub-Agent

Functional roles: sales / AR / AP / commissions / service / inventory / compliance / marketing / industry-vertical. Each is an existing Solid# agent_type promoted to UCP-addressable.

Owner Consent — The Multi-Ladder

A Solid# tenant's UCP presence is never auto-enabled. The company owner walks a 4-rung ladder; every rung defaults OFF; nothing in UCP runs without the matching grant.

Rung 1 — company

Company is UCP-discoverable

Rung 2 — role

Sub-agent role activates (sales / AR / AP / etc.)

Rung 3 — capability

Specific capabilities each role serves

Rung 4 — threshold

Auto-approval ceilings (e.g., negotiate ≤10% off)

Revocation is immediate. In-flight sessions complete; no new sessions accept the revoked capability. Every grant + revocation writes an append-only audit event.

Capabilities

Available today

GET

core/marketplace

Solid# tenant marketplace participation + headline counts

role: owner

GET

core/signal/topics

Agent-facing event vocabulary for a tenant

role: owner

GET

core/signal/tail

Poll a tenant's recent events on a topic (stateless cursor)

role: owner

GET

core/inbound/endpoints

List inbound webhook endpoints a tenant accepts (no secrets returned)

role: owner

GET

core/catalog/products

Tenant's active products with public-safe fields + freshness envelope

role: sales

GET

core/catalog/services

Tenant's active services (respects show_services / show_pricing toggles)

role: sales

Roadmap

PLANNED

core/availability

Read calendar slots for a tenant

PLANNED

core/booking

Book an appointment (idempotency-key required)

PLANNED

core/inquiry

KB search / Q&A

PLANNED

core/content

CMS pages + blog content

PLANNED

core/checkout

AP2-mediated checkout via tenant's payment processor

PLANNED

com.solidnumber.sales.negotiate

Agent-mediated price/term negotiation

PLANNED

com.solidnumber.ar.invoice_create

Issue an invoice via the AR sub-agent

PLANNED

com.solidnumber.psp.l3_enrichment

Level-3 SKU enrichment for B2B card transactions

PLANNED

com.solidnumber.governance.consent_ladder

Query a tenant's grant state before issuing a request

Authentication

Read-only capabilities accept a UCP-Agent header alone. Write capabilities require RFC 9421 HTTP Message Signatures (ECDSA-P256-SHA256) plus an Idempotency-Key.

Read-only request

curl https://api.solidnumber.com/co/61/ucp/capabilities/core/catalog/products \
  -H 'UCP-Agent: profile="https://your-domain/.well-known/ucp"'

Write request (forthcoming)

curl -X POST https://api.solidnumber.com/co/61/ucp/capabilities/core/booking \
  -H 'UCP-Agent: profile="https://your-domain/.well-known/ucp"' \
  -H 'Idempotency-Key: <opaque b64url, ≥128 bits entropy>' \
  -H 'Content-Digest: sha-256=:<base64>:' \
  -H 'Signature-Input: ucp=("@method" "@target-uri" "content-digest" \
       "ucp-agent" "idempotency-key");created=...;keyid="...";alg="ecdsa-p256-sha256"' \
  -H 'Signature: ucp=:<base64>:' \
  -d '{"slot_id": "...", "customer": {...}}'

Error Envelope

HTTP	error	When
401	signature_verification_failed	RFC 9421 signature missing or invalid
403	capability_not_authorized	Tenant's owner has not granted this capability
404	—	Tenant has not walked rung-1 of consent ladder
409	idempotency_key_replayed	Same Idempotency-Key reused within 24h
503	capability_not_configured	Consent granted but no sub-agent row (server-side gap)

REST API MCP Tools CLI Authentication

UCP is an open standard authored by Google + retail partners. Spec: github.com/Universal-Commerce-Protocol/ucp (Apache 2.0).

UCP Integration

Quick Start — Discovery

Three-Tier Hierarchy

Platform

Company

Sub-Agent

Owner Consent — The Multi-Ladder

Capabilities

Available today

Roadmap

Authentication

Error Envelope

Related