Agent Commerce Storefronts

OpenPermit storefronts are cooperative merchant integrations. The merchant exposes a discovery manifest plus catalog, quote, checkout, and order APIs. Agents can then use direct HTTPS, the SDK, or MCP wrappers to buy under an active mandate.

Merchant surface

The storefront publishes the same contract at the root or under a business page such as /shoes, /grocery, or /clothing:

• GET /.well-known/openpermit-storefront.json
• GET /api/products
• POST /api/checkout/quote
• POST /api/checkout/orders
• GET /api/orders/:orderId

For a business page, the URLs are scoped to that page, for example GET /grocery/.well-known/openpermit-storefront.json and POST /grocery/api/checkout/quote.

The checkout endpoint is protected with createSellerMiddleware. Missing payment returns 402 Payment Required; a paid retry creates the order.

Storefront manifests should include actions.buyerSetup so bare agents can redirect the user before they try checkout:

{
	"actions": {
		"buyerSetup": {
			"setupUrl": "https://openpermit.ai/onboarding?role=buyer&intent=agent-commerce&storefrontUrl=...",
			"nextAction": {
				"type": "openBrowser",
				"url": "https://openpermit.ai/onboarding?role=buyer&intent=agent-commerce&storefrontUrl=...",
				"label": "Set up OpenPermit buyer account"
			}
		}
	}
}

Seller SDK integrations can expose the same action directly from createSellerMiddleware:

createSellerMiddleware({
	client,
	sellerId,
	resourceId,
	paymentMethod: 'x402',
	paymentRequired: {
		buyerSetup: ({ request, challenge }) => ({
			setupUrl: buildBuyerSetupUrl(request.url, challenge.intent),
			nextAction: {
				type: 'openBrowser',
				url: buildBuyerSetupUrl(request.url, challenge.intent),
				label: 'Set up OpenPermit buyer account',
			},
		}),
	},
});

The SDK keeps the x402 payment headers intact and adds a Link: <setupUrl>; rel="openpermit-buyer-setup" header plus a JSON body with buyerSetup, so HTTP agents and LLM agents can handle the same response.

Agent HTTP path

MCP is optional. Any HTTP-capable agent can call:

POST /api/v1/agent/commerce/quote
POST /api/v1/agent/commerce/place-order

Example request:

{
	"storefrontUrl": "https://storefront.example",
	"mandateId": "mandate_...",
	"idempotencyKey": "order-run-001",
	"items": [{ "query": "shoes", "color": "white", "size": "42", "quantity": 2 }]
}

If the caller can authorize against a mandate but cannot sign x402 directly, place-order returns paymentCredentialRequired with the payment challenge, a setupUrl, and nextAction: { "type": "openBrowser" }. The agent client can open that URL to let the user set up the buyer account or wallet, then retry with a payment credential.

For local demos, OPENPERMIT_AGENT_COMMERCE_DEMO_SIGNER=1 can be used with a funded Monad testnet wallet.

Demo app

The monorepo includes apps/storefront-demo, which demonstrates realistic merchant pages:

• /shoes: Stride Supply, for the prompt "Buy me 2 pairs of white shoes, size 42."
• /grocery: FreshCart Market, for grocery basket examples.
• /clothing: Northline Apparel, for apparel examples with color and size constraints.

Each business page renders a realistic ecommerce storefront and exposes its own manifest, catalog, quote, checkout, and order APIs over live Monad testnet x402.