# The marketplace model

GraveMarket indexes NFT collections across **nine chains** — `solana-mainnet`,
`ethereum-mainnet`, `polygon-mainnet`, `base-mainnet`, `bsc-mainnet`, `xrpl-mainnet`,
`cronos-mainnet`, `abstract-mainnet` and `robinhood-mainnet`.

Keep the chain and currency alongside each record. Item identifiers and price units depend on the chain.

```bash
npm install @solanadeads/gravemarket
```

```ts
import { GraveyardClient } from '@solanadeads/gravemarket';
const gmk = new GraveyardClient();   // public API — no key, no origin registration
```

## Collections

Addressable three ways — **slug** (`solana-deads`), **on-chain address**, or internal id.
Prefer the slug: it is stable, readable, and what the marketplace URLs use.

```ts
const c = await gmk.collections.get('solana-deads');
```

Related reads hang off the same identifier: `items`, `activity`, `stats`, `traits`,
`holders`, `offers`, `floor`.

## Items

An item is identified by **`token_address` plus `token_id`**.

Solana NFTs use a unique mint address and return `token_id: null`. EVM items use a contract address and token ID. Include the chain when combining items from several networks; contracts can use the same address on different chains.

```ts
const itemKey = (item) =>
  `${item.chain}:${item.token_address}:${item.token_id ?? ''}`;
```

## Listings and prices

`listing_price` and `listing_currency` are **nullable**, and null means **not listed** —
not free, and not zero.

```ts
const label = item.listing_price == null
  ? 'Not listed'
  : `${item.listing_price} ${item.listing_currency}`;
```

`listing_currency` and `floor_currency` identify the units, such as SOL, ETH or XRP. Compare or aggregate prices in the same currency. For cross-currency views, convert with an explicit exchange rate and show the conversion basis.

## Collection statistics {#stats-and-a-caveat-worth-reading}

```ts
const s = await gmk.collections.stats('solana-deads');
```

Returns headline stats plus a daily series — and **`wash_trade_count_7d`**.

The stats response reports `wash_trade_count_7d` separately from volume. Label unadjusted volume accordingly. For analytics that offer adjusted volume, use the documented option rather than subtracting a trade count from a currency amount.

## Activity

Sales and listings, either for one collection or globally:

```ts
await gmk.collections.activity('solana-deads', { limit: 50 });
await gmk.activity.list({ limit: 50 });
```

Use the activity endpoints for a collection feed or marketplace-wide view. The [MCP server](https://docs.deads.io/tools/mcp.md) also provides collection activity reads.

## Traits and rarity

```ts
const t = await gmk.collections.traits('solana-deads');
```

Every trait and value with counts — what a rarity filter is built from. Items carry
`rarity_rank` and `rarity_score`.

Rarity rank is relative to a collection and methodology. Display the collection with its rank and avoid using raw rank values to compare items across collections.

## Pagination {#pagination-—-cursors-and-why-a-partial-page-lies}

Collection and activity lists use cursor pagination. Read the response type for each endpoint; some return different list fields or pagination metadata.

```ts
let cursor;
const all = [];
do {
  const page = await gmk.collections.activity('solana-deads', { limit: 50, cursor });
  all.push(...page.data);
  cursor = page.cursor;
} while (cursor);
```

The SDK also exposes `listAll` / `activityAll` async generators that drain for you.

For full exports, follow the cursor until there are no more pages. For headline statistics, prefer the collection stats endpoint. The number of records loaded into a UI is the loaded count, not the collection total.

## How this differs from GraveMint

| | GraveMint v1 | GraveMarket v1 |
|---|---|---|
| purpose | **mint** a drop on your site | **read** marketplace state |
| credential | invite-only, origin-bound, collection-scoped | **none** |
| writes | prepare / execute | read-only |
| pagination | `limit` + `offset` | **cursor** |
| chains | Solana only | **nine** |

## Next

- [GraveMarket v1 API](https://docs.deads.io/api/gravemarket-v1.md) — request builders and response examples
- [Collection page recipe](https://docs.deads.io/recipes/collection-page.md) — a React example
- [GraveMarket SDK](https://docs.deads.io/sdk/gravemarket.md) — the typed client

---
Source: https://docs.deads.io/concepts/marketplace-model
Markdown: https://docs.deads.io/concepts/marketplace-model.md