OSP v3.0

The Open Storefront Protocol. One way for an agent to read a shop.

OSP defines how an agent discovers a storefront, reads its catalogue, agrees a price, and opens a checkout the buyer completes with the merchant. It is MIT licensed and needs nobody's permission to implement.

Read the specification GitHub

Architecture

Four layers. Adopt them one at a time, or stop after the first.

Each layer is independently versioned and independently optional. A storefront that publishes only discovery and catalogue is a conforming storefront.

01
Discovery
An agent resolves a brand's domain and fetches its manifest. The manifest declares the protocol version, the endpoint base, what authentication is needed, the rate limit tiers, and which capabilities the storefront supports. There is no central registry and no registration step.
GET /.well-known/osp.json
02
Query
The agent reads the catalogue. List, search, compare and recommend answer without a credential; a structured query with a typed intent goes to the query endpoint. Responses are product cards: title, price with a currency, availability, and a rating that is null when we cannot establish one.
GET /api/storefront/{brandId}/products · POST .../query
03
Agreement
A price an agent and a merchant arrive at, through an offer, a bundle, a price hold or a negotiation. Negotiation sits behind two merchant settings that must both be open, and a brand with no auto-optimization record is refused rather than defaulted.
POST .../offers/{offerId}/claim · POST .../negotiate
04
Checkout
A session priced from the catalogue, never from the request. Completing one creates a draft order on the merchant's own store and returns a link the buyer opens to pay the merchant. Cresva takes nothing and holds nothing.
POST .../checkout/sessions · POST .../complete

In code

Two calls. Neither needs a key.

Discovery tells an agent what a storefront supports. The catalogue read is the first thing it does with that. Both are run against the live API by the CI live job on every push, and both are yours to run from the commands below.

1. Find the storefront

terminal

curl https://api.cresva.ai/.well-known/osp.json

The manifest declares the protocol version, the capabilities this storefront supports, and the rate limits it enforces. No account, no key, no registration.

2. Read the catalogue

bash

curl "https://cresva.ai/api/storefront/cmqmr1f6j0003la04nu93f4k4/products?limit=1"

index.ts

const brandId = "cmqmr1f6j0003la04nu93f4k4";

const res = await fetch(
  `https://cresva.ai/api/storefront/${brandId}/products?limit=1`,
);

const { products } = await res.json();
console.log(products[0].title);

main.py

import httpx

brand_id = "cmqmr1f6j0003la04nu93f4k4"

res = httpx.get(
    f"https://cresva.ai/api/storefront/{brand_id}/products",
    params={"limit": 1},
)

print(res.json()["products"][0]["title"])

response

{
  "products": [
    {
      "title": "The Videographer Snowboard",
      "price": { "amount": 885.95, "currency": "USD" },
      "availability": "in_stock",
      "rating": null
    }
  ],
  "meta": { "total": 15, "page": 1, "response_time_ms": 49 }
}

Principles

Four decisions that the rest follows from.

Open

MIT licensed and published in full. Anyone can implement a client or a storefront without permission, royalties or registration, and the specification is developed in the open on GitHub.

Federated

Federated by design: the protocol needs no central server and no mandatory registry, and a storefront is addressed at a well-known URI the same way email and WebFinger decentralise. Today every Cresva storefront is served from cresva.ai, and self-hosting has not been implemented.

Agent-native

The consumer is a program, not a person with a browser. Responses are structured data, errors carry machine-readable codes and field-level detail, and pagination is page and limit based.

Composable

The layers are independent. A brand can publish discovery and query without ever enabling agreement or checkout, and an agent can read a catalogue without implementing either. Capability flags say which are on.

At a glance

The protocol in eleven rows.

Every figure here is read from lib/api-facts.ts, which the CI live job checks against the live API. It used to be a hand-written table, and it said v2.0 on a v3.0 page.

Specification: v3.0
Wire revision: 2026-03-01, in X-OSP-Version on every response
Query protocol: v1.0, negotiated through Accept
Transport: HTTPS, TLS 1.2 or later
Encoding: JSON, UTF-8
Discovery: /.well-known/osp.json
Authentication: None for reads. A bearer key for the rest.
Rate limits: 10/min anonymous, 60/min public key, 300/min secret key
Errors: A JSON envelope, {error:{code,message}}, with two documented variants
Webhooks: HMAC-SHA256 over the raw body
Licence: MIT

Status

What is shipped, and what is not.

One table, so nothing on this page can describe the same thing as beta in one place and planned in another.

Specification v3.0: shippedPublished in full, MIT licensed, open for comment on GitHub. It is a versioned draft maintained by Cresva, not a standards-body recommendation.
Storefront API: shippedDiscovery, catalogue, search, compare, recommend, offers, bundles, pricing, negotiation, checkout sessions, trust and certification, live on cresva.ai.
TypeScript client: shipped@cresva/osp on npm, MIT licensed. Types included.
Python client: buildingThe PyPI name is reserved as `cresva` and resolves at 0.0.2, which is a reservation rather than a client. The SDKs page reads the registry at build time and says what is installable today.
Conformance suite: shipped36 automated checks across five categories, weighted into one score. Runs against the data we already hold about your storefront, from the Cresva dashboard.
Storefront framework: plannedServer adapters that handle discovery, auth and rate limiting for an implementer. Nothing is released.

Use cases

What the protocol is for. Same four layers each time.

A shopping assistant

A conversational agent finds and compares products for someone. Discovery locates a storefront, the query layer reads its catalogue, and a checkout session hands the shopper a link to pay the merchant. The assistant stops at the link.

Price and stock monitoring

An agent watches price and availability across the storefronts it knows about. A structured response makes this a read rather than a scrape, and the merchant sees every request it made in their own log.

Procurement

An approved-vendor list built from discovery manifests, quotes requested through the agreement layer, and bids compared on structured attributes rather than on parsed web pages.

Catalogue distribution

The same catalogue, rendered in the shape a specific platform expects: a Google Merchant feed, a Meta catalog, a ChatGPT-tailored OpenAPI document, a Perplexity configuration. One source, four surfaces.

Alternatives

How this is done today. And what each one cannot do.

Scraping a storefront: Breaks on a redesign, is blocked by bot defences, and gives the merchant no way to say what an agent may or may not do. There is no price to agree and no order to place.
An affiliate feed: Read-only product data, limited to the networks a brand has joined, in a different shape per network. Nothing to negotiate against and nothing to check out through.
An embedded widget: Needs a browser to render it, so a headless agent cannot consume it at all.
A bespoke brand API: Works, and every brand's is different. An agent maintains one integration per merchant, and a merchant maintains one per agent that asks.

Read it, then implement it. In that order.

The specification is the authority on everything this page summarises. It is public, MIT licensed, and open for comment.

Specification v3.0 Quickstart

What changed in v3.0