# GraveMarket SDK — method reference **`@solanadeads/gravemarket`** · version **0.3.1** · install with `npm i @solanadeads/gravemarket` Signatures and types are generated from the published package. Explanatory prose is edited for clarity. For how to put them together, start with the [GraveMarket SDK guide](https://docs.deads.io/sdk/gravemarket.md). ```ts import { GravemarketClient } from "@solanadeads/gravemarket"; const client = new GravemarketClient(); ``` ## Contents - [`client.collections`](#client-collections) — 18 methods - [`client.creators`](#client-creators) — 3 methods - [`client.items`](#client-items) — 8 methods - [`client.orders`](#client-orders) — 5 methods - [`client.activity`](#client-activity) — 2 methods - [`client.search`](#client-search) — 2 methods - [`client.analytics`](#client-analytics) — 5 methods - [`client.recommendations`](#client-recommendations) — 1 method - [`client.platform`](#client-platform) — 9 methods - [`client.affiliates`](#client-affiliates) — 2 methods - [`client.config`](#client-config) — 1 method - [`client.smartMoney`](#client-smartmoney) — 3 methods - [`client.walletAnalytics`](#client-walletanalytics) — 2 methods - [`client.trust`](#client-trust) — 2 methods - [Functions](#functions) — 13 - [Classes](#classes) — 5 - [Types](#types) — 160 ## `client.collections` ### `collections.meta()` ```ts meta(): Promise; ``` ### `collections.launches()` ```ts launches(query?: LaunchesQuery): Promise; ``` ### `collections.sparklines()` ```ts sparklines(query: SparklinesQuery): Promise; ``` ### `collections.list()` ```ts list(query?: ListCollectionsQuery): Promise; ``` ### `collections.get()` ```ts get(id: string): Promise; ``` ### `collections.items()` ```ts items(id: string, query?: CollectionItemsQuery): Promise; ``` ### `collections.activity()` ```ts activity(id: string, query?: CollectionActivityQuery): Promise>; ``` ### `collections.stats()` ```ts stats(id: string, query?: CollectionStatsQuery): Promise; ``` ### `collections.traits()` ```ts traits(id: string): Promise; ``` ### `collections.holders()` ```ts holders(id: string, query?: HoldersQuery): Promise; ``` ### `collections.offers()` ```ts offers(id: string, query?: { limit?: number; }): Promise; ``` ### `collections.traitFloors()` ```ts traitFloors(id: string): Promise; ``` ### `collections.traitPricingSummary()` ```ts traitPricingSummary(id: string): Promise; ``` ### `collections.crossChain()` ```ts crossChain(id: string): Promise; ``` ### `collections.analytics()` ```ts analytics(id: string, query?: { period?: string; }): Promise; ``` ### `collections.floor()` ```ts floor(id: string): Promise; ``` ### `collections.listAll()` ```ts listAll(query?: ListCollectionsQuery): AsyncGenerator; ``` ### `collections.activityAll()` ```ts activityAll(id: string, query?: CollectionActivityQuery): AsyncGenerator; ``` ## `client.creators` Public creator pages — brand pages (e.g. /creators/buxdao) grouping multiple collections under one creator. Read-only; only published pages are visible. ### `creators.list()` Paginated list of published creator pages. ```ts list(query?: CreatorPagesQuery): Promise; ``` ### `creators.get()` A creator page (by slug) with its member collections and stats. ```ts get(slug: string): Promise; ``` ### `creators.byCollection()` The published creator page housing a collection (UUID), or null. ```ts byCollection(collectionId: string): Promise; ``` ## `client.items` ### `items.get()` Fetch an item by Solana mint address or EVM `contract:token_id`. Pass `{ chain }` when a contract exists on more than one chain — see {@link ItemChainHint}. ```ts get(id: string, opts?: ItemChainHint): Promise; ``` ### `items.activity()` ```ts activity(id: string, query?: ItemActivityQuery): Promise>>; ``` ### `items.offers()` ```ts offers(id: string, query?: ItemOffersQuery): Promise>; ``` ### `items.listings()` ```ts listings(id: string, query?: ItemListingsQuery): Promise>; ``` ### `items.traits()` ```ts traits(id: string, opts?: ItemChainHint): Promise; ``` ### `items.neighbors()` ```ts neighbors(id: string, query?: ItemNeighborsQuery): Promise; ``` ### `items.priceHistory()` ```ts priceHistory(id: string, query?: ItemPriceHistoryQuery): Promise; ``` ### `items.rarity()` Convenience wrapper for rarity rank/score/tier. Resolves to `{ rank, score, tier, total_supply }`. ```ts rarity(id: string, opts?: ItemChainHint): Promise; ``` ## `client.orders` ### `orders.aggregatedListings()` ```ts aggregatedListings(collectionId: string, query?: AggregatedListingsQuery): Promise; ``` ### `orders.bestPrice()` ```ts bestPrice(tokenAddress: string, query: { chain: string; }): Promise; ``` ### `orders.aggregatedFloor()` ```ts aggregatedFloor(collectionId: string): Promise; ``` ### `orders.offersSummary()` ```ts offersSummary(collectionId: string): Promise; ``` ### `orders.onchainStatus()` ```ts onchainStatus(assetId: string): Promise; ``` ## `client.activity` ### `activity.list()` ```ts list(query?: ActivityQuery): Promise>; ``` ### `activity.listAll()` ```ts listAll(query?: ActivityQuery): AsyncGenerator; ``` ## `client.search` ### `search.query()` ```ts query(query: SearchQuery): Promise; ``` ### `search.traits()` ```ts traits(query: TraitSearchQuery): Promise; ``` ## `client.analytics` ### `analytics.platform()` ```ts platform(query?: AnalyticsQuery): Promise; ``` ### `analytics.collection()` ```ts collection(id: string, query?: AnalyticsQuery): Promise>; ``` ### `analytics.compare()` ```ts compare(query: CompareCollectionsQuery): Promise; ``` ### `analytics.heatmap()` ```ts heatmap(query: LiquidityHeatmapQuery): Promise; ``` ### `analytics.flow()` ```ts flow(collectionId: string, query?: CollectionFlowQuery): Promise; ``` ## `client.recommendations` ### `recommendations.similar()` ```ts similar(itemId: string, query?: SimilarItemsQuery): Promise; ``` ## `client.platform` ### `platform.tokenPrices()` ```ts tokenPrices(query?: TokenPricesQuery): Promise; ``` ### `platform.price()` ```ts price(query: PriceQuery): Promise; ``` ### `platform.fees()` ```ts fees(): Promise; ``` ### `platform.fee()` ```ts fee(feeType: string): Promise; ``` ### `platform.chains()` ```ts chains(): Promise; ``` ### `platform.branding()` ```ts branding(): Promise; ``` ### `platform.analyticsConfig()` ```ts analyticsConfig(): Promise; ``` ### `platform.status()` ```ts status(): Promise; ``` ### `platform.tokenPrice()` Convenience: look up a single token's USD price by symbol. ```ts tokenPrice(symbol: string): Promise; ``` ## `client.affiliates` ### `affiliates.config()` ```ts config(): Promise; ``` ### `affiliates.leaderboard()` ```ts leaderboard(query?: AffiliateLeaderboardQuery): Promise; ``` ## `client.config` ### `config.client()` ```ts client(): Promise; ``` ## `client.smartMoney` ### `smartMoney.feed()` ```ts feed(query?: SmartMoneyFeedQuery): Promise; ``` ### `smartMoney.leaderboard()` ```ts leaderboard(query?: SmartMoneyLeaderboardQuery): Promise; ``` ### `smartMoney.inflows()` ```ts inflows(query?: SmartMoneyInflowsQuery): Promise; ``` ## `client.walletAnalytics` ### `walletAnalytics.pnl()` ```ts pnl(address: string, query?: WalletPnLQuery): Promise; ``` ### `walletAnalytics.pnlLots()` ```ts pnlLots(address: string, query?: WalletPnLLotsQuery): Promise; ``` ## `client.trust` ### `trust.collections()` ```ts collections(query?: TrustCollectionsQuery): Promise; ``` ### `trust.wallet()` ```ts wallet(address: string): Promise; ``` ## Functions ### `createHttp` ```ts export declare function createHttp(opts: HttpOptions): Http; ``` ### `isUuid` ```ts export declare function isUuid(s: string): boolean; ``` ### `looksLikeAddress` ```ts export declare function looksLikeAddress(s: string): boolean; ``` ### `paginate` ```ts export declare function paginate(fetchPage: (cursor: string | null) => Promise>): AsyncGenerator; ``` ### `sanitizeResponse` ```ts export declare function sanitizeResponse(input: T): T; ``` ### `validateAffiliateCode` Affiliate code — alphanumeric/_/-. ```ts export declare function validateAffiliateCode(code: unknown): string; ``` ### `validateChain` Chain slug like "solana-mainnet". ```ts export declare function validateChain(chain: unknown): string; ``` ### `validateCollectionIdentifier` Collection identifier: slug or on-chain contract address. ```ts export declare function validateCollectionIdentifier(id: unknown): string; ``` ### `validateFeeType` Fee-type slug like "marketplace_v1". ```ts export declare function validateFeeType(feeType: unknown): string; ``` ### `validateItemIdentifier` Item identifier: Solana mint, EVM contract:tokenId, or numeric token id. ```ts export declare function validateItemIdentifier(id: unknown): string; ``` ### `validateLimit` Clamp a numeric limit to [1, max]. ```ts export declare function validateLimit(limit: unknown, max: number, fallback: number): number; ``` ### `validateTokenSymbol` Token-symbol shape: 1-20 alphanumerics. ```ts export declare function validateTokenSymbol(symbol: unknown): string; ``` ### `validateWalletAddress` Wallet address (Solana / EVM / Sui). ```ts export declare function validateWalletAddress(addr: unknown): string; ``` ## Classes ### `GraveyardApiError` ```ts export declare class GraveyardApiError extends Error { readonly code: string; readonly status: number; readonly details?: unknown; constructor(code: string, message: string, status: number, details?: unknown); } ``` ### `GraveyardNetworkError` ```ts export declare class GraveyardNetworkError extends GraveyardApiError { constructor(message: string, cause?: unknown); } ``` ### `GraveyardRateLimitError` Thrown when the API responds with HTTP 429. Exposes `retryAfterMs` if the server set a `Retry-After` header. Falls back to `limit` / `remaining` from `X-RateLimit-*` headers when available. ```ts export declare class GraveyardRateLimitError extends GraveyardApiError { readonly retryAfterMs?: number; readonly limit?: number; readonly remaining?: number; constructor(message: string, opts?: { retryAfterMs?: number; limit?: number; remaining?: number; }); } ``` ### `GraveyardTimeoutError` ```ts export declare class GraveyardTimeoutError extends GraveyardApiError { readonly timeoutMs: number; constructor(timeoutMs: number); } ``` ### `GraveyardValidationError` ```ts export declare class GraveyardValidationError extends GraveyardApiError { constructor(message: string); } ``` ## Types ### `ActivityEvent` ```ts export interface ActivityEvent { chain: Chain; event_type: EventType; from_address: string | null; to_address: string | null; price: number | null; currency: string | null; tx_hash: string | null; event_time: string; marketplace?: string | null; market_collections?: { name: string | null; slug: string | null; image_url: string | null; custom_image_url: string | null; } | null; market_items?: { name: string | null; image_url: string | null; thumbnail_url: string | null; listing_price: number | null; listing_currency: string | null; } | null; } ``` ### `ActivityQuery` ```ts export interface ActivityQuery extends CursorPaginationQuery { chain?: Chain; type?: EventType | string; wallet?: string; mint?: string; } ``` ### `AffiliateConfigResponse` ```ts export interface AffiliateConfigResponse { is_enabled: boolean; commission_percent: number; commission_bps: number; show_leaderboard: boolean; leaderboard_size: number; } ``` ### `AffiliateLeaderboardEntry` ```ts export interface AffiliateLeaderboardEntry { affiliate_code: string; total_referred_volume: number; total_referred_sales: number; total_earned_usd: number; } ``` ### `AffiliateLeaderboardQuery` ```ts export interface AffiliateLeaderboardQuery { limit?: number; } ``` ### `AffiliateLeaderboardResponse` ```ts export interface AffiliateLeaderboardResponse { leaderboard: AffiliateLeaderboardEntry[]; } ``` ### `AggregatedFloorBest` ```ts export interface AggregatedFloorBest { price: number; currency: string; marketplace: string; token_address: string; seller: string; source: 'live_api' | 'database'; } ``` ### `AggregatedFloorResponse` ```ts export interface AggregatedFloorResponse { best: AggregatedFloorBest | null; external_tracking_enabled: boolean; } ``` ### `AggregatedListingsQuery` ```ts export interface AggregatedListingsQuery { limit?: number; offset?: number; sort?: 'price_asc' | 'price_desc' | 'newest'; marketplace?: string; } ``` ### `AggregatedListingsResponse` ```ts export interface AggregatedListingsResponse { listings: AggregatedListingsRow[]; total: number; marketplace_counts: Record; offset: number; limit: number; sort: 'price_asc' | 'price_desc' | 'newest' | string; } ``` ### `AggregatedListingsRow` ```ts export interface AggregatedListingsRow { chain: Chain; maker: string; token_address: string; token_id: string; price: number; currency: string; price_usd: number | null; expiration_at: string | null; protocol: string; source_marketplace: string; created_at: string; updated_at: string; market_items: { name: string | null; image_url: string | null; thumbnail_url: string | null; } | null; } ``` ### `AmbiguousItemCandidate` One of several items a `contract:token_id` names, from `GraveyardApiError.details.candidates` on a 409 `AMBIGUOUS_ITEM` — see {@link ItemChainHint}. Retry with `{ chain }`. (The API also sends each item's internal id; the SDK strips internal UUIDs, as everywhere.) ```ts export interface AmbiguousItemCandidate { chain: string; } ``` ### `AnalyticsConfigResponse` ```ts export interface AnalyticsConfigResponse { analytics_enabled: boolean; } ``` ### `AnalyticsQuery` ```ts export interface AnalyticsQuery { period?: '24h' | '7d' | '30d' | '90d' | '1y' | 'all'; /** Reported (raw) vs Adjusted (wash-filtered) volume mode. Default: 'adjusted'. */ volume?: 'reported' | 'adjusted'; } ``` ### `ApiEnvelope` ```ts export type ApiEnvelope = ApiResponse | ApiErrorBody; ``` ### `ApiErrorBody` ```ts export interface ApiErrorBody { success: false; error: { code: string; message: string; details?: unknown; }; } ``` ### `ApiResponse` ```ts export interface ApiResponse { success: true; data: T; } ``` ### `BestPriceListing` ```ts export interface BestPriceListing { price: number; currency: string; source_marketplace: string; maker: string; protocol: string; protocol_data: unknown | null; expiration_at: string | null; } ``` ### `BestPriceResponse` ```ts export interface BestPriceResponse { best: BestPriceListing | null; all_listings: BestPriceListing[]; count: number; token_address?: string; chain?: Chain; } ``` ### `BrandingResponse` ```ts export interface BrandingResponse { branding: Record; } ``` ### `Chain` ```ts export type Chain = string; ``` ### `ChainInfo` ```ts export interface ChainInfo { id: string; name: string; shortName: string; family: string; chainId: number | string; nativeCurrency: string; nativeCurrencyDecimals: number; coingeckoId: string; explorerUrl: string; explorerTxUrl: string; explorerAddressUrl: string; logo: string | null; color: string | null; } ``` ### `ChainsResponse` ```ts export interface ChainsResponse { chains: ChainInfo[]; } ``` ### `ClientConfigResponse` ```ts export interface ClientConfigResponse { ios_external_marketplace_enabled: boolean; ios_external_marketplace_min_app_version: string | null; ios_external_marketplace_flows: string[] | null; } ``` ### `CollectionActivityQuery` ```ts export interface CollectionActivityQuery extends CursorPaginationQuery { type?: string; wallet?: string; mint?: string; } ``` ### `CollectionAnalyticsDaily` ```ts export interface CollectionAnalyticsDaily { date: string; sales: number; volume: number; avg_price: number | null; floor: number | null; listed_count: number | null; holder_count: number | null; new_listings: number | null; unique_sellers: number | null; unique_buyers: number | null; [key: string]: unknown; } ``` ### `CollectionAnalyticsResponse` ```ts export interface CollectionAnalyticsResponse { stats: CollectionAnalyticsStats | null; daily: CollectionAnalyticsDaily[]; holder_history: HolderHistoryRow[]; wash_trade_count_7d: number; period: string; period_stats: { avg_price: number | null; unique_buyers: number; unique_sellers: number; }; deltas: { floor: number | null; volume: number | null; sales: number | null; listed: number | null; holders: number | null; top_bid: number | null; market_cap: number | null; } | null; } ``` ### `CollectionAnalyticsStats` ```ts export interface CollectionAnalyticsStats { floor_price: number | null; floor_currency: string | null; volume_24h: number | null; volume_7d: number | null; volume_30d: number | null; sales_24h: number | null; sales_7d: number | null; sales_30d: number | null; top_bid_24h: number | null; top_bid_7d: number | null; top_bid_30d: number | null; owner_count: number | null; listed_count: number | null; market_cap: number | null; updated_at: string; created_at: string; [key: string]: unknown; } ``` ### `CollectionCrossChainResponse` ```ts export interface CollectionCrossChainResponse { mappings: CrossChainMapping[]; collections: CrossChainCollection[]; } ``` ### `CollectionDetail` ```ts export interface CollectionDetail extends CollectionSummary { description: string | null; banner_url: string | null; royalty_bps: number | null; royalty_recipients: Array<{ address: string; share: number; }> | null; categories: string[] | null; created_at: string; market_collection_stats: MarketCollectionStatsRow | null; } ``` ### `CollectionFlowParty` ```ts export interface CollectionFlowParty { address: string; volume_usd: number; } ``` ### `CollectionFlowQuery` ```ts export interface CollectionFlowQuery { period?: '7d' | '30d'; } ``` ### `CollectionFlowResponse` ```ts export interface CollectionFlowResponse { collection_id: string; period: string; net_flow_usd: number; total_buy_volume_usd: number; total_sell_volume_usd: number; buyer_count: number; seller_count: number; new_buyer_count: number; returning_buyer_count: number; hold_time_histogram: Record; top_buyers: CollectionFlowParty[]; top_sellers: CollectionFlowParty[]; } ``` ### `CollectionHolder` Top holders for a collection — wallet addresses only, no profile join. ```ts export interface CollectionHolder { address: string; count: number; } ``` ### `CollectionHoldersResponse` ```ts export interface CollectionHoldersResponse { holders: CollectionHolder[]; unique_holders: number; cursor: string | null; hasMore: boolean; } ``` ### `CollectionItemsQuery` ```ts export interface CollectionItemsQuery extends CursorPaginationQuery { sort?: 'price_asc' | 'price_desc' | 'rarity_asc' | 'rarity_desc' | 'token_id_asc' | 'token_id_desc' | 'recently_listed'; listed?: boolean; min_price?: number; max_price?: number; marketplace?: string; owner?: string; traits?: string; rarity_tier?: string; with_offers?: boolean; search?: string; } ``` ### `CollectionItemsResponse` ```ts export interface CollectionItemsResponse extends CursorPaginatedResponse { marketplace_counts: Record; total?: number; } ``` ### `CollectionLaunch` ```ts export interface CollectionLaunch { name: string; slug: string; chain: Chain; contract_address: string | null; image_url: string | null; custom_image_url: string | null; banner_url: string | null; is_verified: boolean; total_supply: number | null; description: string | null; created_at: string; source: string | null; floor_price: number | null; floor_currency: string | null; volume_24h: number | null; volume_7d: number | null; volume_30d: number | null; listed_count: number | null; owner_count: number | null; sales_24h: number | null; sales_7d: number | null; sales_30d: number | null; is_gravemint: boolean; } ``` ### `CollectionLaunchesResponse` ```ts export interface CollectionLaunchesResponse { data: CollectionLaunch[]; total: number; limit: number; offset: number; hasMore: boolean; } ``` ### `CollectionMeta` ```ts export interface CollectionMeta { chains: Array<{ chain: Chain; count: number; }>; categories: string[]; } ``` ### `CollectionOfferRow` ```ts export interface CollectionOfferRow { price: number; currency: string; floor_diff_pct: number | null; fillable_offers: number; total_size: number; bidders: number; marketplace: string; } ``` ### `CollectionOffersResponse` GET /collections/:id/offers returns `{ data }` only. ```ts export interface CollectionOffersResponse { data: MarketOrder[]; } ``` ### `CollectionsListResponse` ```ts export interface CollectionsListResponse extends CursorPaginatedResponse { timeframe?: string; } ``` ### `CollectionSparklines` ```ts export type CollectionSparklines = Record; ``` ### `CollectionStatsDailyRow` ```ts export interface CollectionStatsDailyRow { date: string; sales: number; volume: number; avg_price: number | null; floor: number | null; listed_count: number | null; holder_count: number | null; new_listings: number | null; unique_sellers: number | null; unique_buyers: number | null; [extra: string]: unknown; } ``` ### `CollectionStatsQuery` ```ts export interface CollectionStatsQuery { period?: '24h' | '7d' | '30d' | '90d' | '1y' | 'all'; } ``` ### `CollectionStatsResponse` ```ts export interface CollectionStatsResponse { stats: MarketCollectionStatsRow | null; daily: CollectionStatsDailyRow[]; wash_trade_count_7d: number; } ``` ### `CollectionSummary` Collection row. Reference a collection by `slug` or `contract_address`. ```ts export interface CollectionSummary { name: string; image_url: string | null; chain: Chain; contract_address: string; slug?: string; is_verified: boolean; floor_price: number | null; total_volume: number | null; total_listed: number | null; total_supply: number | null; [extra: string]: unknown; } ``` ### `CollectionTrait` ```ts export interface CollectionTrait { trait_type: string; count: number; values: CollectionTraitValue[]; } ``` ### `CollectionTraitFloor` ```ts export interface CollectionTraitFloor { trait_type: string; trait_value: string; floor_price: number; currency: string; listed_count: number; } ``` ### `CollectionTraitFloorsResponse` ```ts export interface CollectionTraitFloorsResponse { trait_floors: CollectionTraitFloor[]; } ``` ### `CollectionTraitPricingSummary` ```ts export interface CollectionTraitPricingSummary { generated_at: string; per_trait: TraitPricingRow[]; marketplace_has_data: boolean; } ``` ### `CollectionTraitsResponse` ```ts export interface CollectionTraitsResponse { traits: CollectionTrait[]; total_items: number; } ``` ### `CollectionTraitValue` ```ts export interface CollectionTraitValue { value: string; count: number; percentage: number; } ``` ### `CompareCollectionEntry` ```ts export interface CompareCollectionEntry { id: string; meta: { id: string; name: string; slug: string; chain: Chain; image_url: string | null; is_verified: boolean; contract_address: string | null; } | null; stats: Record | null; daily: CompareDailyRow[]; holders: CompareHolderRow[]; } ``` ### `CompareCollectionsQuery` ```ts export interface CompareCollectionsQuery { collection_ids: string; period?: '24h' | '7d' | '30d' | '90d'; } ``` ### `CompareCollectionsResponse` ```ts export interface CompareCollectionsResponse { collections: CompareCollectionEntry[]; period: string; } ``` ### `CompareDailyRow` ```ts export interface CompareDailyRow { collection_id: string; date: string; volume: number; volume_usd: number | null; sales: number; avg_price: number | null; floor_close: number | null; } ``` ### `CompareHolderRow` ```ts export interface CompareHolderRow { collection_id: string; date: string; unique_holders: number | null; top_10_pct_concentration: number | null; } ``` ### `CreatorPageByCollectionResponse` ```ts export interface CreatorPageByCollectionResponse { /** Null when the collection is not on any published creator page. */ page: CreatorPageRef | null; } ``` ### `CreatorPageCollection` ```ts export interface CreatorPageCollection { id: string; slug: string | null; name: string; chain: Chain; contract_address: string | null; image_url: string | null; custom_image_url: string | null; banner_url: string | null; is_verified: boolean; total_supply: number | null; description: string | null; /** Display order on the creator page (0-based). */ position: number; added_by: 'admin' | 'owner'; market_collection_stats: CreatorPageCollectionStats | CreatorPageCollectionStats[] | null; } ``` ### `CreatorPageCollectionStats` ```ts export interface CreatorPageCollectionStats { floor_price: number | null; floor_currency: string | null; volume_24h: number | null; total_volume_all_time: number | null; listed_count: number | null; owner_count: number | null; sales_24h: number | null; total_items: number | null; } ``` ### `CreatorPageDetail` ```ts export interface CreatorPageDetail { id: string; slug: string; name: string; bio: string | null; logo_url: string | null; banner_url: string | null; website_url: string | null; twitter_url: string | null; discord_url: string | null; is_published: boolean; created_at: string; updated_at: string; } ``` ### `CreatorPageRef` ```ts export interface CreatorPageRef { slug: string; name: string; logo_url: string | null; } ``` ### `CreatorPageResponse` ```ts export interface CreatorPageResponse { page: CreatorPageDetail; collections: CreatorPageCollection[]; } ``` ### `CreatorPagesQuery` ```ts export interface CreatorPagesQuery { /** Page size — default 24, max 100. */ limit?: number; offset?: number; } ``` ### `CreatorPagesResponse` ```ts export interface CreatorPagesResponse { items: CreatorPageSummary[]; /** Offset for the next page, or null when this is the last page. */ nextOffset: number | null; } ``` ### `CreatorPageSummary` ```ts export interface CreatorPageSummary { id: string; slug: string; name: string; bio: string | null; logo_url: string | null; banner_url: string | null; created_at: string; collection_count: number; } ``` ### `CrossChainCollection` ```ts export interface CrossChainCollection { name: string; slug: string; chain: Chain; contract_address: string | null; image_url: string | null; is_verified: boolean; total_supply: number | null; floor_price: number | null; floor_currency: string | null; total_volume: number | null; mapping: CrossChainMapping; } ``` ### `CrossChainMapping` ```ts export interface CrossChainMapping { mapping_type: string | null; confidence: number | null; verified: boolean; } ``` ### `CursorPaginatedResponse` Cursor-paginated envelope used by activity feeds, listings, etc. ```ts export interface CursorPaginatedResponse { data: T[]; cursor: string | null; hasMore: boolean; total?: number; } ``` ### `CursorPaginationQuery` ```ts export interface CursorPaginationQuery { limit?: number; cursor?: string | null; } ``` ### `EventType` ```ts export type EventType = 'sale' | 'list' | 'listing' | 'delist' | 'offer' | 'transfer' | 'mint' | 'burn'; ``` ### `Fee` ```ts export interface Fee { fee_type: string; fee_bps: number; description: string; } ``` ### `FeesResponse` ```ts export interface FeesResponse { fees: Fee[]; } ``` ### `GraveyardClientOptions` ```ts export interface GraveyardClientOptions extends HttpOptions { } ``` ### `HeatmapCell` ```ts export interface HeatmapCell { dow: number; hour: number; value: number; } ``` ### `HolderHistoryRow` ```ts export interface HolderHistoryRow { date: string; unique_holders: number | null; top_10_pct_concentration: number | null; holder_distribution: unknown | null; } ``` ### `HoldersQuery` ```ts export interface HoldersQuery extends CursorPaginationQuery { } ``` ### `Http` ```ts export type Http = (path: string, init?: RequestInit) => Promise; ``` ### `HttpOptions` ```ts export interface HttpOptions { /** Defaults to `https://api.deads.io` (`https://api.solanadeads.com` serves the same API). */ baseUrl?: string; /** * API key for higher rate limits and per-key usage tracking. If omitted, * requests fall through to the anonymous (per-IP) rate limit tier. */ apiKey?: string; timeoutMs?: number; fetch?: typeof fetch; headers?: Record; /** @internal Trusted server-side use only. */ disableSanitize?: boolean; } ``` ### `ItemActivityQuery` ```ts export interface ItemActivityQuery extends ItemChainHint { limit?: number; } ``` ### `ItemActivityResponse` ```ts export interface ItemActivityResponse> { data: T[]; hasMore: boolean; } ``` ### `ItemChainHint` Which chain an item identifier refers to. A CREATE2 contract can sit at the same address on several chains, so `contract:token_id` may name more than one NFT; without a hint the API then answers 409 `AMBIGUOUS_ITEM` with `details.candidates: [{ chain }]` rather than guessing. Retry with the chain you mean (e.g. `'robinhood-mainnet'`) — choose it deliberately; taking the first candidate would just reintroduce the guess. ```ts export interface ItemChainHint { chain?: string; } ``` ### `ItemListingsQuery` ```ts export interface ItemListingsQuery extends CursorPaginationQuery, ItemChainHint { } ``` ### `ItemNeighbor` ```ts export interface ItemNeighbor { name: string | null; image_url: string | null; thumbnail_url: string | null; media_type: MediaType | string | null; rarity_rank: number | null; rarity_tier: string | null; token_id: string; token_address: string; chain: Chain; listing_price: number | null; listing_currency: string | null; } ``` ### `ItemNeighborsQuery` ```ts export interface ItemNeighborsQuery extends ItemChainHint { limit?: number; sort?: 'rank' | 'token_id' | 'price_asc' | 'price_desc'; listed?: boolean; } ``` ### `ItemNeighborsResponse` ```ts export interface ItemNeighborsResponse { current_index: number | null; total: number; sort: string; listed: boolean; before: ItemNeighbor[]; current: { rarity_rank: number | null; token_id: string; listing_price: number | null; }; after: ItemNeighbor[]; } ``` ### `ItemOffersQuery` ```ts export interface ItemOffersQuery extends CursorPaginationQuery, ItemChainHint { } ``` ### `ItemOrderListResponse` ```ts export interface ItemOrderListResponse { data: T[]; } ``` ### `ItemPriceHistoryQuery` ```ts export interface ItemPriceHistoryQuery extends ItemChainHint { period?: '24h' | '7d' | '30d' | '90d' | '1y' | 'all'; } ``` ### `ItemRarity` ```ts export interface ItemRarity { rank: number | null; score: number | null; tier: string | null; total_supply: number; } ``` ### `ItemTrait` ```ts export interface ItemTrait { trait_type: string; value: string; percentage: number | null; floor_price: number | null; floor_currency: string | null; total_count: number; listed_count: number; } ``` ### `ItemTraitsResponse` ```ts export interface ItemTraitsResponse { traits: ItemTrait[]; rarity_rank: number | null; rarity_score: number | null; rarity_tier: string | null; total_supply: number; } ``` ### `LaunchesQuery` ```ts export interface LaunchesQuery { period?: '24h' | '7d' | '30d'; chain?: Chain; limit?: number; offset?: number; } ``` ### `LiquidityHeatmapQuery` ```ts export interface LiquidityHeatmapQuery { chain: Chain; metric?: 'volume' | 'sales'; days?: 30 | 90; } ``` ### `LiquidityHeatmapResponse` ```ts export interface LiquidityHeatmapResponse { /** Active metric (volume | sales) as a 7×24 grid — drives the color gradient. */ matrix: number[][]; /** All three metrics at once so click-detail panels can render every stat * for a slot without a second round-trip. */ matrices: { volume: number[][]; sales: number[][]; avg_price: number[][]; }; chain: Chain; metric: 'volume' | 'sales'; days: 30 | 90; best: HeatmapCell; worst: HeatmapCell; } ``` ### `ListCollectionsQuery` ```ts export interface ListCollectionsQuery extends CursorPaginationQuery { sort?: 'volume_24h' | 'volume_7d' | 'volume_30d' | 'floor_price' | 'created_at' | 'name'; chain?: Chain; verified?: boolean; category?: string; timeframe?: '24h' | '7d' | '30d' | 'all'; search?: string; } ``` ### `MarketCollectionStatsRow` ```ts export interface MarketCollectionStatsRow { floor_price: number | null; floor_currency: string | null; volume_24h: number | null; volume_7d: number | null; volume_30d: number | null; sales_24h: number | null; sales_7d: number | null; sales_30d: number | null; top_bid_24h: number | null; top_bid_7d: number | null; top_bid_30d: number | null; owner_count: number | null; listed_count: number | null; market_cap: number | null; updated_at: string; created_at: string; [extra: string]: unknown; } ``` ### `MarketItem` Market item (NFT) shape. Reference items by `token_address` (Solana mint) or `${contract_address}:${token_id}` (EVM). ```ts export interface MarketItem { token_address: string; token_id: string | null; chain: Chain; name: string | null; image_url: string | null; animation_url: string | null; media_type: MediaType | string | null; thumbnail_url: string | null; /** * BENEFICIAL owner. **Nullable**: null means no beneficial owner is * known — typically the asset is held by a marketplace escrow, a stake pool or * a draw escrow. The raw on-chain holder is exposed separately as `raw_owner`. */ owner: string | null; /** The raw on-chain holder — an escrow, pool or draw account when `owner` is null. */ raw_owner?: string | null; listing_price: number | null; listing_currency: string | null; listing_marketplace: string | null; rarity_rank: number | null; rarity_score: number | null; rarity_tier: string | null; is_burned: boolean; /** Extra row fields (attributes, last_sale_price, etc.) may be present. */ [extra: string]: unknown; } ``` ### `MarketOrder` ```ts export interface MarketOrder { chain: Chain; order_type: OrderType; status: OrderStatus; maker: string; taker: string | null; token_address: string; token_id: string | null; price: number; currency: string; currency_contract: string | null; price_usd: number | null; expiration_at: string | null; protocol: string | null; source_marketplace: string; created_at: string; updated_at: string; } ``` ### `MediaType` ```ts export type MediaType = 'image' | 'gif' | 'video' | 'audio' | '3d_model' | 'html'; ``` ### `OffersSummaryResponse` ```ts export interface OffersSummaryResponse { floor_price: number | null; top_offer: CollectionOfferRow | null; collection_offers: CollectionOfferRow[]; trait_offers: TraitOfferRow[]; } ``` ### `OffsetPaginatedResponse` Offset-paginated envelope used by follows, comments, bundles. ```ts export interface OffsetPaginatedResponse { data: T[]; total?: number; limit: number; offset: number; } ``` ### `OffsetPaginationQuery` ```ts export interface OffsetPaginationQuery { limit?: number; offset?: number; } ``` ### `OnchainListingStatus` ```ts export interface OnchainListingStatus { status: string; statusCode: number; seller: string; price: number; priceLamports: string; currency: string; collectionKey: string; assetStandard: string; platformFeeBps: number; royaltyBps: number; createdAt: number; expiresAt: number; filledAt: number; } ``` ### `OnchainStatusResponse` ```ts export interface OnchainStatusResponse { assetId: string; onchain: boolean; listing: OnchainListingStatus | null; } ``` ### `OrderStatus` ```ts export type OrderStatus = 'active' | 'filled' | 'cancelled' | 'expired'; ``` ### `OrderType` ```ts export type OrderType = 'listing' | 'offer' | 'counter_offer' | 'collection_offer' | 'trait_offer' | 'item_offer'; ``` ### `PaginatedResponse` ```ts export type PaginatedResponse = CursorPaginatedResponse; ``` ### `PaginationQuery` ```ts export type PaginationQuery = CursorPaginationQuery; ``` ### `PlatformAnalyticsOverview` ```ts export interface PlatformAnalyticsOverview { total_collections: number; total_items: number; active_orders: number; total_users: number; period_volume: number; period_sales: number; } ``` ### `PlatformAnalyticsResponse` ```ts export interface PlatformAnalyticsResponse { overview: PlatformAnalyticsOverview; top_collections: TopCollectionRow[]; daily: PlatformDailyRow[]; period: string; } ``` ### `PlatformDailyRow` ```ts export interface PlatformDailyRow { date: string; volume: number; sales: number; listings: number; active_wallets: number; } ``` ### `PlatformStatusResponse` ```ts export interface PlatformStatusResponse { maintenance: boolean; maintenanceMessage: string; allowReads: boolean; minAppVersionIos: string | null; minAppVersionAndroid: string | null; updateMessage: string | null; } ``` ### `PriceHistoryPoint` ```ts export interface PriceHistoryPoint { t: string; price: number; currency: string; price_usd: number | null; } ``` ### `PriceHistoryResponse` ```ts export interface PriceHistoryResponse { data: PriceHistoryPoint[]; } ``` ### `PriceQuery` ```ts export interface PriceQuery { symbol: string; currency?: string; } ``` ### `PricesResponse` GET /platform/prices returns `{ prices: { [coingeckoId]: priceUsd|null } }`. ```ts export interface PricesResponse { prices: Record; } ``` ### `RequestInit` ```ts export interface RequestInit { query?: object; signal?: AbortSignal; } ``` ### `SearchCollectionHit` ```ts export interface SearchCollectionHit { name: string; slug: string; image_url: string | null; custom_image_url: string | null; chain: Chain; is_verified: boolean; contract_address: string; description: string | null; } ``` ### `SearchItemHit` ```ts export interface SearchItemHit { name: string | null; image_url: string | null; animation_url: string | null; media_type: string | null; thumbnail_url: string | null; chain: Chain; token_address: string; listing_price: number | null; listing_currency: string | null; rarity_rank: number | null; royalty_bps?: number; } ``` ### `SearchQuery` ```ts export interface SearchQuery { q: string; limit?: number; chain?: Chain; type?: 'collection' | 'item' | 'trait'; } ``` ### `SearchResponse` SDK-facing search response. Profiles and wallet-arrays are removed from the public API surface — only collection/item/trait results are returned. ```ts export interface SearchResponse { collections: SearchCollectionHit[]; items: SearchItemHit[]; traits: SearchTraitHit[]; } ``` ### `SearchTraitHit` ```ts export interface SearchTraitHit { chain: Chain; trait_type: string; trait_value: string; } ``` ### `SimilarItem` ```ts export interface SimilarItem { name: string; image_url: string | null; animation_url: string | null; media_type: string | null; thumbnail_url: string | null; token_address: string; token_id: string; listing_price: number | null; listing_currency: string | null; last_sale_price: number | null; last_sale_currency: string | null; rarity_rank: number | null; rarity_tier: string | null; chain: Chain; /** * The BENEFICIAL owner (, the #532 rule `MarketItem.owner` follows): `null` * when no beneficial owner is known — the item is held by a marketplace escrow, a stake pool * or a draw escrow. The raw on-chain holder is exposed separately as `raw_owner`. */ owner: string | null; /** The raw on-chain holder — may be an escrow or stake-pool account. */ raw_owner?: string | null; is_burned: boolean; market_collections: { name: string; image_url: string | null; chain: Chain; royalty_bps: number; }; } ``` ### `SimilarItemsQuery` ```ts export interface SimilarItemsQuery { /** How many similar items to return: default 12, clamped to 1..24 by the server. */ limit?: number; /** Which chain the item identifier refers to — see `ItemChainHint`. */ chain?: string; } ``` ### `SimilarItemsResponse` ```ts export type SimilarItemsResponse = SimilarItem[]; ``` ### `SmartMoneyFeedQuery` ```ts export interface SmartMoneyFeedQuery { chain?: Chain; cursor?: string; limit?: number; } ``` ### `SmartMoneyFeedResponse` ```ts export interface SmartMoneyFeedResponse { feed: SmartMoneyFeedRow[]; next_cursor: string | null; } ``` ### `SmartMoneyFeedRow` ```ts export interface SmartMoneyFeedRow { id: string; chain: Chain; collection_id: string | null; item_id: string | null; from_address: string; to_address: string; price: number | null; price_usd: number | null; currency: string | null; marketplace: string | null; event_time: string; tx_hash: string | null; side: 'buy' | 'sell'; collection: { id: string; name: string; slug: string; image_url: string | null; } | null; item: { id: string; name: string; image_url: string | null; } | null; } ``` ### `SmartMoneyInflowRow` ```ts export interface SmartMoneyInflowRow { collection_id: string; inflow_usd: number; buys: number; sells: number; last_event_at: string; collection: { id: string; name: string; slug: string; image_url: string | null; chain: Chain; } | null; } ``` ### `SmartMoneyInflowsQuery` ```ts export interface SmartMoneyInflowsQuery { period?: '24h' | '7d'; chain?: Chain | '__global__'; limit?: number; } ``` ### `SmartMoneyInflowsResponse` ```ts export interface SmartMoneyInflowsResponse { inflows: SmartMoneyInflowRow[]; period: string; chain: string; } ``` ### `SmartMoneyLeaderboardQuery` ```ts export interface SmartMoneyLeaderboardQuery { metric?: SmartMoneyMetric; period?: '24h' | '7d' | '30d'; chain?: Chain; limit?: number; } ``` ### `SmartMoneyLeaderboardResponse` ```ts export interface SmartMoneyLeaderboardResponse { rankings: SmartMoneyLeaderboardRow[]; metric: SmartMoneyMetric; period: string; } ``` ### `SmartMoneyLeaderboardRow` ```ts export interface SmartMoneyLeaderboardRow { address: string; chain: Chain; volume_usd?: number; realized_pnl_usd?: number; trades?: number; } ``` ### `SmartMoneyMetric` ```ts export type SmartMoneyMetric = 'volume' | 'realized_pnl' | 'trades'; ``` ### `SparklinesQuery` ```ts export interface SparklinesQuery { ids?: string[]; contract_addresses?: string[]; slugs?: string[]; hours?: number; days?: number; } ``` ### `TokenPricesQuery` ```ts export interface TokenPricesQuery { symbols?: string[]; } ``` ### `TokenPricesResponse` GET /platform/token-prices returns `{ [symbol]: priceUsd }` (e.g. `{ SOL: 84.52 }`). ```ts export type TokenPricesResponse = Record; ``` ### `TopCollectionRow` ```ts export interface TopCollectionRow { floor_price: number | null; floor_currency: string | null; volume_24h: number | null; volume_7d: number | null; volume_30d: number | null; sales_24h: number | null; sales_7d: number | null; sales_30d: number | null; owner_count: number | null; listed_count: number | null; name: string; slug: string; image_url: string | null; chain: Chain; is_verified: boolean; contract_address: string | null; } ``` ### `TraitOfferRow` ```ts export interface TraitOfferRow { trait_type: string; trait_value: string; price: number; currency: string; fillable_offers: number; total_size: number; bidders: number; marketplace: string; } ``` ### `TraitPricingRow` ```ts export interface TraitPricingRow { trait_type: string; trait_value: string; floor_price: number | null; currency: string | null; top_trait_offer: number | null; offer_currency: string | null; listed_count: number; sales_7d: number; } ``` ### `TraitSearchGroup` ```ts export interface TraitSearchGroup { chain: Chain; items: SearchTraitHit[]; count: number; collection_name?: string; collection_image?: string; is_verified?: boolean; } ``` ### `TraitSearchQuery` ```ts export interface TraitSearchQuery { q: string; limit?: number; chain?: Chain; } ``` ### `TraitSearchResponse` ```ts export interface TraitSearchResponse { results: TraitSearchGroup[]; total_matches: number; } ``` ### `TrustCollectionRow` ```ts export interface TrustCollectionRow { id: string; name: string; slug: string; chain: Chain; image_url: string | null; is_verified: boolean; contract_address: string | null; wash_pct: number; wash_volume_usd: number; total_volume_usd: number; clean_volume_usd: number; flagged_trade_count: number; } ``` ### `TrustCollectionsQuery` ```ts export interface TrustCollectionsQuery { sort?: TrustSort; period?: '24h' | '7d' | '30d'; chain?: Chain; limit?: number; } ``` ### `TrustCollectionsResponse` ```ts export interface TrustCollectionsResponse { collections: TrustCollectionRow[]; period: string; sort: TrustSort; } ``` ### `TrustSort` ```ts export type TrustSort = 'cleanest' | 'most_suspicious'; ``` ### `TrustWalletResponse` ```ts export interface TrustWalletResponse { address: string; wash_pct_7d: number | null; wash_pct_30d: number | null; wash_pct_all: number | null; total_trades_30d: number; total_trades_all: number; in_cluster: boolean; /** Verified-treasury memberships — present when the wallet is on the * admin-approved allowlist. UI uses this to render the green badge and to * link to the scoped collection page when length === 1. */ verified_treasury: TrustWalletTreasuryEntry[]; /** Auto-classified distributor flag — true when this wallet's recent * activity is dominated by buys + outgoing transfers (treasury-like * pattern) but no admin approval exists. UI renders a quieter cyan chip. */ is_distributor: boolean; } ``` ### `TrustWalletTreasuryEntry` Verified-treasury entry surfaced on a wallet. Empty array when the wallet is not on the allowlist. `collection_id` null = global treasury (every collection); non-null = scoped to that specific collection. ```ts export interface TrustWalletTreasuryEntry { label: string | null; collection_id: string | null; collection_name: string | null; collection_slug: string | null; } ``` ### `WalletLotRow` ```ts export interface WalletLotRow { id: string; item_id: string; collection_id: string | null; chain: Chain; acquired_at: string; cost_basis_usd: number | null; disposed_at: string | null; disposed_price_usd: number | null; realized_pnl_usd: number | null; holding_period_seconds: number | null; } ``` ### `WalletLotSummary` ```ts export interface WalletLotSummary { item_id: string; collection_id: string | null; realized_pnl_usd: number | null; disposed_at: string; holding_period_seconds: number | null; } ``` ### `WalletPnLDailyRow` ```ts export interface WalletPnLDailyRow { date: string; realized_pnl_usd: number; volume_usd: number; realized_trade_count: number; } ``` ### `WalletPnLLotsQuery` ```ts export interface WalletPnLLotsQuery { closed_only?: boolean; cursor?: string; limit?: number; } ``` ### `WalletPnLLotsResponse` ```ts export interface WalletPnLLotsResponse { lots: WalletLotRow[]; next_cursor: string | null; } ``` ### `WalletPnLQuery` ```ts export interface WalletPnLQuery { period?: '7d' | '30d' | '90d' | 'ytd' | 'all'; } ``` ### `WalletPnLResponse` ```ts export interface WalletPnLResponse { address: string; period: string; realized_pnl_usd: number; unrealized_pnl_usd: number; volume_usd: number; total_trades: number; win_rate_pct: number; open_lots_count: number; open_lots_value_usd: number; daily: WalletPnLDailyRow[]; best_trades: WalletLotSummary[]; worst_trades: WalletLotSummary[]; } ``` --- Source: https://docs.deads.io/sdk/gravemarket-reference Markdown: https://docs.deads.io/sdk/gravemarket-reference.md