List marketplace listings

Search, filter, sort, and paginate cards listed for sale on the Phygitals marketplace.

GET /api/marketplace/marketplace-listings

List marketplace listings

cURL

curl --request GET \
  --url https://api.example.com/api/marketplace/marketplace-listings

200

{
  "listings": [
    {
      "address": "7YboEnrAwzA1BLYuH3QDCaMRaKxD1AvbYjvd2U71g3m4",
      "slug": "2024-charizard-psa-10",
      "name": "2024 Charizard PSA 10",
      "image": "https://cdn.phygitals.com/cards/charizard.png",
      "owner": "3BqtQbWXtcf73eScw7Rdu34Z2kLuJTziw1bH7RhmDyZm",
      "collection_address": "7QVm5bfXBEKHRKYVhhZm7QsP8GyoD1vFcuMGNaoUWV2x",
      "price": "125000000",
      "listed": true,
      "altFmv": 142.5,
      "marketplace": "TENSOR",
      "metadata": [
        { "key": "Title", "value": "2024 Charizard PSA 10" },
        { "key": "Category", "value": "Pokemon" },
        { "key": "Grader", "value": "PSA" },
        { "key": "Grade", "value": "10" }
      ],
      "offers": [],
      "mostRecentListActivity": { "time": "2026-06-01T12:00:00.000Z" }
    }
  ],
  "amount": 1284
}

Returns a paginated page of marketplace listings with metadata, open offers, and listing activity. Use this to build a buy-now catalog or price-comparison tooling.

No authentication required. This is a public read endpoint.

Query parameters

searchTerm · string

Free-text search matched against card name and metadata (for example title and cert number).

sortBy · string · default: "fmv-low-high"

Sort order. One of:

price-low-high, price-high-low, newest, recently-listed, name-asc, name-desc, fmv-low-high, fmv-high-low

page · integer · default: "0"

Zero-based page index. Page 0 is the first page.

itemsPerPage · integer · default: "24"

Page size. Maximum 200 items per request.

metadataConditions · string · default: "{}"

JSON object mapping metadata trait names to allowed values. Values are OR’d within a trait; traits are AND’d together.

Example: {"Category":["Pokemon"],"Grader":["PSA"]}

Trait names are matched case-insensitively and normalized to title case server-side (Category, Grader, etc.).

priceRange · string · default: "[null,null]"

JSON [min, max] listing price bounds in USD. Use null for an open bound.

Example: [10, 500]

fmvRange · string · default: "[null,null]"

JSON [min, max] fair-market-value bounds in USD. Use null for an open bound.

listedStatus · string · default: "any"

Listing filter: any, listed, or unlisted. Ignored when hasBorrowOffer=true.

collectionAddresses · string

JSON array of collection mint addresses to scope results. When omitted, defaults to the primary Phygitals marketplace collections.

hasBorrowOffer · boolean · default: "false"

When true, return only listings with an active Jupiter borrow offer attached. Each listing includes a _borrowOffer object. Forces listedStatus to any.

Example request

GET /api/marketplace/marketplace-listings?searchTerm=charizard&sortBy=price-low-high&page=0&itemsPerPage=24&listedStatus=listed&metadataConditions=%7B%22Category%22%3A%5B%22Pokemon%22%5D%7D&priceRange=%5Bnull%2C500%5D&fmvRange=%5Bnull%2Cnull%5D

Response

200

{
  "listings": [
    {
      "address": "7YboEnrAwzA1BLYuH3QDCaMRaKxD1AvbYjvd2U71g3m4",
      "slug": "2024-charizard-psa-10",
      "name": "2024 Charizard PSA 10",
      "image": "https://cdn.phygitals.com/cards/charizard.png",
      "owner": "3BqtQbWXtcf73eScw7Rdu34Z2kLuJTziw1bH7RhmDyZm",
      "collection_address": "7QVm5bfXBEKHRKYVhhZm7QsP8GyoD1vFcuMGNaoUWV2x",
      "price": "125000000",
      "listed": true,
      "altFmv": 142.5,
      "marketplace": "TENSOR",
      "metadata": [
        { "key": "Title", "value": "2024 Charizard PSA 10" },
        { "key": "Category", "value": "Pokemon" },
        { "key": "Grader", "value": "PSA" },
        { "key": "Grade", "value": "10" }
      ],
      "offers": [],
      "mostRecentListActivity": { "time": "2026-06-01T12:00:00.000Z" }
    }
  ],
  "amount": 1284
}

listings · array

Page of listing objects. Each row is a UniversalNFTData record with related metadata, offers, and listing timestamps included.

amount · number

Total number of listings matching the current filters (across all pages, not just this page).

Key listing fields

Field	Type	Description
address	string	On-chain mint / item id. Use as the card identifier in downstream marketplace calls.
slug	string	URL slug when present. Resolves on phygitals.com/card/:slug.
name	string	Display name.
image	string	Primary image URL.
price	string | null	List price in USDC base units (6 decimals). Divide by 1_000_000 for USD. null when not listed.
listed	boolean	Whether the item currently has an active list price.
altFmv	number | null	Fair-market value in USD from Alt (when available).
metadata	Array<{ key, value }>	Card traits (Title, Category, Grader, Grade, etc.).
offers	array	Open bids/offers on the item.
marketplace	"TENSOR" | "MAGICEDEN"	Aggregator the listing is sourced from, when applicable.
_borrowOffer	object | null	Present only when hasBorrowOffer=true. Jupiter borrow-offer terms (pubkey, principal_amount, apy_bps, expires_at, …).

Pagination

Request the next page by incrementing page while keeping other query parameters identical:

GET /api/marketplace/marketplace-listings?page=1&itemsPerPage=24&sortBy=price-low-high&listedStatus=listed

Stop when page * itemsPerPage >= amount.

Filter facets

Use GET /api/marketplace/filters to populate trait pickers (Set, Grader, Grade, etc.) before building metadataConditions.

Error responses

Status	Body	Cause
500	{ "error": "Internal server error" }	Unexpected server failure