get_market_data
Retrieve market data for Bitcoin Stamps with trading activity indicators, floor price filters, and volume data to analyze market trends.
Instructions
Retrieve market data for stamps with trading activity indicators (v2.3 feature)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| stamp_id | No | Filter by specific stamp ID | |
| activity_level | No | Filter by trading activity level | |
| min_floor_price | No | Minimum floor price in BTC | |
| max_floor_price | No | Maximum floor price in BTC | |
| include_volume_data | No | Include volume data in response | |
| page | No | Page number | |
| page_size | No | Items per page |
Implementation Reference
- src/tools/stamps.ts:601-678 (handler)The execute method of GetMarketDataTool class implements the core tool logic: validates parameters, checks API feature availability, fetches market data via StampchainClient.getMarketData(), formats the response as text, and handles errors.public async execute(params: GetMarketDataParams, context?: ToolContext): Promise<ToolResponse> { try { context?.logger?.info('Executing get_market_data tool', { params }); // Validate parameters const validatedParams = this.validateParams(params); // Use API client from context if available, otherwise use instance client const client = context?.apiClient || this.apiClient; // Check if v2.3 features are available const features = client.getFeatureAvailability(); if (!features.marketData) { return textResponse( 'Market data is not available in the current API version. Please upgrade to v2.3 or later.' ); } // Get market data const marketData = await client.getMarketData(validatedParams); if (!marketData.data || marketData.data.length === 0) { return textResponse('No market data found for the specified criteria'); } // Format the response const lines = [`Market Data (${marketData.data.length} results):`]; lines.push('---'); marketData.data.forEach((data: StampMarketData, index: number) => { lines.push(`${index + 1}. Market Data Entry`); lines.push(` Floor Price: ${data.floorPriceBTC || 'N/A'} BTC`); if (data.floorPriceUSD) { lines.push(` Floor Price USD: $${data.floorPriceUSD.toFixed(2)}`); } // Note: marketCapUSD not available in v2.3 marketData object lines.push(` Activity Level: ${data.activityLevel}`); if (data.lastActivityTime) { lines.push(` Last Activity: ${new Date(data.lastActivityTime * 1000).toISOString()}`); } if (data.volume24hBTC) { lines.push(` 24h Volume: ${data.volume24hBTC} BTC`); } if (data.lastSaleTxHash) { lines.push(` Last Sale TX: ${data.lastSaleTxHash}`); } if (data.lastSaleBuyerAddress) { lines.push(` Last Buyer: ${data.lastSaleBuyerAddress}`); } lines.push(''); }); // Add metadata lines.push('Metadata:'); lines.push(`- Total Results: ${marketData.total}`); lines.push(`- Page: ${marketData.page}`); lines.push(`- Page Size: ${marketData.limit}`); lines.push(`- Last Block: ${marketData.last_block}`); return textResponse(lines.join('\n')); } catch (error) { context?.logger?.error('Error executing get_market_data tool', { error }); if (error instanceof ValidationError) { throw error; } if (error instanceof ToolExecutionError) { throw error; } // Pass through the original error message for API errors if (error instanceof Error) { throw new ToolExecutionError(error.message, this.name, error); } throw new ToolExecutionError('Failed to retrieve market data', this.name, error); }
- src/schemas/stamps.ts:244-254 (schema)Zod schema GetMarketDataParamsSchema defining input validation and TypeScript types for the get_market_data tool parameters.export const GetMarketDataParamsSchema = z.object({ stamp_id: z.number().int().positive().optional(), activity_level: z.enum(['HOT', 'WARM', 'COOL', 'DORMANT', 'COLD']).optional(), min_floor_price: z.number().positive().optional(), max_floor_price: z.number().positive().optional(), include_volume_data: z.boolean().optional().default(true), page: z.number().int().min(1).optional().default(1), page_size: z.number().int().min(1).max(100).optional().default(20), }); export type GetMarketDataParams = z.infer<typeof GetMarketDataParamsSchema>;
- src/tools/stamps.ts:816-823 (registration)Registration of GetMarketDataTool in the stampTools export object, making it available for tool aggregation and server registration.export const stampTools = { get_stamp: GetStampTool, search_stamps: SearchStampsTool, get_recent_stamps: GetRecentStampsTool, get_recent_sales: GetRecentSalesTool, get_market_data: GetMarketDataTool, get_stamp_market_data: GetStampMarketDataTool, };
- src/tools/index.ts:47-70 (registration)Central list of all available tool names including 'get_market_data' for MCP tool discovery.export function getAvailableToolNames(): string[] { return [ // Stamp tools 'get_stamp', 'search_stamps', 'get_recent_stamps', 'get_recent_sales', 'get_market_data', 'get_stamp_market_data', // Collection tools 'get_collection', 'search_collections', // Token tools 'get_token_info', 'search_tokens', // Analysis tools 'analyze_stamp_code', 'get_stamp_dependencies', 'analyze_stamp_patterns', ]; }
- src/api/stampchain-client.ts:431-440 (helper)StampchainClient.getMarketData method that performs the HTTP request to the Stampchain API endpoint for market data, used by the tool handler.async getMarketData(params: MarketDataQueryParams = {}): Promise<{ data: StampMarketData[]; last_block: number; page: number; limit: number; total: number; }> { const response = await this.client.get('/stamps/marketData', { params }); return response.data; }