get_market_data
Fetch Bitcoin Stamps market data, including trading activity levels, floor prices, and volume details, using filters like stamp ID and activity level.
Instructions
Retrieve market data for stamps with trading activity indicators (v2.3 feature)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| activity_level | No | Filter by trading activity level | |
| include_volume_data | No | Include volume data in response | |
| max_floor_price | No | Maximum floor price in BTC | |
| min_floor_price | No | Minimum floor price in BTC | |
| page | No | Page number | |
| page_size | No | Items per page | |
| stamp_id | No | Filter by specific stamp ID |
Implementation Reference
- src/tools/stamps.ts:601-679 (handler)The execute method of GetMarketDataTool class implements the core logic for the get_market_data tool. It validates parameters, checks API version compatibility, 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 defining input parameters for the get_market_data tool, including optional filters like stamp_id, activity_level, price ranges, pagination, and volume data inclusion.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 object export, making it available for tool registry.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:28-42 (registration)Central tool creation factory createAllTools includes stamp tools (via createStampTools) which instantiates get_market_data tool for the main tool registry.export function createAllTools(apiClient?: StampchainClient): Record<string, ITool> { const client = apiClient || new StampchainClient(); const stamps = createStampTools(client); const collections = createCollectionTools(client); const tokens = createTokenTools(client); const analysis = createStampAnalysisTools(client); return { ...stamps, ...collections, ...tokens, ...analysis, }; }
- src/api/stampchain-client.ts:431-440 (helper)StampchainClient.getMarketData method called by the tool handler to fetch raw market data from the Stampchain API.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; }