@circles-market/catalog

Read-only access to aggregated operator catalogs (no auth).

Install

pnpm add @circles-market/catalog

Quickstart

import { CatalogClientImpl } from "@circles-market/catalog";

async function fetchFirstPage(marketApiBase: string, operator: string, sellers: string[]) {
  const catalog = new CatalogClientImpl(marketApiBase);

  const page = await catalog.fetchCatalogPage({
    operator,
    avatars: sellers,
    chainId: 100,
    pageSize: 50,
  });

  return page.items;
}

Demo app

A minimal runnable demo is included. It fetches the first catalog page and prints a compact summary.

Run it either from the monorepo root or from this package directory (requires Node 18+ for global fetch):

# Set your environment values (run these in your shell)
export MARKET_API_BASE="https://market-api.aboutcircles.com/market/"
export OPERATOR="0x31d5d15c558fbfbbbe604c9c11eb42c9afbf5140"

# Optional: comma-separated list of seller/avatar addresses to filter
export SELLERS="0xde374ece6fa50e781e81aac78e811b33d16912c7"

# Option B) From the package directory (no workspace flags):
# (run these commands inside packages/circles-market-catalog)
pnpm install
pnpm demo

If you omit SELLERS, the demo will request whatever the operator returns by default. The script exits with a helpful message if required env vars are missing.

Quickstart (lookup by seller + sku)

import { CatalogClientImpl } from "@circles-market/catalog";

async function fetchSellerSku(marketApiBase: string, operator: string, seller: string, sku: string) {
  const catalog = new CatalogClientImpl(marketApiBase);

  const item = await catalog
    .forOperator(operator)
    .fetchProductForSellerAndSku(seller, sku, { chainId: 100, maxPages: 10 });

  return item;
}

Reference

Concepts

• operator: operator address serving the aggregation endpoint
• avatars: seller/avatar addresses to include
• pagination:
  • cursor-based (X-Next-Cursor / cursor)
  • sometimes Link header (rel="next")
  • status 416: out-of-range / no more pages

API and return values

• fetchCatalogPage(query) → CatalogPage
• forOperator(operator).fetchCatalogPage(queryWithoutOperator) → CatalogPage
• forOperator(operator).fetchSellerCatalog(seller, opts?) → AggregatedCatalogItem[]
• forOperator(operator).fetchProductForSellerAndSku(seller, sku, opts?) → AggregatedCatalogItem | null

Types

CatalogPage

Fields:

• catalog: AggregatedCatalog | null (backend may omit)
• items: AggregatedCatalogItem[]
• nextCursor: cursor string or null
• nextLink: next URL or null
• status: HTTP status code

AggregatedCatalogItem

Fields:

• seller: seller/avatar address
• productCid: IPFS CID of product JSON-LD
• publishedAt: numeric timestamp (backend-defined unit)
• linkKeccak: link identifier/hash
• indexInChunk: position inside aggregation chunk
• product: SchemaOrgProductLite

SchemaOrgProductLite

Fields:

• sku, name: primary fields for checkout
• description?, image?, url?, brand?, mpn?, gtin13?, category?
• offers: SchemaOrgOfferLite[] (price/currency/availability/etc.)

Runtime notes

• Requires global fetch.
• There’s an internal 10s memoization cache for pages to avoid spamming the same URL.

Related packages

• @circles-market/cart uses SKUs + sellers from catalog results
• @circles-market/sdk gives you catalog + cart + orders in one client