# GraveMarket v1 API

Base URL — `https://api.solanadeads.com/gravemarket/v1`

The marketplace read API. Browse collections, read an item, follow sales activity, pull
traits and holders.

> **TIP: Public reads, with optional SDK authentication**
These read consoles currently send requests without an `X-API-Key` header. For an integration you intend to maintain, follow the [published SDK's API-key guidance](https://docs.deads.io/sdk/gravemarket.md#api-keys): the SDK accepts a key, and its documentation recommends obtaining one because anonymous access is planned to change.

GraveMint has a different access model. Read [keys and origins](https://docs.deads.io/guides/keys.md) before integrating its mint flows.

Prefer the SDK — it gives you typed responses, retries and pagination helpers:

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

```ts
import { GraveyardClient } from '@solanadeads/gravemarket';
const gmk = new GraveyardClient();
```

## Identifiers

A collection is addressable three ways, and every console below accepts any of them:

| form | example |
|---|---|
| **slug** | `solana-deads` |
| **on-chain address** | `7ZYBDpPou8EehaYz6nUPExy5DU1bL3E64P5AKtikwZnh` |
| internal id | `b2a30c10-0ba7-4ca8-9482-397324dc64bf` |

Prefer the slug: it is stable, readable, and what the marketplace URLs use.

## Try it live

Examples are available below in JavaScript, TypeScript and cURL.

Every console runs against **our own collection**, `solana-deads`.

### Browse collections


#### GET /collections

Paginated browse. Returns a cursor — see Pagination below.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| limit | query | No | 3 |  |
| chain | query | No |  | e.g. solana-mainnet. Omit for every chain. |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const result = await market.collections.list({
  limit: 3,
});
console.log(result);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError, type CollectionsListResponse } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const result: CollectionsListResponse = await market.collections.list({
    limit: 3,
  });
  console.log(result);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/collections?limit=3'
```




#### GET /collections/meta

The chains and categories the marketplace currently indexes — use it to build filters rather than hardcoding a list.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const meta = await market.collections.meta();
console.log(meta);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError, type CollectionMeta } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const meta: CollectionMeta = await market.collections.meta();
  console.log(meta);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/collections/meta'
```



### One collection


#### GET /collections/{id}

Full detail: stats, floor, verification, chain and standard.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| id | path | Yes | solana-deads |  Options: solana-deads (solana-deads (slug)); 7ZYBDpPou8EehaYz6nUPExy5DU1bL3E64P5AKtikwZnh (on-chain address) |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const result = await market.collections.get("solana-deads");
console.log(result);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError, type CollectionDetail } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const result: CollectionDetail = await market.collections.get("solana-deads");
  console.log(result);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/collections/solana-deads'
```




#### GET /collections/{id}/stats

Headline stats plus a daily series. Includes wash_trade_count_7d — volume figures elsewhere are not filtered for it, so read this before quoting volume.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| id | path | Yes | solana-deads |  |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const stats = await market.collections.stats("solana-deads");
console.log(stats);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError, type CollectionStatsResponse } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const stats: CollectionStatsResponse = await market.collections.stats("solana-deads");
  console.log(stats);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/collections/solana-deads/stats'
```



### Items and listings


#### GET /collections/{id}/items

Items in the collection, with listing state.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| id | path | Yes | solana-deads |  |
| limit | query | No | 3 |  |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const items = await market.collections.items("solana-deads", {
  limit: 3,
});
console.log(items);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError, type CollectionItemsResponse } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const items: CollectionItemsResponse = await market.collections.items("solana-deads", {
    limit: 3,
  });
  console.log(items);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/collections/solana-deads/items?limit=3'
```




#### GET /collections/{id}/offers

Standing offers against the collection.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| id | path | Yes | solana-deads |  |
| limit | query | No | 3 |  |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const offers = await market.collections.offers("solana-deads", {
  limit: 3,
});
console.log(offers);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError, type CollectionOffersResponse } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const offers: CollectionOffersResponse = await market.collections.offers("solana-deads", {
    limit: 3,
  });
  console.log(offers);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/collections/solana-deads/offers?limit=3'
```



### Activity


#### GET /collections/{id}/activity

Sales and listings for one collection — the secondary-market context that pairs with a GraveMint drop.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| id | path | Yes | solana-deads |  |
| limit | query | No | 3 |  |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const activity = await market.collections.activity("solana-deads", {
  limit: 3,
});
console.log(activity);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const activity = await market.collections.activity("solana-deads", {
    limit: 3,
  });
  console.log(activity);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/collections/solana-deads/activity?limit=3'
```




#### GET /activity

Global activity across the marketplace.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| limit | query | No | 3 |  |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const result = await market.activity.list({
  limit: 3,
});
console.log(result);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const result = await market.activity.list({
    limit: 3,
  });
  console.log(result);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/activity?limit=3'
```



### Traits and holders


#### GET /collections/{id}/traits

Every trait and value, with counts — what you build a rarity filter from.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| id | path | Yes | solana-deads |  |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const traits = await market.collections.traits("solana-deads");
console.log(traits);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError, type CollectionTraitsResponse } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const traits: CollectionTraitsResponse = await market.collections.traits("solana-deads");
  console.log(traits);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/collections/solana-deads/traits'
```




#### GET /collections/{id}/holders

Holder distribution, with unique_holders.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| id | path | Yes | solana-deads |  |
| limit | query | No | 3 |  |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const holders = await market.collections.holders("solana-deads", {
  limit: 3,
});
console.log(holders);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError, type CollectionHoldersResponse } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const holders: CollectionHoldersResponse = await market.collections.holders("solana-deads", {
    limit: 3,
  });
  console.log(holders);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/collections/solana-deads/holders?limit=3'
```



### Search


#### GET /search

Searches collections, items, profiles and traits in one call — the response is split by kind.

Authentication: these documented public read examples omit X-API-Key; see the SDK guide for optional API-key guidance.

| Parameter | Location | Required | Default example | Guidance |
| --- | --- | --- | --- | --- |
| q | query | Yes | deads |  |
| limit | query | No | 3 |  |
| type | query | No |  | collection \| item \| trait. Omit for all. |

**JavaScript**

```js
import { GravemarketClient } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

const result = await market.search.query({
  q: "deads",
  limit: 3,
});
console.log(result);
```

**TypeScript**

```ts
import { GravemarketClient, GravemarketApiError, type SearchResponse } from "@solanadeads/gravemarket";

const market = new GravemarketClient();

try {
  const result: SearchResponse = await market.search.query({
    q: "deads",
    limit: 3,
  });
  console.log(result);
} catch (err) {
  // `code` is stable — branch on it. `message` is a sentence you can show a user.
  if (err instanceof GravemarketApiError) console.error(err.code, err.message);
  else throw err;
}
```

**cURL**

```bash
curl -s \
  'https://api.solanadeads.com/gravemarket/v1/search?q=deads&limit=3'
```



## Pagination

List endpoints are **cursor**-paginated and return `cursor` and `hasMore`:

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

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

For a complete export, follow the cursor until there are no more pages. Use the statistics endpoints for headline totals; the number of records loaded into a UI is not the collection total.

## Differences from GraveMint v1

| | GraveMint v1 | GraveMarket v1 |
|---|---|---|
| credential | `gm_pub_` / `gm_live_`, invite-only | **none** |
| origin binding | required | n/a |
| collection scope | key is confined to its drops | n/a — public data |
| writes | prepare / execute a mint | **read-only** |
| pagination | `limit` + `offset` | **cursor** |

## Related

- [GraveMarket SDK](https://docs.deads.io/sdk/gravemarket.md) — the typed client, generated from the published package
- [GraveMint v1 API](https://docs.deads.io/api/gravemint-v1.md) — minting on your own site

---
Source: https://docs.deads.io/api/gravemarket-v1
Markdown: https://docs.deads.io/api/gravemarket-v1.md