---
title: "The PD API — Public Reads"
description: "The stable, public read endpoints of PriceOS — the catalog, a Project and its Outputs, people and their PriceSprite IDs, the activity feed, the market, PriceDays, stickers, keychains, $PRICE and the Exchange — with what each one answers. No key needed."
category: "building"
keywords: ["api", "rest", "endpoints", "developers", "json", "public api", "build on pd", "price token", "integrations"]
last_updated: "2026-10-19"
---

# The PD API — Public Reads

PriceOS answers plain HTTPS `GET` requests with JSON. These are the endpoints
PD commits to keeping — the app's own pages read them, and most of them power
[PDMCP](/docs/mcp) too. No key, no signup.

**How:** Send a GET to `https://pricediscussion.com` plus any path below; every answer is JSON.

- **Base URL:** `https://pricediscussion.com`
- **Open to every website.** Every endpoint on this page answers any origin
  (CORS `*`), so your own page can call it straight from the browser — no
  server needed. It never accepts credentials: a visitor's PD sign-in is
  never sent to, or usable from, your site.
- **The spec:** [`/openapi.json`](/openapi.json) describes every endpoint
  below in OpenAPI 3.1 — hand it to your tools or your LLM.
- **Times** are UTC (ISO strings, or seconds where named `_ts` / `end_time`).
  Prices are ETH. Token ids are 1-based.
- **Live, not cached for you:** most answers are `no-store`. Be kind: cache on
  your side and poll no faster than once a minute.
- **Stable means:** the paths and the fields documented here keep their
  meaning. New fields may appear; fields not listed here may change without
  notice.

For anything tokenized, the chain is the source of truth and outranks this
API — see [Building on PD](/docs/building-on-pd) for the contract reads.

## The catalog

### `GET /api/home`

The platform at a glance. `stats` — `projects`, `minted`, `volume_eth`,
`primary_eth`, `secondary_eth`, `top_projects`. `uploads` — every Project,
newest first: `slug`, `title`, `project_no`, `max_supply`, `minted_count`,
`artist_minted_count`, `sold_out_at`, `artist_minted_out`, `uploaded_at`.
`minting_now` — the same fields for what is still minting.

### `GET /api/stats`

Platform totals in one small object: `total_projects`, `total_minted`,
`total_holders`, `total_volume_eth`, `primary_volume_eth`,
`secondary_volume_eth`, `active_artists`, `artists_in_cooldown`.

### `GET /api/search?q={text}`

What the app's search finds: `projects`, `users`, `artworks`, `traits` and
more, each a short list of matches.

## A Project and its Outputs

### `GET /api/project/{slug}/outputs`

One Project: `project_id`, `total` minted, `artist_minted`, `artist_address`,
`contract_address`, `colorway`, `price_sprite`, `soundtrack`, its trait
vocabulary (`traits`, `subtraits`) and its minted `outputs` — each with
`token_id`, `owner` (+ `owner_handle`), `list_price_eth`, `mint_ts` and
`last_sale_ts`.

### `GET /api/project/{slug}/floor`

`{ project_id, floor_eth }` — the lowest live listing, or `null` when nothing
is listed.

### `GET /api/output/{slug}-{id}`

One Output, e.g. `/api/output/kiki-7`: `owner`, `minter`, `minted_at`,
`list_price_eth`, `last_sale_eth`, `symbol`, the full `traits` (artist traits
plus PD's platform traits — PriceDay, Sun, Moon, Rising, Fate…), the visual
`fingerprint` measured from the pixels, and `history` (every recorded event,
with prices).

## People

### `GET /api/user/{address}` · `GET /api/user/by-handle/{handle}`

A public profile: `address`, `handle`, `ens_name`, `user_number`,
`price_rank`, `price_score`, `price_streak`, `price_sprite` and
`price_sprite_resolved` (the parts the PriceSprite face is drawn from),
`sigil_forged_at`, `follower_count`, `following_count`, `profile_hex`,
`owned_projects`, `volume_spent_eth`. Only what anyone sees on the profile
page.

### `GET /api/user/{address}/outputs`

What a wallet holds: `total` and `holdings` — `slug`, `token_id`,
`list_price_eth`, `mint_ts`, `acquired_ts`, `last_sale_ts`.

### `GET /api/artist/{address}`

An artist's Projects (`id`, `title`, `minted_count`, `max_supply`,
`floor_price_eth`, `volume_eth`, `uploaded_at`, `sold_out_at`), their
`total_volume_eth`, and the between-releases cooldown (`cooldown_active`,
`cooldown_days_remaining`). A wallet shows as an artist only once its first
Project is on PD.

### `GET /api/artists`

Every artist on PD: `name`, `handle`, `address`, `status` (`active` or
`cooldown`).

## Activity and the market

### `GET /api/feed`

The platform's event feed, newest first: `events` with `type` (`MINT`,
`LIST`, `SALE`, `XFER`, `OFFER`, `OFFER_WITHDRAWN`, `OFFER_DECLINED`),
`project_id`, `token_id`, `from_address` / `to_address` (+ handles),
`price_eth` and `timestamp`.

| Option | What it does |
| --- | --- |
| `limit` | 1–100 (default 20) |
| `project_id` | one Project only |
| `address` | only events this wallet is on either side of |
| `types` | comma list, e.g. `SALE,LIST` |
| `order=price` · `dir=asc` | sort by price, or oldest first |

### `GET /api/marketplace`

The market right now: `listings` (`slug`, `token_id`, `price_eth`), recent
`events`, and `stats` — `listed`, `offers`, `volume_eth`, `top_projects`,
`top_sales`.

### `GET /api/priceday/{n}`

One finished [PriceDay](/docs/reference/glossary): its `date_label`, what
minted and uploaded, the biggest sale, its `tallies` (`mints`, `sales`,
`volume_eth`, `listings`, `offers`, `uploads`) and its almanac `story`.

### `GET /api/gas`

Live Ethereum gas: `baseFeeGwei`, `standardGwei`, `fastGwei`, `rapidGwei`,
`ethUsd`, `blockNumber`.

## Soundtracks

Every Project can carry a soundtrack: a YouTube playlist (usually a mix)
picked by its artist.

### `GET /api/soundtracks`

Every Project's soundtrack in one read, newest Project first: `slug`,
`title`, `playlist_id`, `url`, `embed_url` (drop it into an `<iframe>` to
play it) and `plays` (PD Plays).

### `GET /api/soundtrack/{slug}`

One Project's soundtrack facts: `info` — `kind` (`playlist` or `video`),
`tracks`, `playable`, `runtimeSec`, `maker` — and `plays`. `info` is `null`
when the Project has no soundtrack.

## Stickers, keychains, $PRICE and the Exchange

- **`GET /api/stickers/market?summary=1`** — every sticker sheet's market:
  `floor`, `listed`, `best_offer`, `last`, `volume`, `sales`, `peels`.
- **`GET /api/keychains/market?listed=1`** — keychains for sale. With
  `?meta=1`: the keychain contract and its royalty receiver.
- **`GET /api/keychains/{address}`** — the keychains a wallet holds, by number.
- **`GET /api/price/{address}`** — a wallet's [$PRICE](/docs/price-token/contract)
  balance (`balance_formatted`, `balance_wei`, `decimals`). $PRICE is
  official PD digital merch; its contract is fully readable on chain too.
- **`GET /api/exchange?board=1`** — open trades on [the Exchange board](/docs/exchange/the-board)
  anyone can fill: what each proposer `give`s and wants to `get`.
- **`GET /api/exchange/settled?since={seconds}`** — Exchange trades settled
  since that moment.

## Writing to PD

Every write in the app is signed by a wallet. Through the API:

- **Offers from agents and tools** go through `POST /api/agent/offer` —
  PDMCP's `prepare_offer` / `submit_offer` drive it, and the
  [PDMCP page](/docs/mcp#acting-for-someone) explains the flow. The offer's
  own signature proves who made it.
- **Buying and minting** need no API at all: they are transactions straight
  to the contracts (PDMCP's `prepare_buy` and `prepare_mint` build them).
- Everything else (follows, stars, profiles, listings made in the app) is
  signed in with [Sign-In With Ethereum](/docs/for-collectors/wallet-setup)
  inside the app and isn't a public interface.

## Building it with Claude (or any LLM)

Hand your model [`/openapi.json`](/openapi.json) and [`/llms.txt`](/llms.txt),
then ask for the thing. The full how-to — Claude, Claude Code, any other
model — and ten ideas to start from are on
[Building on PD](/docs/building-on-pd#building-with-claude-or-any-llm).

The artwork itself is a public image at
`https://pricediscussion.com/preview/{slug}/{id}.v2.png`, and every Output's
page is `https://pricediscussion.com/art/{slug}/{id}` — link back to it.

## House rules

The ones on [Building on PD](/docs/building-on-pd#house-rules): name your
tool as yours, honor the royalty, and ship it. If an endpoint you need isn't
here, ask in the [Discord](https://discord.gg/4tJr2txNCX).