docs: explain limited ux

Signed-off-by: shankar <shankar@layerzero.org>

Author: shankar

packages/hyperliquid-composer/src/operations/spotDeploy.ts

@@ -203,20 +203,23 @@ export async function setNoHyperliquidity(
         if (!state) {
             // Token is already deployed - check for pending spot pairs in spotMetaAndAssetCtxs
             logger.info(
-                `No in progress deployment state found for token ${tokenIndex}. Checking for pending spot pairs...`
+                `No in progress deployment state found for token ${tokenIndex}. Checking for pending spot pairs network-wide...`
             )
 
-            const pendingSpots = await getPendingSpotPairs(isTestnet, tokenIndex, logLevel)
+            const pendingSpots = await getPendingSpotPairs(isTestnet, logLevel)
 
             if (pendingSpots.length === 0) {
-                logger.error(
-                    `No pending spot pairs found for token ${tokenIndex}. The token is fully deployed with no pending pairs.`
-                )
+                logger.error(`No pending spot pairs found network-wide.`)
                 logger.info(`Tip: If you know the spot index, use --spot-index <id> to directly specify it.`)
                 process.exit(1)
             }
 
-            logger.info(`Found ${pendingSpots.length} pending spot pair(s):`)
+            logger.warn(
+                `WARNING: The API does not provide token composition for pending spots. ` +
+                    `The following are ALL pending spots network-wide, not filtered by token ${tokenIndex}.`
+            )
+            logger.warn(`Use --spot-index <id> to directly specify your spot if you know it from register-spot output.`)
+            logger.info(`Found ${pendingSpots.length} pending spot pair(s) network-wide:`)
             pendingSpots.forEach((spot) => {
                 logger.info(`  - ${spot.coin} (spot index: ${spot.spotIndex}, markPx: ${spot.markPx})`)
             })

packages/hyperliquid-composer/src/operations/spotMeta.ts

@@ -179,18 +179,16 @@ export async function getExistingQuoteTokens(
  * Gets pending spot pairs that exist in spotMetaAndAssetCtxs but NOT in the universe.
  * These are spots that have been registered via registerSpot but not yet finalized.
  *
- * Note: The Hyperliquid API does not provide token composition info for pending spots,
+ * IMPORTANT: The Hyperliquid API does not provide token composition info for pending spots,
  * so this function returns ALL pending spots network-wide, not filtered by token.
  * Users should use the --spot-index flag to directly specify which spot to finalize.
  *
  * @param isTestnet Whether to query testnet or mainnet
- * @param _tokenIndex Unused - API doesn't support filtering pending spots by token
  * @param logLevel Logging level for the client
- * @returns Array of pending spot indices and their details
+ * @returns Array of pending spot indices and their details (network-wide, not token-specific)
  */
 export async function getPendingSpotPairs(
     isTestnet: boolean,
-    _tokenIndex: number,
     logLevel: string
 ): Promise<Array<{ spotIndex: number; coin: string; markPx: string }>> {
     const hyperliquidClient = new HyperliquidClient(isTestnet, logLevel)