Collections
Collections are a user's grouped product instances - organized views of owned smart product copies.
The word names two things.
- A
Collectionentity is a curated, ordered grouping of smart products - a campaign such as On The Record's "Dear Stacks", or an events calendar. It has aslug, an owner, a source app and its own rules. SeertClient.collections. - A user's collection is an organized view of the product instances they own, described below. The protocol tracks ownership directly from on-chain state - this view is a presentation layer on top of that.
Collection types
| Type | Contents |
|---|---|
| All | Every instance owned by the user |
| By domain | PAGE, EVENT, PREDICTION or GAME instances |
| By product type | Instances of a specific type (e.g., all haikus) - grouped client-side from the domain feed |
The API filters by domain, not by product type. Grouping down to a specific type (haiku, tanka) is a presentation-layer concern - the Profile Hub buckets the returned rows by their parent productType.
API endpoints
The instances feed is cross-domain: editions, reservations, bracket entries and matches in one list, each row status-tagged.
| Method | Path | Description |
|---|---|---|
GET | /api/users/address/:stxAddress/instances | List all instances for a user |
GET | /api/users/address/:stxAddress/instances?domain=PAGE | Filter by domain (PAGE, EVENT, PREDICTION, GAME) |
GET | /api/users/address/:stxAddress/instances?status=CONFIRMED | Filter by transaction status |
Also accepts parentProductId, include=page, sortBy, sortOrder, page, and limit.
SDK hooks
const { data: instances } = useUserInstances(address, { domain: "PAGE" });Profile Hub integration
The Profile Hub app surfaces what a user holds at the /collected route, filtered by source app. Editions of a product the viewer owns are excluded there and shown under /made instead. /collections and /pages are retired and redirect.
Achievements
The progression ladder - awards derived from the event stream that open apps and mint invites, and the two read surfaces an app builds on.
Payment Currency Policy
How the protocol decides which currency a payment settles in - the app/collection accepted-currency policy and the user's preferred currency.