@omen.foundation/game-sdk 1.0.14 → 1.0.15

package/dist/index.d.mts

@@ -74,8 +74,9 @@ interface OmenXGameSDKConfig {
 interface OAuthOptions {
     /**
      * Redirect URI (must be registered in developer portal)
+     * If not provided, defaults to `${window.location.origin}/auth/callback`
      */
-    redirectUri: string;
+    redirectUri?: string;
     /**
      * State parameter for CSRF protection (auto-generated if not provided)
      */
@@ -194,12 +195,19 @@ declare class OmenXServerSDK {
     /**
      * Player Operations
      */
+    /**
+     * Get full player data: NFTs (system + game) and balances for a wallet.
+     * Requires both nfts:read and balances:read scopes.
+     */
+    getPlayer(wallet: string, chainId: string): Promise<any>;
     /**
      * Get native and ERC20 token balances for a wallet
      */
     getPlayerBalances(wallet: string, chainId: string): Promise<any>;
     /**
-     * Get paginated NFTs for a wallet
+     * Get paginated NFTs for a wallet.
+     * With no contract: returns OmenX system NFTs (Asset Manager, Faucet, Early Adopter) + game NFTs.
+     * With contract: returns only NFTs for that contract.
      */
     getPlayerNfts(wallet: string, chainId: string, options?: {
         contract?: string;

package/dist/index.d.ts

@@ -74,8 +74,9 @@ interface OmenXGameSDKConfig {
 interface OAuthOptions {
     /**
      * Redirect URI (must be registered in developer portal)
+     * If not provided, defaults to `${window.location.origin}/auth/callback`
      */
-    redirectUri: string;
+    redirectUri?: string;
     /**
      * State parameter for CSRF protection (auto-generated if not provided)
      */
@@ -194,12 +195,19 @@ declare class OmenXServerSDK {
     /**
      * Player Operations
      */
+    /**
+     * Get full player data: NFTs (system + game) and balances for a wallet.
+     * Requires both nfts:read and balances:read scopes.
+     */
+    getPlayer(wallet: string, chainId: string): Promise<any>;
     /**
      * Get native and ERC20 token balances for a wallet
      */
     getPlayerBalances(wallet: string, chainId: string): Promise<any>;
     /**
-     * Get paginated NFTs for a wallet
+     * Get paginated NFTs for a wallet.
+     * With no contract: returns OmenX system NFTs (Asset Manager, Faucet, Early Adopter) + game NFTs.
+     * With contract: returns only NFTs for that contract.
      */
     getPlayerNfts(wallet: string, chainId: string, options?: {
         contract?: string;

package/dist/index.js

@@ -1,83 +1,34 @@
 'use strict';
 
-// src/pkce.ts
-async function generatePKCE() {
-  const codeVerifier = generateRandomString(128);
-  const hash = await sha256(codeVerifier);
-  const codeChallenge = base64URLEncode(hash);
-  return { codeVerifier, codeChallenge };
-}
-function generateRandomString(length) {
-  const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
-  const array = new Uint8Array(length);
-  crypto.getRandomValues(array);
-  return Array.from(array, (byte) => charset[byte % charset.length]).join("");
-}
-function base64URLEncode(buffer) {
-  const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));
-  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
-}
-async function sha256(message) {
-  const encoder = new TextEncoder();
-  const data = encoder.encode(message);
-  return crypto.subtle.digest("SHA-256", data);
-}
-
 // src/oauth.ts
 var OAuthFlow = class {
   constructor(config) {
     this.config = config;
   }
   /**
-   * Authenticate user via OAuth popup
+   * Authenticate user via OAuth 2.0 Authorization Code Grant with PKCE
    */
-  async authenticate(options) {
-    const state = options.state || this.generateState();
-    try {
-      const allKeys = Object.keys(localStorage).filter((k) => k.startsWith("omenx_oauth_callback_"));
-      console.log("[OAuthFlow] \u{1F9F9} Cleaning up old OAuth entries:", { count: allKeys.length });
-      allKeys.forEach((key) => {
-        try {
-          const data = localStorage.getItem(key);
-          if (data) {
-            const parsed = JSON.parse(data);
-            const age = Date.now() - (parsed.timestamp || 0);
-            if (age > 3e5) {
-              localStorage.removeItem(key);
-              console.log("[OAuthFlow] \u{1F5D1}\uFE0F Removed old entry:", key.substring(0, 50) + "...", { age: `${age}ms` });
-            }
-          }
-        } catch (e) {
-          localStorage.removeItem(key);
-        }
-      });
-    } catch (error) {
-      console.warn("[OAuthFlow] \u26A0\uFE0F Error cleaning up old entries:", error);
-    }
-    let codeChallenge;
-    let codeVerifier;
-    if (options.enablePKCE !== false) {
-      const pkce = await generatePKCE();
-      codeChallenge = pkce.codeChallenge;
-      codeVerifier = pkce.codeVerifier;
-      sessionStorage.setItem(`omenx_pkce_${state}`, codeVerifier);
-    }
+  async authenticate(options = {}) {
+    const state = this.generateState();
+    const codeVerifier = this.generateCodeVerifier();
+    const codeChallenge = await this.generateCodeChallenge(codeVerifier);
     return new Promise((resolve, reject) => {
-      const params = new URLSearchParams({
-        client_id: this.config.gameId,
-        redirect_uri: options.redirectUri,
-        response_type: "code",
-        state
-      });
-      if (codeChallenge) {
-        params.append("code_challenge", codeChallenge);
-        params.append("code_challenge_method", "S256");
-      }
-      const authUrl = `${this.config.oauthAuthorizeUrl}?${params.toString()}`;
+      sessionStorage.setItem(`omenx_pkce_${state}`, codeVerifier);
+      const redirectUri = options.redirectUri || `${window.location.origin}/auth/callback`;
+      const authUrl = new URL(this.config.oauthAuthorizeUrl);
+      authUrl.searchParams.set("client_id", this.config.gameId);
+      authUrl.searchParams.set("redirect_uri", redirectUri);
+      authUrl.searchParams.set("response_type", "code");
+      authUrl.searchParams.set("scope", "openid profile email");
+      authUrl.searchParams.set("state", state);
+      authUrl.searchParams.set("code_challenge", codeChallenge);
+      authUrl.searchParams.set("code_challenge_method", "S256");
+      const stateStorageKey = `omenx_oauth_state_${state}`;
+      sessionStorage.setItem(stateStorageKey, state);
       const popup = window.open(
-        authUrl,
-        "OmenX Authentication",
-        "width=500,height=600,left=" + (window.screen.width / 2 - 250) + ",top=" + (window.screen.height / 2 - 300)
+        authUrl.toString(),
+        "OmenX OAuth",
+        "width=500,height=600,left=100,top=100"
       );
       if (!popup) {
         const error = new Error("Failed to open popup window. Please allow popups for this site.");
@@ -85,346 +36,92 @@ var OAuthFlow = class {
         reject(error);
         return;
       }
-      const messageListener = async (event) => {
-        try {
-          const currentOrigin = window.location.origin;
-          if (event.origin !== currentOrigin) {
-            return;
-          }
-        } catch {
-        }
-        if (event.data?.type === "OMENX_OAUTH_CODE") {
-          window.removeEventListener("message", messageListener);
-          popup.close();
-          const { code, state: returnedState } = event.data;
-          if (returnedState !== state) {
-            const error = new Error("Invalid state parameter. Possible CSRF attack.");
-            this.config.onError?.(error);
-            reject(error);
-            return;
-          }
-          const storedCodeVerifier = sessionStorage.getItem(`omenx_pkce_${state}`);
-          if (storedCodeVerifier) {
-            sessionStorage.removeItem(`omenx_pkce_${state}`);
-            codeVerifier = storedCodeVerifier;
-          }
+      try {
+        const allKeys = Object.keys(localStorage).filter((k) => k.startsWith("omenx_oauth_callback_"));
+        allKeys.forEach((key) => {
           try {
-            const tokenResponse = await this.exchangeCodeForToken(code, options.redirectUri, codeVerifier);
-            await this.config.onTokenReceived(tokenResponse);
-            resolve(tokenResponse);
-          } catch (error) {
-            this.config.onError?.(error);
-            reject(error);
-          }
-        }
-      };
-      window.addEventListener("message", messageListener);
-      const storageListener = (event) => {
-        if (!event.key || !event.key.startsWith("omenx_oauth_callback_")) {
-          return;
-        }
-        const callbackState = event.key.replace("omenx_oauth_callback_", "");
-        if (callbackState !== state) {
-          return;
-        }
-        try {
-          const data = JSON.parse(event.newValue || "{}");
-          if (data.code && data.state === state) {
-            console.log("[OAuthFlow] Received OAuth code via localStorage fallback");
-            messageReceived = true;
-            window.removeEventListener("storage", storageListener);
-            window.removeEventListener("message", wrappedMessageListener);
-            const { code: codeFromStorage } = data;
-            const storedCodeVerifier = sessionStorage.getItem(`omenx_pkce_${state}`);
-            let codeVerifier2;
-            if (storedCodeVerifier) {
-              sessionStorage.removeItem(`omenx_pkce_${state}`);
-              codeVerifier2 = storedCodeVerifier;
+            const data = localStorage.getItem(key);
+            if (data) {
+              const parsed = JSON.parse(data);
+              const age = Date.now() - (parsed.timestamp || 0);
+              if (age > 3e5) {
+                localStorage.removeItem(key);
+              }
             }
-            this.exchangeCodeForToken(codeFromStorage, options.redirectUri, codeVerifier2).then(async (tokenResponse) => {
-              await this.config.onTokenReceived(tokenResponse);
-              resolve(tokenResponse);
-            }).catch((error) => {
-              this.config.onError?.(error);
-              reject(error);
-            });
-            localStorage.removeItem(event.key);
+          } catch (e) {
+            localStorage.removeItem(key);
           }
-        } catch (error) {
-          console.error("[OAuthFlow] Error processing localStorage callback:", error);
-        }
-      };
-      window.addEventListener("storage", storageListener);
-      let pollCount = 0;
-      const storageKey = `omenx_oauth_callback_${state}`;
-      const immediateCheck = () => {
-        const allKeys = Object.keys(localStorage).filter((k) => k.startsWith("omenx_oauth_callback_"));
-        console.log("[OAuthFlow] \u{1F50D} Immediate localStorage check:", {
-          count: allKeys.length,
-          keys: allKeys.map((k) => k.substring(0, 50) + "..."),
-          lookingFor: storageKey.substring(0, 50) + "...",
-          expectedState: state.substring(0, 20) + "..."
         });
-        for (const key of allKeys) {
-          const storedData = localStorage.getItem(key);
-          if (storedData) {
-            try {
-              const data = JSON.parse(storedData);
-              console.log("[OAuthFlow] \u{1F50D} Checking stored key:", {
-                key: key.substring(0, 50) + "...",
-                storedState: data.state?.substring(0, 20) + "...",
-                expectedState: state.substring(0, 20) + "...",
-                statesMatch: data.state === state,
-                hasCode: !!data.code,
-                timestamp: data.timestamp,
-                age: data.timestamp ? `${Date.now() - data.timestamp}ms` : "unknown"
-              });
-            } catch (e) {
-              console.warn("[OAuthFlow] \u26A0\uFE0F Error parsing stored key:", key, e);
-            }
-          }
-        }
-      };
-      immediateCheck();
-      console.log("[OAuthFlow] \u{1F504} Starting localStorage polling interval (every 100ms)");
+      } catch (error) {
+      }
+      const storageKey = `omenx_oauth_callback_${state}`;
+      let messageReceived = false;
       const pollInterval = setInterval(() => {
-        pollCount++;
-        const stored = localStorage.getItem(storageKey);
-        if (pollCount % 10 === 0) {
-          console.log("[OAuthFlow] \u{1F50D} Polling localStorage...", {
-            key: storageKey.substring(0, 50) + "...",
-            found: !!stored,
-            pollCount,
-            statePreview: state.substring(0, 20) + "...",
-            intervalActive: true
-          });
-          if (pollCount % 100 === 0) {
-            immediateCheck();
-          }
+        if (messageReceived) {
+          clearInterval(pollInterval);
+          return;
         }
+        const stored = localStorage.getItem(storageKey);
         if (stored) {
           try {
             const data = JSON.parse(stored);
-            if (pollCount === 1 || pollCount % 10 === 0) {
-              console.log("[OAuthFlow] \u2705 Found stored data!", {
-                hasCode: !!data.code,
-                hasState: !!data.state,
-                stateMatch: data.state === state,
-                storedState: data.state?.substring(0, 20) + "...",
-                expectedState: state.substring(0, 20) + "...",
-                pollCount
-              });
-            }
             if (data.code && data.state === state) {
               const age = Date.now() - (data.timestamp || 0);
               if (age < 3e4) {
-                console.log("[OAuthFlow] \u2705\u2705\u2705 Processing OAuth callback from localStorage!", {
-                  age: `${age}ms`,
-                  hasCode: !!data.code,
-                  codePreview: data.code.substring(0, 10) + "...",
-                  pollCount
-                });
+                messageReceived = true;
                 clearInterval(pollInterval);
-                window.removeEventListener("storage", storageListener);
-                storageListener(new StorageEvent("storage", {
-                  key: storageKey,
-                  newValue: stored,
-                  storageArea: localStorage
-                }));
+                localStorage.removeItem(storageKey);
+                sessionStorage.removeItem(`omenx_pkce_${state}`);
+                sessionStorage.removeItem(stateStorageKey);
+                this.exchangeCodeForToken(data.code, redirectUri, codeVerifier).then(async (tokenResponse) => {
+                  await this.config.onTokenReceived(tokenResponse);
+                  if (popup && !popup.closed) {
+                    try {
+                      popup.close();
+                    } catch (e) {
+                    }
+                  }
+                  resolve(tokenResponse);
+                }).catch((error) => {
+                  this.config.onError?.(error);
+                  reject(error);
+                });
                 return;
               } else {
-                console.warn("[OAuthFlow] \u26A0\uFE0F Callback data too old, removing:", { age: `${age}ms` });
                 localStorage.removeItem(storageKey);
               }
-            } else {
-              console.warn("[OAuthFlow] \u26A0\uFE0F State mismatch!", {
-                storedState: data.state?.substring(0, 20) + "...",
-                expectedState: state.substring(0, 20) + "...",
-                statesMatch: data.state === state,
-                storedStateLength: data.state?.length,
-                expectedStateLength: state.length,
-                pollCount
-              });
             }
           } catch (error) {
-            console.error("[OAuthFlow] \u274C Error parsing localStorage callback:", error, {
-              stored: stored?.substring(0, 100) + "...",
-              pollCount
-            });
-          }
-        } else {
-          if (pollCount === 1 || pollCount % 5 === 0) {
-            const allKeys = Object.keys(localStorage).filter((k) => k.startsWith("omenx_oauth_callback_"));
-            if (allKeys.length > 0) {
-              console.log("[OAuthFlow] \u{1F50D} Found localStorage keys (checking all for state match):", {
-                count: allKeys.length,
-                keys: allKeys.map((k) => k.substring(0, 50) + "..."),
-                lookingFor: storageKey.substring(0, 50) + "...",
-                expectedState: state.substring(0, 20) + "...",
-                pollCount
-              });
-              for (const key of allKeys) {
-                const storedData = localStorage.getItem(key);
-                if (storedData) {
-                  try {
-                    const data = JSON.parse(storedData);
-                    const statesMatch = data.state === state;
-                    console.log("[OAuthFlow] \u{1F50D} Checking stored key:", {
-                      key: key.substring(0, 50) + "...",
-                      storedState: data.state?.substring(0, 20) + "...",
-                      expectedState: state.substring(0, 20) + "...",
-                      statesMatch,
-                      storedStateLength: data.state?.length,
-                      expectedStateLength: state.length,
-                      hasCode: !!data.code,
-                      pollCount
-                    });
-                    if (statesMatch && data.code) {
-                      const age = Date.now() - (data.timestamp || 0);
-                      if (age < 3e4) {
-                        console.log("[OAuthFlow] \u2705\u2705\u2705 Found matching state in different key! Processing...", {
-                          key: key.substring(0, 50) + "...",
-                          age: `${age}ms`,
-                          pollCount
-                        });
-                        clearInterval(pollInterval);
-                        window.removeEventListener("storage", storageListener);
-                        storageListener(new StorageEvent("storage", {
-                          key,
-                          newValue: storedData,
-                          storageArea: localStorage
-                        }));
-                        return;
-                      }
-                    }
-                  } catch (e) {
-                    console.warn("[OAuthFlow] \u26A0\uFE0F Error parsing key:", key, e);
-                  }
-                }
-              }
-            }
+            console.error("[OAuthFlow] Error parsing localStorage callback:", error);
           }
         }
       }, 100);
-      let broadcastChannel = null;
-      try {
-        broadcastChannel = new BroadcastChannel("omenx_oauth");
-        const broadcastListener = (event) => {
-          if (event.data?.type === "OMENX_OAUTH_CODE" && event.data?.state === state) {
-            console.log("[OAuthFlow] \u2705 Received OAuth code via BroadcastChannel");
-            messageReceived = true;
-            clearInterval(pollInterval);
-            if (broadcastChannel) {
-              broadcastChannel.onmessage = null;
-              broadcastChannel.close();
-            }
-            window.removeEventListener("message", wrappedMessageListener);
-            window.removeEventListener("storage", storageListener);
-            const { code: codeFromBroadcast } = event.data;
-            const storedCodeVerifier = sessionStorage.getItem(`omenx_pkce_${state}`);
-            let codeVerifier2;
-            if (storedCodeVerifier) {
-              sessionStorage.removeItem(`omenx_pkce_${state}`);
-              codeVerifier2 = storedCodeVerifier;
-            }
-            this.exchangeCodeForToken(codeFromBroadcast, options.redirectUri, codeVerifier2).then(async (tokenResponse) => {
-              await this.config.onTokenReceived(tokenResponse);
-              resolve(tokenResponse);
-            }).catch((error) => {
-              this.config.onError?.(error);
-              reject(error);
-            });
-          }
-        };
-        broadcastChannel.onmessage = broadcastListener;
-      } catch (error) {
-        console.warn("[OAuthFlow] BroadcastChannel not supported:", error);
-        broadcastChannel = null;
-      }
-      console.log("[OAuthFlow] \u{1F50D} Starting OAuth flow, listening for callback...", {
-        state,
-        statePreview: state.substring(0, 20) + "...",
-        stateLength: state.length,
-        hasOpener: !!window.opener,
-        polling: true,
-        broadcastChannel: true,
-        expectedKey: `omenx_oauth_callback_${state}`
-      });
-      let messageReceived = false;
-      const originalMessageListener = messageListener;
-      const wrappedMessageListener = async (event) => {
-        messageReceived = true;
-        clearInterval(pollInterval);
-        window.removeEventListener("storage", storageListener);
-        await originalMessageListener(event);
-      };
-      window.removeEventListener("message", messageListener);
-      window.addEventListener("message", wrappedMessageListener);
-      const isPopupActuallyClosed = () => {
-        try {
-          if (!popup.closed) {
-            return false;
-          }
-          try {
-            const _ = popup.location.href;
-            return true;
-          } catch (e) {
-            return false;
-          }
-        } catch (e) {
-          return false;
-        }
-      };
-      let popupClosedTime = null;
-      const POPUP_CLOSED_GRACE_PERIOD = 5e3;
       const checkClosed = setInterval(() => {
         if (messageReceived) {
           clearInterval(checkClosed);
-          clearInterval(pollInterval);
           return;
         }
-        if (isPopupActuallyClosed()) {
-          if (popupClosedTime === null) {
-            popupClosedTime = Date.now();
-            console.log("[OAuthFlow] \u26A0\uFE0F Popup appears closed, starting grace period for callback...", {
-              gracePeriod: `${POPUP_CLOSED_GRACE_PERIOD}ms`,
-              pollCount,
-              stillPolling: true
-            });
-            return;
-          }
-          const timeSinceClosed = Date.now() - popupClosedTime;
-          if (timeSinceClosed < POPUP_CLOSED_GRACE_PERIOD) {
-            console.log("[OAuthFlow] \u23F3 Popup closed, but still in grace period...", {
-              timeRemaining: `${POPUP_CLOSED_GRACE_PERIOD - timeSinceClosed}ms`,
-              pollCount
-            });
-            return;
+        let isClosed = false;
+        try {
+          if (popup.closed) {
+            try {
+              popup.location.href;
+              isClosed = true;
+            } catch (e) {
+              isClosed = false;
+            }
           }
-          console.log("[OAuthFlow] \u274C Popup closed and grace period expired without callback", {
-            timeSinceClosed: `${timeSinceClosed}ms`,
-            pollCount,
-            finalCheck: "Checking localStorage one last time..."
-          });
-          immediateCheck();
+        } catch (e) {
+          isClosed = false;
+        }
+        if (isClosed) {
           clearInterval(checkClosed);
           clearInterval(pollInterval);
-          window.removeEventListener("message", wrappedMessageListener);
-          window.removeEventListener("storage", storageListener);
-          if (broadcastChannel) {
-            broadcastChannel.onmessage = null;
-            broadcastChannel.close();
-          }
-          if (!messageReceived) {
-            const error = new Error("Authentication was cancelled.");
-            this.config.onError?.(error);
-            reject(error);
-          }
-        } else {
-          if (popupClosedTime !== null) {
-            console.log("[OAuthFlow] \u2705 Popup is open again (was temporarily on different origin)");
-            popupClosedTime = null;
-          }
+          sessionStorage.removeItem(`omenx_pkce_${state}`);
+          sessionStorage.removeItem(stateStorageKey);
+          const error = new Error("Authentication was cancelled.");
+          this.config.onError?.(error);
+          reject(error);
         }
       }, 1e3);
     });
@@ -436,7 +133,8 @@ var OAuthFlow = class {
     const body = {
       code,
       redirect_uri: redirectUri,
-      grant_type: "authorization_code"
+      grant_type: "authorization_code",
+      client_id: this.config.gameId
     };
     if (codeVerifier) {
       body.code_verifier = codeVerifier;
@@ -445,8 +143,6 @@ var OAuthFlow = class {
       method: "POST",
       headers: {
         "Content-Type": "application/json"
-        // Note: API key should be included via Authorization header
-        // This should be set by the game's backend, not the SDK
       },
       body: JSON.stringify(body)
     });
@@ -464,6 +160,25 @@ var OAuthFlow = class {
     crypto.getRandomValues(array);
     return Array.from(array, (byte) => byte.toString(16).padStart(2, "0")).join("");
   }
+  /**
+   * Generate PKCE code verifier
+   */
+  generateCodeVerifier() {
+    const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+    const array = new Uint8Array(128);
+    crypto.getRandomValues(array);
+    return Array.from(array, (byte) => charset[byte % charset.length]).join("");
+  }
+  /**
+   * Generate PKCE code challenge from verifier
+   */
+  async generateCodeChallenge(verifier) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(verifier);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    const base64 = btoa(String.fromCharCode(...new Uint8Array(hash)));
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+  }
 };
 
 // src/iframe-auth.ts
@@ -657,7 +372,17 @@ var OmenXGameSDK = class {
    * Authenticate user via OAuth popup
    */
   async authenticate(options) {
-    return this.oauthFlow.authenticate(options);
+    const tokenResponse = await this.oauthFlow.authenticate(options);
+    return {
+      accessToken: tokenResponse.access_token,
+      walletAddress: tokenResponse.user.walletAddress,
+      userId: tokenResponse.user.userId,
+      profileName: tokenResponse.user.profileName,
+      profilePicture: tokenResponse.user.profilePicture,
+      email: tokenResponse.user.email,
+      gameId: this.config.gameId,
+      timestamp: Date.now()
+    };
   }
   /**
    * Get current authentication data
@@ -830,22 +555,38 @@ var OmenXServerSDK = class {
   /**
    * Player Operations
    */
+  /**
+   * Get full player data: NFTs (system + game) and balances for a wallet.
+   * Requires both nfts:read and balances:read scopes.
+   */
+  async getPlayer(wallet, chainId) {
+    const response = await this.apiCall(
+      `/v1/players/${encodeURIComponent(wallet)}?chainId=${encodeURIComponent(chainId)}`
+    );
+    return response.json();
+  }
   /**
    * Get native and ERC20 token balances for a wallet
    */
   async getPlayerBalances(wallet, chainId) {
-    const response = await this.apiCall(`/v1/players/${wallet}/balances?chainId=${chainId}`);
+    const response = await this.apiCall(
+      `/v1/players/${encodeURIComponent(wallet)}/balances?chainId=${encodeURIComponent(chainId)}`
+    );
     return response.json();
   }
   /**
-   * Get paginated NFTs for a wallet
+   * Get paginated NFTs for a wallet.
+   * With no contract: returns OmenX system NFTs (Asset Manager, Faucet, Early Adopter) + game NFTs.
+   * With contract: returns only NFTs for that contract.
    */
   async getPlayerNfts(wallet, chainId, options) {
     const params = new URLSearchParams({ chainId });
-    if (options?.contract) params.append("contract", options.contract);
-    if (options?.cursor) params.append("cursor", options.cursor);
-    if (options?.limit) params.append("limit", options.limit.toString());
-    const response = await this.apiCall(`/v1/players/${wallet}/nfts?${params.toString()}`);
+    if (options?.contract) params.set("contract", options.contract);
+    if (options?.cursor) params.set("cursor", options.cursor);
+    if (options?.limit != null) params.set("limit", String(options.limit));
+    const response = await this.apiCall(
+      `/v1/players/${encodeURIComponent(wallet)}/nfts?${params.toString()}`
+    );
     return response.json();
   }
   /**