search_stamps
Search Bitcoin stamps using filters like creator, collection, or stamp type to find specific digital assets on the blockchain.
Instructions
Search for Bitcoin stamps with various filtering criteria including creator, collection, and stamp type
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query string | |
| creator | No | Filter by creator address | |
| collection_id | No | Filter by collection ID | |
| cpid | No | Filter by CPID | |
| is_btc_stamp | No | Filter for BTC stamps only | |
| is_cursed | No | Filter for cursed stamps only | |
| sort_order | No | Sort order by stamp ID | DESC |
| page | No | Page number | |
| page_size | No | Items per page |
Implementation Reference
- src/tools/stamps.ts:195-271 (handler)The main handler function for the 'search_stamps' tool. It validates input parameters, constructs query params, calls the StampchainClient.searchStamps API, formats the results, and returns a multi-response with text summary and metadata.public async execute(params: SearchStampsParams, context?: ToolContext): Promise<ToolResponse> { try { context?.logger?.info('Executing search_stamps tool', { params }); // Validate parameters const validatedParams = this.validateParams(params); // Build query parameters const queryParams = { query: validatedParams.query, creator: validatedParams.creator, collection_id: validatedParams.collection_id, cpid: validatedParams.cpid, is_btc_stamp: validatedParams.is_btc_stamp, is_cursed: validatedParams.is_cursed, sort_order: validatedParams.sort_order, page: validatedParams.page, page_size: validatedParams.page_size, }; // Remove undefined values Object.keys(queryParams).forEach((key) => { if (queryParams[key as keyof typeof queryParams] === undefined) { delete queryParams[key as keyof typeof queryParams]; } }); // Use API client from context if available, otherwise use instance client const client = context?.apiClient || this.apiClient; // Search stamps const stamps: Stamp[] = await client.searchStamps(queryParams); if (!stamps || stamps.length === 0) { return textResponse('No stamps found matching the search criteria'); } // Since the API returns an array, we need to handle pagination info differently const total = stamps.length; const page = validatedParams.page || 1; const limit = validatedParams.page_size || 20; // Format the response const formattedList = formatStampList(stamps, total, page, limit); // Include metadata about the search const metadata = { total_results: total, current_page: page, page_size: limit, total_pages: Math.ceil(total / limit), query_params: queryParams, }; return multiResponse( { type: 'text', text: formattedList }, { type: 'text', text: `\nSearch Metadata:\n${JSON.stringify(metadata, null, 2)}` } ); } catch (error) { context?.logger?.error('Error executing search_stamps 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 search stamps', this.name, error); } }
- src/schemas/stamps.ts:199-218 (schema)Zod schema defining the input parameters and validation rules for the search_stamps tool.export const SearchStampsParamsSchema = z.object({ query: z.string().optional(), creator: z.string().optional(), collection_id: z.string().optional(), cpid: z.string().optional(), is_btc_stamp: z.boolean().optional(), is_cursed: z.boolean().optional(), sort_order: z.enum(['ASC', 'DESC']).optional().default('DESC'), page: z.number().int().min(1).optional().default(1), page_size: z.number().int().min(1).max(100).optional().default(20), limit: z.number().int().min(1).max(1000).optional(), // v2.3: New filtering parameters from_timestamp: z.number().int().positive().optional(), to_timestamp: z.number().int().positive().optional(), min_floor_price: z.number().positive().optional(), max_floor_price: z.number().positive().optional(), activity_level: z.enum(['HOT', 'WARM', 'COOL', 'DORMANT', 'COLD']).optional(), include_market_data: z.boolean().optional().default(false), include_dispenser_info: z.boolean().optional().default(false), });
- src/tools/stamps.ts:816-823 (registration)Registration of the SearchStampsTool class in the stampTools object, which aggregates all stamp-related tools for export.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 factory function that creates all tool instances, including search_stamps from createStampTools, for use in the MCP server.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/tools/stamps.ts:828-837 (helper)Factory function that instantiates the SearchStampsTool instance, which can then be registered in the ToolRegistry.export function createStampTools(apiClient?: StampchainClient) { return { get_stamp: new GetStampTool(apiClient), search_stamps: new SearchStampsTool(apiClient), get_recent_stamps: new GetRecentStampsTool(apiClient), get_recent_sales: new GetRecentSalesTool(apiClient), get_market_data: new GetMarketDataTool(apiClient), get_stamp_market_data: new GetStampMarketDataTool(apiClient), }; }