@0xsequence/marketplace-sdk 1.0.0 → 1.1.1

package/src/react/queries/orders/listItemsOrdersForCollection.ts

@@ -0,0 +1,90 @@
+import { infiniteQueryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { Page, SdkConfig } from '../../../types';
+import type {
+	ListOrdersWithCollectiblesArgs,
+	ListOrdersWithCollectiblesReturn,
+	QueryKeyArgs,
+	ValuesOptional,
+} from '../../_internal';
+import { collectionKeys, getMarketplaceClient } from '../../_internal';
+import type { StandardInfiniteQueryOptions } from '../../types/query';
+
+export interface FetchListItemsOrdersForCollectionParams
+	extends Omit<ListOrdersWithCollectiblesArgs, 'chainId' | 'contractAddress'> {
+	chainId: number;
+	collectionAddress: Address;
+	config: SdkConfig;
+}
+
+export async function fetchListItemsOrdersForCollection(
+	params: FetchListItemsOrdersForCollectionParams,
+	page: Page,
+): Promise<ListOrdersWithCollectiblesReturn> {
+	const { collectionAddress, chainId, config, ...additionalApiParams } = params;
+	const marketplaceClient = getMarketplaceClient(config);
+
+	const apiArgs: ListOrdersWithCollectiblesArgs = {
+		contractAddress: collectionAddress,
+		chainId: String(chainId),
+		page: page,
+		...additionalApiParams,
+	};
+
+	return await marketplaceClient.listOrdersWithCollectibles(apiArgs);
+}
+
+export type ListItemsOrdersForCollectionQueryOptions =
+	ValuesOptional<FetchListItemsOrdersForCollectionParams> & {
+		query?: StandardInfiniteQueryOptions;
+	};
+
+export function getListItemsOrdersForCollectionQueryKey(
+	params: ListItemsOrdersForCollectionQueryOptions,
+) {
+	const apiArgs = {
+		chainId: String(params.chainId),
+		contractAddress: params.collectionAddress,
+		side: params.side,
+		filter: params.filter,
+	} satisfies QueryKeyArgs<Omit<ListOrdersWithCollectiblesArgs, 'page'>>;
+
+	return [...collectionKeys.collectionItemsOrders, apiArgs] as const;
+}
+
+export function listItemsOrdersForCollectionQueryOptions(
+	params: ListItemsOrdersForCollectionQueryOptions,
+) {
+	const enabled = Boolean(
+		params.collectionAddress &&
+			params.chainId &&
+			params.config &&
+			params.side &&
+			(params.query?.enabled ?? true),
+	);
+
+	return infiniteQueryOptions({
+		queryKey: getListItemsOrdersForCollectionQueryKey(params),
+		queryFn: async ({ pageParam }) => {
+			return fetchListItemsOrdersForCollection(
+				{
+					// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+					chainId: params.chainId!,
+					// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+					collectionAddress: params.collectionAddress!,
+					// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+					config: params.config!,
+					// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+					side: params.side!,
+					filter: params.filter,
+				},
+				pageParam,
+			);
+		},
+		initialPageParam: (params.page || { page: 1, pageSize: 30 }) as Page,
+		getNextPageParam: (lastPage) =>
+			lastPage.page?.more ? lastPage.page : undefined,
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/orders/listItemsOrdersForCollectionPaginated.ts

@@ -0,0 +1,90 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { Page, SdkConfig } from '../../../types';
+import type {
+	ListOrdersWithCollectiblesArgs,
+	ListOrdersWithCollectiblesReturn,
+	ValuesOptional,
+} from '../../_internal';
+import { collectionKeys, getMarketplaceClient } from '../../_internal';
+import type { StandardQueryOptions } from '../../types/query';
+
+export interface FetchListItemsOrdersForCollectionPaginatedParams
+	extends Omit<
+		ListOrdersWithCollectiblesArgs,
+		'chainId' | 'contractAddress' | 'page'
+	> {
+	chainId: number;
+	collectionAddress: Address;
+	page?: number;
+	pageSize?: number;
+	config: SdkConfig;
+}
+
+/**
+ * Fetches a list of items orders for a collection with pagination support from the Marketplace API
+ */
+export async function fetchListItemsOrdersForCollectionPaginated(
+	params: FetchListItemsOrdersForCollectionPaginatedParams,
+): Promise<ListOrdersWithCollectiblesReturn> {
+	const {
+		collectionAddress,
+		chainId,
+		config,
+		page = 1,
+		pageSize = 30,
+		...additionalApiParams
+	} = params;
+	const marketplaceClient = getMarketplaceClient(config);
+
+	const pageParams: Page = {
+		page,
+		pageSize,
+	};
+
+	const apiArgs: ListOrdersWithCollectiblesArgs = {
+		contractAddress: collectionAddress,
+		chainId: String(chainId),
+		page: pageParams,
+		...additionalApiParams,
+	};
+
+	return await marketplaceClient.listOrdersWithCollectibles(apiArgs);
+}
+
+export type ListItemsOrdersForCollectionPaginatedQueryOptions =
+	ValuesOptional<FetchListItemsOrdersForCollectionPaginatedParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function listItemsOrdersForCollectionPaginatedQueryOptions(
+	params: ListItemsOrdersForCollectionPaginatedQueryOptions,
+) {
+	const enabled = Boolean(
+		params.collectionAddress &&
+			params.chainId &&
+			params.config &&
+			params.side &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: [...collectionKeys.collectionItemsOrders, 'paginated', params],
+		queryFn: () =>
+			fetchListItemsOrdersForCollectionPaginated({
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				chainId: params.chainId!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				collectionAddress: params.collectionAddress!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				side: params.side!,
+				filter: params.filter,
+				page: params.page,
+				pageSize: params.pageSize,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/{listListingsForCollectible.ts → orders/listListingsForCollectible.ts}

@@ -1,13 +1,14 @@
 import { queryOptions } from '@tanstack/react-query';
 import type { Address } from 'viem';
-import type { SdkConfig } from '../../types';
+import type { SdkConfig } from '../../../types';
 import type {
 	ListCollectibleListingsArgs,
 	ListCollectibleListingsReturn,
+	QueryKeyArgs,
 	ValuesOptional,
-} from '../_internal';
-import { collectableKeys, getMarketplaceClient } from '../_internal';
-import type { StandardQueryOptions } from '../types/query';
+} from '../../_internal';
+import { collectableKeys, getMarketplaceClient } from '../../_internal';
+import type { StandardQueryOptions } from '../../types/query';
 
 export interface FetchListListingsForCollectibleParams
 	extends Omit<
@@ -50,6 +51,20 @@ export type ListListingsForCollectibleQueryOptions =
 		query?: StandardQueryOptions;
 	};
 
+export function getListListingsForCollectibleQueryKey(
+	params: ListListingsForCollectibleQueryOptions,
+) {
+	const apiArgs = {
+		chainId: String(params.chainId),
+		contractAddress: params.collectionAddress,
+		tokenId: params.collectibleId,
+		filter: params.filter,
+		page: params.page,
+	} satisfies QueryKeyArgs<ListCollectibleListingsArgs>;
+
+	return [...collectableKeys.listings, apiArgs] as const;
+}
+
 export function listListingsForCollectibleQueryOptions(
 	params: ListListingsForCollectibleQueryOptions,
 ) {
@@ -62,7 +77,7 @@ export function listListingsForCollectibleQueryOptions(
 	);
 
 	return queryOptions({
-		queryKey: [...collectableKeys.listings, params],
+		queryKey: getListListingsForCollectibleQueryKey(params),
 		queryFn: () =>
 			fetchListListingsForCollectible({
 				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined

package/src/react/queries/orders/listOffersForCollectible.ts

@@ -0,0 +1,116 @@
+import { queryOptions } from '@tanstack/react-query';
+import type { Address } from 'viem';
+import type { SdkConfig } from '../../../types';
+import type {
+	ListCollectibleOffersReturn,
+	ListOffersForCollectibleArgs,
+	Page,
+	QueryKeyArgs,
+	SortBy,
+	ValuesOptional,
+} from '../../_internal';
+import { collectableKeys, getMarketplaceClient } from '../../_internal';
+import type { StandardQueryOptions } from '../../types/query';
+
+export interface FetchListOffersForCollectibleParams
+	extends Omit<
+		ListOffersForCollectibleArgs,
+		'chainId' | 'contractAddress' | 'tokenId'
+	> {
+	chainId: number;
+	collectionAddress: Address;
+	collectibleId: string;
+	config: SdkConfig;
+	sort?: Array<SortBy>;
+}
+
+/**
+ * Fetches offers for a specific collectible from the Marketplace API
+ */
+export async function fetchListOffersForCollectible(
+	params: FetchListOffersForCollectibleParams,
+): Promise<ListCollectibleOffersReturn> {
+	const {
+		collectionAddress,
+		chainId,
+		collectibleId,
+		config,
+		sort,
+		page,
+		...additionalApiParams
+	} = params;
+	const marketplaceClient = getMarketplaceClient(config);
+
+	const finalSort = sort || (page && 'sort' in page ? page.sort : undefined);
+
+	let finalPage: Page | undefined;
+	if (page || finalSort) {
+		finalPage = {
+			page: page?.page ?? 1,
+			pageSize: page?.pageSize ?? 20,
+			...(page?.more && { more: page.more }),
+			...(finalSort && { sort: finalSort }),
+		} as Page;
+	}
+
+	const apiArgs: ListOffersForCollectibleArgs = {
+		contractAddress: collectionAddress,
+		chainId: String(chainId),
+		tokenId: collectibleId,
+		page: finalPage,
+		...additionalApiParams,
+	};
+
+	return await marketplaceClient.listCollectibleOffers(apiArgs);
+}
+
+export type ListOffersForCollectibleQueryOptions =
+	ValuesOptional<FetchListOffersForCollectibleParams> & {
+		query?: StandardQueryOptions;
+	};
+
+export function getListOffersForCollectibleQueryKey(
+	params: ListOffersForCollectibleQueryOptions,
+) {
+	const apiArgs = {
+		chainId: String(params.chainId),
+		contractAddress: params.collectionAddress,
+		tokenId: params.collectibleId,
+		filter: params.filter,
+		page: params.page,
+	} satisfies QueryKeyArgs<ListOffersForCollectibleArgs>;
+
+	return [...collectableKeys.offers, apiArgs] as const;
+}
+
+export function listOffersForCollectibleQueryOptions(
+	params: ListOffersForCollectibleQueryOptions,
+) {
+	const enabled = Boolean(
+		params.collectionAddress &&
+			params.chainId &&
+			params.collectibleId &&
+			params.config &&
+			(params.query?.enabled ?? true),
+	);
+
+	return queryOptions({
+		queryKey: getListOffersForCollectibleQueryKey(params),
+		queryFn: () =>
+			fetchListOffersForCollectible({
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				chainId: params.chainId!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				collectionAddress: params.collectionAddress!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				collectibleId: params.collectibleId!,
+				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined
+				config: params.config!,
+				filter: params.filter,
+				page: params.page,
+				sort: params.sort,
+			}),
+		...params.query,
+		enabled,
+	});
+}

package/src/react/queries/{lowestListing.ts → orders/lowestListing.ts}

@@ -1,13 +1,14 @@
 import { queryOptions } from '@tanstack/react-query';
-import type { SdkConfig } from '../../types';
+import type { SdkConfig } from '../../../types';
 import {
 	collectableKeys,
 	type GetCollectibleLowestListingArgs,
 	type GetCollectibleLowestListingReturn,
 	getMarketplaceClient,
+	type QueryKeyArgs,
 	type ValuesOptional,
-} from '../_internal';
-import type { StandardQueryOptions } from '../types/query';
+} from '../../_internal';
+import type { StandardQueryOptions } from '../../types/query';
 
 export interface FetchLowestListingParams
 	extends Omit<GetCollectibleLowestListingArgs, 'contractAddress' | 'chainId'> {
@@ -41,6 +42,17 @@ export type LowestListingQueryOptions =
 		query?: StandardQueryOptions;
 	};
 
+export function getLowestListingQueryKey(params: LowestListingQueryOptions) {
+	const apiArgs = {
+		chainId: String(params.chainId),
+		contractAddress: params.collectionAddress,
+		tokenId: params.tokenId,
+		filter: params.filter,
+	} satisfies QueryKeyArgs<GetCollectibleLowestListingArgs>;
+
+	return [...collectableKeys.lowestListings, apiArgs] as const;
+}
+
 export function lowestListingQueryOptions(params: LowestListingQueryOptions) {
 	const enabled = Boolean(
 		params.collectionAddress &&
@@ -51,7 +63,7 @@ export function lowestListingQueryOptions(params: LowestListingQueryOptions) {
 	);
 
 	return queryOptions({
-		queryKey: [...collectableKeys.lowestListings, params],
+		queryKey: getLowestListingQueryKey(params),
 		queryFn: () =>
 			fetchLowestListing({
 				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined

package/src/react/queries/{countOfPrimarySaleItems.ts → primary-sales/countOfPrimarySaleItems.ts}

@@ -1,11 +1,13 @@
 import { queryOptions } from '@tanstack/react-query';
 import type { Address } from 'viem';
-import type { SdkConfig } from '../../types';
+import type { SdkConfig } from '../../../types';
 import {
+	collectableKeys,
 	type GetCountOfPrimarySaleItemsArgs,
 	getMarketplaceClient,
 	type PrimarySaleItemsFilter,
-} from '../_internal';
+	type QueryKeyArgs,
+} from '../../_internal';
 
 export interface UseCountOfPrimarySaleItemsArgs
 	extends Omit<
@@ -36,13 +38,25 @@ export async function fetchCountOfPrimarySaleItems(
 	return data.count;
 }
 
+export function getCountOfPrimarySaleItemsQueryKey(
+	args: UseCountOfPrimarySaleItemsArgs,
+) {
+	const apiArgs = {
+		chainId: String(args.chainId),
+		primarySaleContractAddress: args.primarySaleContractAddress,
+		filter: args.filter,
+	} satisfies QueryKeyArgs<GetCountOfPrimarySaleItemsArgs>;
+
+	return [...collectableKeys.primarySaleItemsCount, apiArgs] as const;
+}
+
 export function countOfPrimarySaleItemsOptions(
 	args: UseCountOfPrimarySaleItemsArgs,
 	config: SdkConfig,
 ) {
 	return queryOptions({
 		enabled: args.query?.enabled ?? true,
-		queryKey: ['countOfPrimarySaleItems', args],
+		queryKey: getCountOfPrimarySaleItemsQueryKey(args),
 		queryFn: () => fetchCountOfPrimarySaleItems(args, config),
 	});
 }

package/src/react/queries/primary-sales/index.ts

@@ -0,0 +1,3 @@
+export * from './countOfPrimarySaleItems';
+export * from './primarySaleItems';
+export * from './primarySaleItemsCount';

package/src/react/queries/{primarySaleItems.ts → primary-sales/primarySaleItems.ts}

@@ -1,15 +1,17 @@
 import { infiniteQueryOptions } from '@tanstack/react-query';
 import type { Address } from 'viem';
-import type { SdkConfig } from '../../types';
+import type { SdkConfig } from '../../../types';
 import {
+	collectableKeys,
 	getMarketplaceClient,
 	type ListPrimarySaleItemsArgs,
 	type ListPrimarySaleItemsReturn,
 	type Page,
 	type PrimarySaleItemsFilter,
+	type QueryKeyArgs,
 	type ValuesOptional,
-} from '../_internal';
-import type { StandardQueryOptions } from '../types/query';
+} from '../../_internal';
+import type { StandardQueryOptions } from '../../types/query';
 
 export interface FetchPrimarySaleItemsParams {
 	chainId: number;
@@ -42,6 +44,18 @@ export type ListPrimarySaleItemsQueryOptions =
 		query?: StandardQueryOptions;
 	};
 
+export function getListPrimarySaleItemsQueryKey(
+	params: ListPrimarySaleItemsQueryOptions,
+) {
+	const apiArgs = {
+		chainId: String(params.chainId),
+		primarySaleContractAddress: params.primarySaleContractAddress,
+		filter: params.filter,
+	} satisfies QueryKeyArgs<Omit<ListPrimarySaleItemsArgs, 'page'>>;
+
+	return [...collectableKeys.listPrimarySaleItems, apiArgs] as const;
+}
+
 export const listPrimarySaleItemsQueryOptions = (
 	params: ListPrimarySaleItemsQueryOptions,
 ) => {
@@ -56,7 +70,7 @@ export const listPrimarySaleItemsQueryOptions = (
 	const initialPage: PageParam = params.page || { page: 1, pageSize: 30 };
 
 	return infiniteQueryOptions({
-		queryKey: ['listPrimarySaleItems', params],
+		queryKey: getListPrimarySaleItemsQueryKey(params),
 		queryFn: async ({ pageParam }) => {
 			return fetchPrimarySaleItems({
 				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined

package/src/react/queries/{primarySaleItemsCount.ts → primary-sales/primarySaleItemsCount.ts}

@@ -1,12 +1,15 @@
 import { queryOptions } from '@tanstack/react-query';
 import type { Address } from 'viem';
-import type { SdkConfig } from '../../types';
+import type { SdkConfig } from '../../../types';
 import {
+	collectableKeys,
+	type GetCountOfPrimarySaleItemsArgs,
 	type GetCountOfPrimarySaleItemsReturn,
 	getMarketplaceClient,
 	type PrimarySaleItemsFilter,
-} from '../_internal';
-import type { StandardQueryOptions } from '../types/query';
+	type QueryKeyArgs,
+} from '../../_internal';
+import type { StandardQueryOptions } from '../../types/query';
 
 export interface FetchPrimarySaleItemsCountParams {
 	chainId: number;
@@ -36,6 +39,18 @@ export type PrimarySaleItemsCountQueryOptions =
 		query?: StandardQueryOptions;
 	};
 
+export function getPrimarySaleItemsCountQueryKey(
+	args: PrimarySaleItemsCountQueryOptions,
+) {
+	const apiArgs = {
+		chainId: String(args.chainId),
+		primarySaleContractAddress: args.primarySaleContractAddress,
+		filter: args.filter,
+	} satisfies QueryKeyArgs<GetCountOfPrimarySaleItemsArgs>;
+
+	return [...collectableKeys.primarySaleItemsCount, apiArgs] as const;
+}
+
 export const primarySaleItemsCountQueryOptions = (
 	args: PrimarySaleItemsCountQueryOptions,
 ) => {
@@ -47,7 +62,7 @@ export const primarySaleItemsCountQueryOptions = (
 	);
 
 	return queryOptions({
-		queryKey: ['primarySaleItemsCount', args],
+		queryKey: getPrimarySaleItemsCountQueryKey(args),
 		queryFn: () =>
 			fetchPrimarySaleItemsCount({
 				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined

package/src/react/queries/{getTokenRanges.ts → tokens/getTokenRanges.ts}

@@ -1,9 +1,13 @@
 import type { GetTokenIDRangesReturn } from '@0xsequence/indexer';
 import { queryOptions } from '@tanstack/react-query';
 import type { Address } from 'viem';
-import type { SdkConfig } from '../../types';
-import { getIndexerClient, type ValuesOptional } from '../_internal';
-import type { StandardQueryOptions } from '../types/query';
+import type { SdkConfig } from '../../../types';
+import {
+	getIndexerClient,
+	tokenKeys,
+	type ValuesOptional,
+} from '../../_internal';
+import type { StandardQueryOptions } from '../../types/query';
 
 export interface FetchGetTokenRangesParams {
 	chainId: number;
@@ -37,6 +41,15 @@ export type GetTokenRangesQueryOptions =
 		query?: StandardQueryOptions;
 	};
 
+export function getTokenRangesQueryKey(params: GetTokenRangesQueryOptions) {
+	const apiArgs = {
+		chainId: params.chainId!,
+		contractAddress: params.collectionAddress!,
+	};
+
+	return [...tokenKeys.ranges, apiArgs] as const;
+}
+
 export function getTokenRangesQueryOptions(params: GetTokenRangesQueryOptions) {
 	const enabled = Boolean(
 		params.chainId &&
@@ -46,7 +59,7 @@ export function getTokenRangesQueryOptions(params: GetTokenRangesQueryOptions) {
 	);
 
 	return queryOptions({
-		queryKey: ['indexer', 'tokenRanges', params],
+		queryKey: getTokenRangesQueryKey(params),
 		queryFn: () =>
 			fetchGetTokenRanges({
 				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined

package/src/react/queries/tokens/index.ts

@@ -0,0 +1,5 @@
+export * from './getTokenRanges';
+export * from './listBalances';
+export * from './listTokenMetadata';
+export * from './searchTokenMetadata';
+export * from './tokenSupplies';

package/src/react/queries/{listBalances.ts → tokens/listBalances.ts}

@@ -1,8 +1,8 @@
 import type { GetTokenBalancesReturn, Page } from '@0xsequence/indexer';
 import { infiniteQueryOptions } from '@tanstack/react-query';
 import type { Address, Hex } from 'viem';
-import type { SdkConfig } from '../../types';
-import { balanceQueries, getIndexerClient, LaosAPI } from '../_internal';
+import type { SdkConfig } from '../../../types';
+import { balanceQueries, getIndexerClient, LaosAPI } from '../../_internal';
 
 export type UseListBalancesArgs = {
 	chainId: number;
@@ -55,6 +55,21 @@ export async function fetchBalances(
 	});
 }
 
+export function getListBalancesQueryKey(args: UseListBalancesArgs) {
+	const apiArgs = {
+		chainId: args.chainId,
+		accountAddress: args.accountAddress,
+		contractAddress: args.contractAddress,
+		tokenID: args.tokenId,
+		includeMetadata: args.includeMetadata,
+		metadataOptions: args.metadataOptions,
+		includeCollectionTokens: args.includeCollectionTokens,
+		isLaos721: args.isLaos721,
+	};
+
+	return [...balanceQueries.lists, apiArgs] as const;
+}
+
 /**
  * Creates a tanstack infinite query options object for the balances query
  *
@@ -68,7 +83,7 @@ export function listBalancesOptions(
 ) {
 	return infiniteQueryOptions({
 		...args.query,
-		queryKey: [...balanceQueries.lists, args, config],
+		queryKey: getListBalancesQueryKey(args),
 		queryFn: ({ pageParam }) => fetchBalances(args, config, pageParam),
 		initialPageParam: { page: 1, pageSize: 30 } as Page,
 		getNextPageParam: (lastPage) => lastPage.page.after,

package/src/react/queries/{listTokenMetadata.ts → tokens/listTokenMetadata.ts}

@@ -1,11 +1,13 @@
+import type { GetTokenMetadataArgs } from '@0xsequence/metadata';
 import { queryOptions } from '@tanstack/react-query';
-import type { SdkConfig } from '../../types';
+import type { SdkConfig } from '../../../types';
 import {
 	getMetadataClient,
+	type QueryKeyArgs,
 	tokenKeys,
 	type ValuesOptional,
-} from '../_internal';
-import type { StandardQueryOptions } from '../types/query';
+} from '../../_internal';
+import type { StandardQueryOptions } from '../../types/query';
 
 export interface FetchListTokenMetadataParams {
 	chainId: number;
@@ -37,6 +39,18 @@ export type ListTokenMetadataQueryOptions =
 		query?: StandardQueryOptions;
 	};
 
+export function getListTokenMetadataQueryKey(
+	params: ListTokenMetadataQueryOptions,
+) {
+	const apiArgs = {
+		chainID: String(params.chainId),
+		contractAddress: params.contractAddress,
+		tokenIDs: params.tokenIds,
+	} satisfies QueryKeyArgs<GetTokenMetadataArgs>;
+
+	return [...tokenKeys.metadata, apiArgs] as const;
+}
+
 export function listTokenMetadataQueryOptions(
 	params: ListTokenMetadataQueryOptions,
 ) {
@@ -49,7 +63,7 @@ export function listTokenMetadataQueryOptions(
 	);
 
 	return queryOptions({
-		queryKey: [...tokenKeys.metadata, params],
+		queryKey: getListTokenMetadataQueryKey(params),
 		queryFn: () =>
 			fetchListTokenMetadata({
 				// biome-ignore lint/style/noNonNullAssertion: The enabled check above ensures these are not undefined