# Shopify Agent Data

Machine-readable Shopify store data aggregated from public storefronts
(collections, categories, products, trends, and each store's agents.md
and sitemap.xml), sold over the x402 payment protocol. Built for AI
agents; also usable by humans with a Base wallet. Data is refreshed on a
recurring schedule as new stores are added.

## Payments

- Protocol: x402
- Network: base mainnet (chain 8453)
- Asset: USDC
- Pay to: 0xeae48f1e0d58a58bdff4bce24941c8d80f71a999
- Facilitator: Coinbase CDP
- Machine manifest: /.well-known/x402
- OpenAPI spec (response schemas): /api/openapi.yaml

Requests to paid endpoints without a valid X-PAYMENT header return HTTP
402 with the payment requirements. Attach an x402 payment and retry.

## Repeat access (no double charge)

- A settled paid request returns an X-Entitlement response header.
- Send it back as the X-Entitlement request header to re-fetch that
  same page (any query) for free, forever — no second payment.
- Tokens are signed, never expire, and are bound per-payer + per-page.

## Free endpoints (no payment)

- GET /api/stats - Network-wide totals and last refresh time. (schema: NetworkStats)
- GET /api/pricing - Machine-readable price list for every paid endpoint. (schema: PricingInfo)
- GET /api/stores - Directory of indexed stores (summary only). (schema: StoreListResponse)
- GET /api/categories - Category directory across the network. (schema: CategoryListResponse)
- GET /api/facets - Faceted filter counts across the store directory. (schema: StoreFacets)
- GET /api/trends/preview - Small free sample of current trend data. (schema: TrendsPreview)
- GET /api/submissions - Recently submitted stores and their crawl status. (schema: SubmissionListResponse)
- POST /api/submissions - Submit a public store URL to be crawled and indexed. (schema: Submission)

## Paid endpoints

- GET /api/stores - $0.01 - Store directory: browse and filter every tracked store. (schema: ListStoresResponse)
- GET /api/products - $0.01 - Full-text product search across every indexed store. (schema: ProductListResponse)
- GET /api/stores/{id} - $0.02 - Full store profile with collections, vendors and agents.md. (schema: StoreProfile)
- GET /api/stores/{id}/products - $0.02 - Complete product catalog for a single store. (schema: ProductListResponse)
- GET /api/collections - $0.02 - Aggregated collections across all tracked stores. (schema: CollectionListResponse)
- GET /api/trends/new-arrivals - $0.02 - Newest products indexed across the network. (schema: ProductListResponse)
- GET /api/trends/price-drops - $0.02 - Products currently discounted below their compare-at price. (schema: PriceDropListResponse)
- GET /api/trends/restocks - $0.02 - Products that recently returned to stock. (schema: ProductListResponse)
- GET /api/trends/trending-categories - $0.02 - Categories ranked by recent catalog activity. (schema: TrendingCategoryListResponse)
- GET /api/trends/top-vendors - $0.02 - Vendors ranked by catalog footprint. (schema: TopVendorListResponse)
- GET /api/agents-md - $0.01 - Directory of every store's agents.md manifest. (schema: AgentsMdListResponse)
- GET /api/export - $0.50 - Bulk JSON export of the full stores and products dataset. (schema: DatasetExport)

## For humans

Prefer plain language? See /humans.md for a non-technical explanation
of this service and how to set up a Base wallet.

## AI crawler / LLM discovery

- /llms.txt - short summary for LLM-based crawlers and answer engines
- /humans.md - this service, explained for people