@solanadeads/gravemint

Official TypeScript SDK for the GraveMint launchpad public API.

Read-only access to collections, NFTs, mint activity, discovery feeds, bounties, claim-code validation, and platform info.

• Zero runtime dependencies. Native fetch. Works in Node 18+, browsers, Bun, Deno.
• Dual build. ESM + CJS via exports map.
• Typed. Full .d.ts for every method and response.
• Rate-limit safe. Client-side token-bucket limiter + automatic retry with exponential backoff honoring Retry-After.

Install

npm install @solanadeads/gravemint

Node <18 needs a fetch polyfill (undici, node-fetch):

import { fetch } from "undici";
import { GraveMintClient } from "@solanadeads/gravemint";
const gm = new GraveMintClient({ apiKey: "...", fetch });

Quick start

import { GraveMintClient } from "@solanadeads/gravemint";

const gm = new GraveMintClient({ apiKey: process.env.GRAVEMINT_API_KEY! });

// Discovery
const trending = await gm.discovery.getTrending({ limit: 10 });
const live     = await gm.discovery.getLiveMints({ limit: 10 });
const upcoming = await gm.discovery.getUpcoming({ limit: 10 });

// Collection by shortId or on-chain address
const result = await gm.collections.get("absurdhorizons");
if ("collection" in result) {
  console.log(result.collection.name, result.stats.mintedCount, "/", result.stats.totalSupply);
  console.log(result.phases.active);
} else {
  console.log("pre-launch:", result.status, result.message);
}

// Recent mint activity
const mints = await gm.collections.getRecentlyMinted("absurdhorizons", { limit: 20 });

// Single NFT by mint address / token id
const nft = await gm.nfts.get("11111111111111111111111111111111");

// Platform
const caps   = await gm.platform.getCapabilities();
const prices = await gm.platform.getTokenPrices();

Configuration

new GraveMintClient({
  apiKey:       "...",                                            // required
  baseUrl:      "https://api.solanadeads.com/gravemint/public",   // default
  timeoutMs:    30_000,                                           // per request
  maxRetries:   3,                                                // 429 / 5xx / network
  rateLimit:    { requestsPerSecond: 5, burst: 10 },              // null to disable client-side limiter
  fetch:        globalThis.fetch,
});

Authentication

Generate an API key at gravemint.io. Every request sends X-API-Key. Server-to-server calls and browser calls from allowed origins both work. Don't embed a privileged key in a public bundle — issue a separate read-only key for client-side use and rotate it.

Rate limiting

The SDK's client-side limiter (default 5 RPS sustained, 10 RPS burst) stays under the server's per-IP ceiling. On a 429, the SDK reads Retry-After, waits, and retries up to maxRetries. After exhaustion, throws RateLimitError with .retryAfterMs.

Disable with rateLimit: null if you have your own queueing layer.

Resources

| Resource | Methods | | --------------------- | ------------------------------------------------------------------------------------------------ | | gm.discovery | getFeatured, getLiveMints, getTrending, getUpcoming, getRecentSoldouts, listCollections, searchCollections | | gm.collections | get, getGallery, getRecentlyMinted | | gm.nfts | get | | gm.bounty | getSummary, getPrizes | | gm.platform | getCapabilities, getTokenPrices | | gm.codes | validate (read-only — does not redeem) |

Identifiers

| Resource | Accepts | | ----------- | ------------------------------------------------------------- | | Collection | shortId (e.g. "absurdhorizons") OR collectionAddress / contractAddress | | NFT | mint_address (Solana) OR 0xContract:tokenId (EVM) OR plain numeric token_id |

Errors

import {
  GraveMintError, AuthError, RateLimitError, NotFoundError,
  ValidationError, ServerError, NetworkError, TimeoutError,
} from "@solanadeads/gravemint";

try {
  await gm.collections.get(id);
} catch (err) {
  if (err instanceof NotFoundError)        { /* 404 */ }
  else if (err instanceof RateLimitError)  { console.log("retry in", err.retryAfterMs); }
  else if (err instanceof AuthError)       { /* bad / missing key */ }
  else if (err instanceof ValidationError) { /* bad input */ }
  else if (err instanceof TimeoutError)    { /* request exceeded timeoutMs */ }
  else if (err instanceof NetworkError)    { /* DNS / TCP / TLS failure */ }
  else if (err instanceof ServerError)     { /* 5xx after retries */ }
  else throw err;
}

Every error exposes .status, .code, and .requestId for support tickets.

Testing

npm test            # unit tests (fake fetch, no network)
npm run typecheck   # tsc --noEmit
npm run build       # dual ESM + CJS output to dist/

License

MIT