list_buyers
Retrieve a list of buyers from Finix payment processing. Filter results by email or limit the number of records returned for efficient buyer management.
Instructions
This tool will fetch a list of Buyers from Finix.
It takes two arguments:
limit (int, optional): The number of buyers to return.
email (str, optional): A case-sensitive filter on the list based on the buyer's email field.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| No |
Implementation Reference
- src/tools/identities/listBuyers.ts:30-63 (handler)The main handler function that executes the tool logic: fetches identities from Finix API using provided limit and email filters, filters for buyers (those with identity_roles including 'BUYER'), and returns an array of buyer IDs.
const listBuyers = async (client: FinixClient, _context: FinixContext, params: any): Promise<any> => { try { if (!client.hasCredentials()) { throw new Error('Finix username and password are required for this operation. Please configure FINIX_USERNAME and FINIX_PASSWORD in your environment.'); } const { limit, email } = params; // Build query parameters const queryParams = new URLSearchParams(); if (limit) queryParams.append('limit', limit.toString()); if (email) queryParams.append('email', email); const response = await client.get(`/identities?${queryParams.toString()}`); if (response.error) { throw new Error(`Error listing buyers: ${response.error.message}`); } const data = response.data; const identities = data._embedded?.identities || []; // Filter for buyers only and return just IDs like Stripe const buyers = identities .filter((identity: any) => identity.identity_roles?.includes('BUYER')) .map((buyer: any) => ({ id: buyer.id })); return buyers; } catch (error) { throw error; } }; - Zod input schema defining optional parameters: limit (integer 1-100) and email (string filter).
const listBuyersParameters = () => z.object({ limit: z.number().int().min(1).max(100).optional().describe( 'A limit on the number of objects to be returned. Limit can range between 1 and 100.' ), email: z.string().optional().describe( 'A case-sensitive filter on the list based on the buyer\'s email field. The value must be a string.' ) }); - src/tools/identities/listBuyers.ts:65-79 (registration)ToolFactory registration defining the 'list_buyers' tool, including method name, name, description, parameters, annotations, actions, and reference to the execute handler. Exported as default.
const tool: ToolFactory = () => ({ method: 'list_buyers', name: 'List Buyers', description: listBuyersPrompt(), parameters: listBuyersParameters(), annotations: listBuyersAnnotations(), actions: { identities: { read: true } }, execute: listBuyers }); export default tool; - src/tools/index.ts:15-27 (registration)Central registration of all tools in the allTools array, including the listBuyers tool.
export const allTools: ToolFactory[] = [ // Search & Documentation searchDocs, // Identities (Buyers/Sellers) createBuyer, createSeller, listBuyers, listSellers, // Payment Links createPaymentLink, ]; - Prompt/description generator for the list_buyers tool.
const listBuyersPrompt = () => ` This tool will fetch a list of Buyers from Finix. It takes two arguments: - limit (int, optional): The number of buyers to return. - email (str, optional): A case-sensitive filter on the list based on the buyer's email field. `; - Annotations for the list_buyers tool indicating it is read-only, idempotent, etc.
const listBuyersAnnotations = () => ({ destructiveHint: false, idempotentHint: true, openWorldHint: true, readOnlyHint: true, title: 'List buyers' });