relay_get_requests

Instructions

Implementation Reference

• src/tools/requests.ts:243-247 (handler)

  Handler function for the relay_get_requests tool. Parses args using getRequestsSchema (Zod) and calls client.getRequests(params) to fetch paginated cross-chain requests.

    handler: async (args: unknown) => {
      const params = getRequestsSchema.parse(args);
      return await client.getRequests(params);
    },
  },

• src/tools/requests.ts:25-42 (schema)

  Zod schema for relay_get_requests input validation. Defines all filter/pagination fields (limit, continuation, user, hash, chainIds, timestamps, blocks, referrer, sort options).

  const getRequestsSchema = z.object({
    limit: z.number().min(1).max(50).optional().describe('Limit the number of results (1-50, default: 20)'),
    continuation: z.string().optional().describe('Continuation token for pagination'),
    user: z.string().optional().describe('Filter by user address'),
    hash: z.string().optional().describe('Filter by transaction hash'),
    originChainId: z.number().optional().describe('Filter by origin chain ID'),
    destinationChainId: z.number().optional().describe('Filter by destination chain ID'),
    privateChainsToInclude: z.string().optional().describe('Private chains to include'),
    id: z.string().optional().describe('Filter by request ID'),
    startTimestamp: z.number().optional().describe('Start timestamp filter'),
    endTimestamp: z.number().optional().describe('End timestamp filter'),
    startBlock: z.number().optional().describe('Start block filter'),
    endBlock: z.number().optional().describe('End block filter'),
    chainId: z.string().optional().describe('Filter by chain ID (either direction)'),
    referrer: z.string().optional().describe('Filter by referrer'),
    sortBy: z.enum(['createdAt', 'updatedAt']).optional().describe('Sort field'),
    sortDirection: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
  });

• src/tools/requests.ts:158-247 (registration)

  Registration of the relay_get_requests tool within createRequestTools(). Defines name, description, inputSchema (JSON Schema format), and the handler function.

  relay_get_requests: {
    name: 'relay_get_requests',
    description: 'Get all cross-chain transactions with advanced filtering and pagination.\n\nUse Cases:\n• List all transactions for a specific user\n• Find transactions by hash, chain IDs, or time range\n• Monitor transaction history with pagination\n• Filter by request status and referrer\n\nPagination: Use limit (max 50) and continuation token for large result sets.\nSorting: Sort by createdAt or updatedAt in asc/desc order.',
    inputSchema: {
      type: 'object',
      properties: {
        limit: {
          type: 'number',
          minimum: 1,
          maximum: 50,
          description: 'Limit the number of results (1-50, default: 20)'
        },
        continuation: {
          type: 'string',
          description: 'Continuation token for pagination'
        },
        user: {
          type: 'string',
          description: 'Filter by user address'
        },
        hash: {
          type: 'string',
          description: 'Filter by transaction hash'
        },
        originChainId: {
          type: 'number',
          description: 'Filter by origin chain ID'
        },
        destinationChainId: {
          type: 'number',
          description: 'Filter by destination chain ID'
        },
        privateChainsToInclude: {
          type: 'string',
          description: 'Private chains to include'
        },
        id: {
          type: 'string',
          description: 'Filter by request ID'
        },
        startTimestamp: {
          type: 'number',
          description: 'Start timestamp filter (Unix timestamp)'
        },
        endTimestamp: {
          type: 'number',
          description: 'End timestamp filter (Unix timestamp)'
        },
        startBlock: {
          type: 'number',
          description: 'Start block filter'
        },
        endBlock: {
          type: 'number',
          description: 'End block filter'
        },
        chainId: {
          type: 'string',
          description: 'Filter by chain ID (either direction, overrides origin/destination filters)'
        },
        referrer: {
          type: 'string',
          description: 'Filter by referrer address'
        },
        sortBy: {
          type: 'string',
          enum: ['createdAt', 'updatedAt'],
          description: 'Sort field (default: createdAt)'
        },
        sortDirection: {
          type: 'string',
          enum: ['asc', 'desc'],
          description: 'Sort direction'
        }
      },
      additionalProperties: false
    },
    /**
     * Handler function for the relay_get_requests tool.
     * 
     * @param {unknown} args - Raw arguments from MCP client
     * @returns {Promise<GetRequestsResponse>} Paginated list of cross-chain requests
     * @throws {ZodError} When arguments don't match the expected schema
     * @throws {RelayAPIError} When filter parameters are invalid
     */
    handler: async (args: unknown) => {
      const params = getRequestsSchema.parse(args);
      return await client.getRequests(params);
    },
  },

• src/client/RelayClient.ts:278-283 (helper)

  Client method getRequests() - makes the actual HTTP GET request to /requests/v2 endpoint with filter/pagination params and returns the response data.

  async getRequests(request: GetRequestsRequest = {}): Promise<GetRequestsResponse> {
    const response = await this.client.get<GetRequestsResponse>('/requests/v2', {
      params: request
    });
    return response.data;
  }

• src/types/relay.ts:383-416 (schema)

  TypeScript interfaces GetRequestsRequest and GetRequestsResponse defining the request filter parameters and response structure for the API call.

  export interface GetRequestsRequest {
    /** Maximum number of requests to return */
    limit?: number;
    /** Pagination token for next page */
    continuation?: string;
    /** Filter by user address */
    user?: string;
    /** Filter by transaction hash */
    hash?: string;
    /** Filter by origin chain ID */
    originChainId?: number;
    /** Filter by destination chain ID */
    destinationChainId?: number;
    /** Include private chains in results */
    privateChainsToInclude?: string;
    /** Filter by request ID */
    id?: string;
    /** Filter by start timestamp */
    startTimestamp?: number;
    /** Filter by end timestamp */
    endTimestamp?: number;
    /** Filter by start block number */
    startBlock?: number;
    /** Filter by end block number */
    endBlock?: number;
    /** Filter by chain ID */
    chainId?: string;
    /** Filter by referrer address */
    referrer?: string;
    /** Sort field */
    sortBy?: 'createdAt' | 'updatedAt';
    /** Sort direction */
    sortDirection?: 'asc' | 'desc';
  }