thordata-sdk 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

thordata/async_client.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 import asyncio
 import logging
 import os
+from datetime import date, datetime
 from typing import Any, Dict, List, Optional, Union
 
 import aiohttp
@@ -32,7 +33,9 @@ import aiohttp
 from . import __version__ as _sdk_version
 from ._utils import (
     build_auth_headers,
+    build_builder_headers,
     build_public_api_headers,
+    build_sign_headers,
     build_user_agent,
     decode_base64_image,
     extract_error_message,
@@ -45,7 +48,18 @@ from .exceptions import (
     ThordataTimeoutError,
     raise_for_code,
 )
-from .models import ProxyConfig, ScraperTaskConfig, SerpRequest, UniversalScrapeRequest
+from .models import (
+    CommonSettings,
+    ProxyConfig,
+    ProxyServer,
+    ProxyUser,
+    ProxyUserList,
+    ScraperTaskConfig,
+    SerpRequest,
+    UniversalScrapeRequest,
+    UsageStatistics,
+    VideoTaskConfig,
+)
 from .retry import RetryConfig
 
 logger = logging.getLogger(__name__)
@@ -78,18 +92,22 @@ class AsyncThordataClient:
     # API Endpoints (same as sync client)
     BASE_URL = "https://scraperapi.thordata.com"
     UNIVERSAL_URL = "https://universalapi.thordata.com"
-    API_URL = "https://api.thordata.com/api/web-scraper-api"
-    LOCATIONS_URL = "https://api.thordata.com/api/locations"
+    API_URL = "https://openapi.thordata.com/api/web-scraper-api"
+    LOCATIONS_URL = "https://openapi.thordata.com/api/locations"
 
     def __init__(
         self,
         scraper_token: str,
         public_token: Optional[str] = None,
         public_key: Optional[str] = None,
+        sign: Optional[str] = None,
+        api_key: Optional[str] = None,
         proxy_host: str = "pr.thordata.net",
         proxy_port: int = 9999,
         timeout: int = 30,
+        api_timeout: int = 60,
         retry_config: Optional[RetryConfig] = None,
+        auth_mode: str = "bearer",
         scraperapi_base_url: Optional[str] = None,
         universalapi_base_url: Optional[str] = None,
         web_scraper_api_base_url: Optional[str] = None,
@@ -103,14 +121,33 @@ class AsyncThordataClient:
         self.public_token = public_token
         self.public_key = public_key
 
+        # Automatic Fallback Logic: If sign/api_key is not provided, try using public_token/key
+        self.sign = sign or os.getenv("THORDATA_SIGN") or self.public_token
+        self.api_key = api_key or os.getenv("THORDATA_API_KEY") or self.public_key
+
+        # Public API authentication
+        self.sign = sign or os.getenv("THORDATA_SIGN")
+        self.api_key = api_key or os.getenv("THORDATA_API_KEY")
+
         # Proxy configuration
         self._proxy_host = proxy_host
         self._proxy_port = proxy_port
         self._default_timeout = aiohttp.ClientTimeout(total=timeout)
 
+        # Timeout configuration
+        self._default_timeout = aiohttp.ClientTimeout(total=timeout)
+        self._api_timeout = aiohttp.ClientTimeout(total=api_timeout)
+
         # Retry configuration
         self._retry_config = retry_config or RetryConfig()
 
+        # Authentication mode
+        self._auth_mode = auth_mode.lower()
+        if self._auth_mode not in ("bearer", "header_token"):
+            raise ThordataConfigError(
+                f"Invalid auth_mode: {auth_mode}. Must be 'bearer' or 'header_token'."
+            )
+
         # Pre-calculate proxy auth
         self._proxy_url = f"http://{proxy_host}:{proxy_port}"
         self._proxy_auth = aiohttp.BasicAuth(
@@ -142,12 +179,39 @@ class AsyncThordataClient:
             or self.LOCATIONS_URL
         ).rstrip("/")
 
+        gateway_base = os.getenv(
+            "THORDATA_GATEWAY_BASE_URL", "https://api.thordata.com/api/gateway"
+        )
+        child_base = os.getenv(
+            "THORDATA_CHILD_BASE_URL", "https://api.thordata.com/api/child"
+        )
+
+        self._gateway_base_url = gateway_base
+        self._child_base_url = child_base
+
         self._serp_url = f"{scraperapi_base}/request"
         self._builder_url = f"{scraperapi_base}/builder"
+        self._video_builder_url = f"{scraperapi_base}/video_builder"
         self._universal_url = f"{universalapi_base}/request"
         self._status_url = f"{web_scraper_api_base}/tasks-status"
         self._download_url = f"{web_scraper_api_base}/tasks-download"
         self._locations_base_url = locations_base
+        self._usage_stats_url = (
+            f"{locations_base.replace('/locations', '')}/account/usage-statistics"
+        )
+        self._proxy_users_url = (
+            f"{locations_base.replace('/locations', '')}/proxy-users"
+        )
+        whitelist_base = os.getenv(
+            "THORDATA_WHITELIST_BASE_URL", "https://api.thordata.com/api"
+        )
+        self._whitelist_url = f"{whitelist_base}/whitelisted-ips"
+        proxy_api_base = os.getenv(
+            "THORDATA_PROXY_API_BASE_URL", "https://api.thordata.com/api"
+        )
+        self._proxy_list_url = f"{proxy_api_base}/proxy/proxy-list"
+        self._proxy_expiration_url = f"{proxy_api_base}/proxy/expiration-time"
+        self._list_url = f"{web_scraper_api_base}/tasks-list"
 
         # Session initialized lazily
         self._session: Optional[aiohttp.ClientSession] = None
@@ -156,7 +220,7 @@ class AsyncThordataClient:
         """Async context manager entry."""
         if self._session is None or self._session.closed:
             self._session = aiohttp.ClientSession(
-                timeout=self._default_timeout,
+                timeout=self._api_timeout,
                 trust_env=True,
                 headers={"User-Agent": build_user_agent(_sdk_version, "aiohttp")},
             )
@@ -324,7 +388,7 @@ class AsyncThordataClient:
         )
 
         payload = request.to_payload()
-        headers = build_auth_headers(self.scraper_token)
+        headers = build_auth_headers(self.scraper_token, mode=self._auth_mode)
 
         logger.info(f"Async SERP Search: {engine_str} - {query}")
 
@@ -372,7 +436,7 @@ class AsyncThordataClient:
         session = self._get_session()
 
         payload = request.to_payload()
-        headers = build_auth_headers(self.scraper_token)
+        headers = build_auth_headers(self.scraper_token, mode=self._auth_mode)
 
         logger.info(f"Async SERP Advanced: {request.engine} - {request.query}")
 
@@ -466,7 +530,7 @@ class AsyncThordataClient:
         session = self._get_session()
 
         payload = request.to_payload()
-        headers = build_auth_headers(self.scraper_token)
+        headers = build_auth_headers(self.scraper_token, mode=self._auth_mode)
 
         logger.info(f"Async Universal Scrape: {request.url}")
 
@@ -538,10 +602,16 @@ class AsyncThordataClient:
         """
         Create a task using ScraperTaskConfig.
         """
+        self._require_public_credentials()
         session = self._get_session()
 
         payload = config.to_payload()
-        headers = build_auth_headers(self.scraper_token)
+        # Builder needs 3 headers: token, key, Authorization Bearer
+        headers = build_builder_headers(
+            self.scraper_token,
+            self.public_token or "",
+            self.public_key or "",
+        )
 
         logger.info(f"Async Task Creation: {config.spider_name}")
 
@@ -566,6 +636,75 @@ class AsyncThordataClient:
                 f"Task creation failed: {e}", original_error=e
             ) from e
 
+    async def create_video_task(
+        self,
+        file_name: str,
+        spider_id: str,
+        spider_name: str,
+        parameters: Dict[str, Any],
+        common_settings: CommonSettings,
+    ) -> str:
+        """
+        Create a YouTube video/audio download task.
+        """
+
+        config = VideoTaskConfig(
+            file_name=file_name,
+            spider_id=spider_id,
+            spider_name=spider_name,
+            parameters=parameters,
+            common_settings=common_settings,
+        )
+
+        return await self.create_video_task_advanced(config)
+
+    async def create_video_task_advanced(self, config: VideoTaskConfig) -> str:
+        """
+        Create a video task using VideoTaskConfig object.
+        """
+
+        self._require_public_credentials()
+        session = self._get_session()
+
+        payload = config.to_payload()
+        headers = build_builder_headers(
+            self.scraper_token,
+            self.public_token or "",
+            self.public_key or "",
+        )
+
+        logger.info(
+            f"Async Video Task Creation: {config.spider_name} - {config.spider_id}"
+        )
+
+        try:
+            async with session.post(
+                self._video_builder_url,
+                data=payload,
+                headers=headers,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(
+                        f"Video task creation failed: {msg}", code=code, payload=data
+                    )
+
+                return data["data"]["task_id"]
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Video task creation timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Video task creation failed: {e}", original_error=e
+            ) from e
+
     async def get_task_status(self, task_id: str) -> str:
         """
         Check async task status.
@@ -667,6 +806,61 @@ class AsyncThordataClient:
                 f"Get result failed: {e}", original_error=e
             ) from e
 
+    async def list_tasks(
+        self,
+        page: int = 1,
+        size: int = 20,
+    ) -> Dict[str, Any]:
+        """
+        List all Web Scraper tasks.
+
+        Args:
+            page: Page number (starts from 1).
+            size: Number of tasks per page.
+
+        Returns:
+            Dict containing 'count' and 'list' of tasks.
+        """
+        self._require_public_credentials()
+        session = self._get_session()
+
+        headers = build_public_api_headers(
+            self.public_token or "", self.public_key or ""
+        )
+        payload: Dict[str, Any] = {}
+        if page:
+            payload["page"] = str(page)
+        if size:
+            payload["size"] = str(size)
+
+        logger.info(f"Async listing tasks: page={page}, size={size}")
+
+        try:
+            async with session.post(
+                self._list_url,
+                data=payload,
+                headers=headers,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(f"List tasks failed: {msg}", code=code, payload=data)
+
+                return data.get("data", {"count": 0, "list": []})
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"List tasks timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"List tasks failed: {e}", original_error=e
+            ) from e
+
     async def wait_for_task(
         self,
         task_id: str,
@@ -703,6 +897,591 @@ class AsyncThordataClient:
 
         raise TimeoutError(f"Task {task_id} did not complete within {max_wait} seconds")
 
+    # =========================================================================
+    # Proxy Account Management Methods
+    # =========================================================================
+
+    async def get_usage_statistics(
+        self,
+        from_date: Union[str, date],
+        to_date: Union[str, date],
+    ) -> UsageStatistics:
+        """
+        Get account usage statistics for a date range.
+
+        Args:
+            from_date: Start date (YYYY-MM-DD string or date object).
+            to_date: End date (YYYY-MM-DD string or date object).
+
+        Returns:
+            UsageStatistics object with traffic data.
+        """
+
+        self._require_public_credentials()
+        session = self._get_session()
+
+        # Convert dates to strings
+        if isinstance(from_date, date):
+            from_date = from_date.strftime("%Y-%m-%d")
+        if isinstance(to_date, date):
+            to_date = to_date.strftime("%Y-%m-%d")
+
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "from_date": from_date,
+            "to_date": to_date,
+        }
+
+        logger.info(f"Async getting usage statistics: {from_date} to {to_date}")
+
+        try:
+            async with session.get(
+                self._usage_stats_url,
+                params=params,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                if isinstance(data, dict):
+                    code = data.get("code")
+                    if code is not None and code != 200:
+                        msg = extract_error_message(data)
+                        raise_for_code(
+                            f"Usage statistics error: {msg}",
+                            code=code,
+                            payload=data,
+                        )
+
+                    usage_data = data.get("data", data)
+                    return UsageStatistics.from_dict(usage_data)
+
+                raise ThordataNetworkError(
+                    f"Unexpected usage statistics response: {type(data).__name__}",
+                    original_error=None,
+                )
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Usage statistics timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Usage statistics failed: {e}", original_error=e
+            ) from e
+
+    async def get_residential_balance(self) -> Dict[str, Any]:
+        """
+        Get residential proxy balance (Public API NEW).
+
+        Requires sign and apiKey credentials.
+
+        Returns:
+            Dict with 'balance' (bytes) and 'expire_time' (timestamp).
+        """
+        if not self.sign or not self.api_key:
+            raise ThordataConfigError(
+                "sign and api_key are required for Public API NEW. "
+                "Set THORDATA_SIGN and THORDATA_API_KEY environment variables."
+            )
+
+        session = self._get_session()
+        headers = build_sign_headers(self.sign, self.api_key)
+
+        logger.info("Async getting residential proxy balance (API NEW)")
+
+        try:
+            async with session.post(
+                f"{self._gateway_base_url}/getFlowBalance",
+                headers=headers,
+                data={},
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(
+                        f"Get balance failed: {msg}", code=code, payload=data
+                    )
+
+                return data.get("data", {})
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Get balance timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Get balance failed: {e}", original_error=e
+            ) from e
+
+    async def get_residential_usage(
+        self,
+        start_time: Union[str, int],
+        end_time: Union[str, int],
+    ) -> Dict[str, Any]:
+        """
+        Get residential proxy usage records (Public API NEW).
+
+        Args:
+            start_time: Start timestamp (Unix timestamp or YYYY-MM-DD HH:MM:SS).
+            end_time: End timestamp (Unix timestamp or YYYY-MM-DD HH:MM:SS).
+
+        Returns:
+            Dict with usage data including 'all_flow', 'all_used_flow', 'data' list.
+        """
+        if not self.sign or not self.api_key:
+            raise ThordataConfigError(
+                "sign and api_key are required for Public API NEW."
+            )
+
+        session = self._get_session()
+        headers = build_sign_headers(self.sign, self.api_key)
+        payload = {
+            "start_time": str(start_time),
+            "end_time": str(end_time),
+        }
+
+        logger.info(f"Async getting residential usage: {start_time} to {end_time}")
+
+        try:
+            async with session.post(
+                f"{self._gateway_base_url}/usageRecord",
+                headers=headers,
+                data=payload,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(f"Get usage failed: {msg}", code=code, payload=data)
+
+                return data.get("data", {})
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Get usage timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Get usage failed: {e}", original_error=e
+            ) from e
+
+    async def list_proxy_users(
+        self, proxy_type: Union[ProxyType, int] = ProxyType.RESIDENTIAL
+    ) -> ProxyUserList:
+        """List all proxy users (sub-accounts)."""
+
+        self._require_public_credentials()
+        session = self._get_session()
+
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(
+                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+            ),
+        }
+
+        logger.info(f"Async listing proxy users: type={params['proxy_type']}")
+
+        try:
+            async with session.get(
+                f"{self._proxy_users_url}/user-list",
+                params=params,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                if isinstance(data, dict):
+                    code = data.get("code")
+                    if code is not None and code != 200:
+                        msg = extract_error_message(data)
+                        raise_for_code(
+                            f"List proxy users error: {msg}", code=code, payload=data
+                        )
+
+                    user_data = data.get("data", data)
+                    return ProxyUserList.from_dict(user_data)
+
+                raise ThordataNetworkError(
+                    f"Unexpected proxy users response: {type(data).__name__}",
+                    original_error=None,
+                )
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"List users timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"List users failed: {e}", original_error=e
+            ) from e
+
+    async def create_proxy_user(
+        self,
+        username: str,
+        password: str,
+        proxy_type: Union[ProxyType, int] = ProxyType.RESIDENTIAL,
+        traffic_limit: int = 0,
+        status: bool = True,
+    ) -> Dict[str, Any]:
+        """Create a new proxy user (sub-account)."""
+        self._require_public_credentials()
+        session = self._get_session()
+
+        headers = build_public_api_headers(
+            self.public_token or "", self.public_key or ""
+        )
+
+        payload = {
+            "proxy_type": str(
+                int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+            ),
+            "username": username,
+            "password": password,
+            "traffic_limit": str(traffic_limit),
+            "status": "true" if status else "false",
+        }
+
+        logger.info(f"Async creating proxy user: {username}")
+
+        try:
+            async with session.post(
+                f"{self._proxy_users_url}/create-user",
+                data=payload,
+                headers=headers,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(
+                        f"Create proxy user failed: {msg}", code=code, payload=data
+                    )
+
+                return data.get("data", {})
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Create user timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Create user failed: {e}", original_error=e
+            ) from e
+
+    async def add_whitelist_ip(
+        self,
+        ip: str,
+        proxy_type: Union[ProxyType, int] = ProxyType.RESIDENTIAL,
+        status: bool = True,
+    ) -> Dict[str, Any]:
+        """
+        Add an IP to the whitelist for IP authentication.
+        """
+        self._require_public_credentials()
+        session = self._get_session()
+
+        headers = build_public_api_headers(
+            self.public_token or "", self.public_key or ""
+        )
+
+        proxy_type_int = (
+            int(proxy_type) if isinstance(proxy_type, ProxyType) else proxy_type
+        )
+
+        payload = {
+            "proxy_type": str(proxy_type_int),
+            "ip": ip,
+            "status": "true" if status else "false",
+        }
+
+        logger.info(f"Async adding whitelist IP: {ip}")
+
+        try:
+            async with session.post(
+                f"{self._whitelist_url}/add-ip",
+                data=payload,
+                headers=headers,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(
+                        f"Add whitelist IP failed: {msg}", code=code, payload=data
+                    )
+
+                return data.get("data", {})
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Add whitelist timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Add whitelist failed: {e}", original_error=e
+            ) from e
+
+    async def list_proxy_servers(
+        self,
+        proxy_type: int,
+    ) -> List[ProxyServer]:
+        """
+        List ISP or Datacenter proxy servers.
+        """
+
+        self._require_public_credentials()
+        session = self._get_session()
+
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(proxy_type),
+        }
+
+        logger.info(f"Async listing proxy servers: type={proxy_type}")
+
+        try:
+            async with session.get(
+                self._proxy_list_url,
+                params=params,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                if isinstance(data, dict):
+                    code = data.get("code")
+                    if code is not None and code != 200:
+                        msg = extract_error_message(data)
+                        raise_for_code(
+                            f"List proxy servers error: {msg}", code=code, payload=data
+                        )
+
+                    server_list = data.get("data", data.get("list", []))
+                elif isinstance(data, list):
+                    server_list = data
+                else:
+                    raise ThordataNetworkError(
+                        f"Unexpected proxy list response: {type(data).__name__}",
+                        original_error=None,
+                    )
+
+                return [ProxyServer.from_dict(s) for s in server_list]
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"List servers timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"List servers failed: {e}", original_error=e
+            ) from e
+
+    async def get_isp_regions(self) -> List[Dict[str, Any]]:
+        """
+        Get available ISP proxy regions (Public API NEW).
+
+        Returns:
+            List of regions with id, continent, country, city, num, pricing.
+        """
+        if not self.sign or not self.api_key:
+            raise ThordataConfigError(
+                "sign and api_key are required for Public API NEW."
+            )
+
+        session = self._get_session()
+        headers = build_sign_headers(self.sign, self.api_key)
+
+        logger.info("Async getting ISP regions (API NEW)")
+
+        try:
+            async with session.post(
+                f"{self._gateway_base_url}/getRegionIsp",
+                headers=headers,
+                data={},
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(
+                        f"Get ISP regions failed: {msg}", code=code, payload=data
+                    )
+
+                return data.get("data", [])
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Get ISP regions timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Get ISP regions failed: {e}", original_error=e
+            ) from e
+
+    async def list_isp_proxies(self) -> List[Dict[str, Any]]:
+        """
+        List ISP proxies (Public API NEW).
+
+        Returns:
+            List of ISP proxies with ip, port, user, pwd, startTime, expireTime.
+        """
+        if not self.sign or not self.api_key:
+            raise ThordataConfigError(
+                "sign and api_key are required for Public API NEW."
+            )
+
+        session = self._get_session()
+        headers = build_sign_headers(self.sign, self.api_key)
+
+        logger.info("Async listing ISP proxies (API NEW)")
+
+        try:
+            async with session.post(
+                f"{self._gateway_base_url}/queryListIsp",
+                headers=headers,
+                data={},
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(
+                        f"List ISP proxies failed: {msg}", code=code, payload=data
+                    )
+
+                return data.get("data", [])
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"List ISP proxies timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"List ISP proxies failed: {e}", original_error=e
+            ) from e
+
+    async def get_wallet_balance(self) -> Dict[str, Any]:
+        """
+        Get wallet balance for ISP proxies (Public API NEW).
+
+        Returns:
+            Dict with 'walletBalance'.
+        """
+        if not self.sign or not self.api_key:
+            raise ThordataConfigError(
+                "sign and api_key are required for Public API NEW."
+            )
+
+        session = self._get_session()
+        headers = build_sign_headers(self.sign, self.api_key)
+
+        logger.info("Async getting wallet balance (API NEW)")
+
+        try:
+            async with session.post(
+                f"{self._gateway_base_url}/getBalance",
+                headers=headers,
+                data={},
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                code = data.get("code")
+                if code != 200:
+                    msg = extract_error_message(data)
+                    raise_for_code(
+                        f"Get wallet balance failed: {msg}", code=code, payload=data
+                    )
+
+                return data.get("data", {})
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Get wallet balance timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Get wallet balance failed: {e}", original_error=e
+            ) from e
+
+    async def get_proxy_expiration(
+        self,
+        ips: Union[str, List[str]],
+        proxy_type: int,
+    ) -> Dict[str, Any]:
+        """
+        Get expiration time for specific proxy IPs.
+        """
+        self._require_public_credentials()
+        session = self._get_session()
+
+        if isinstance(ips, list):
+            ips = ",".join(ips)
+
+        params = {
+            "token": self.public_token,
+            "key": self.public_key,
+            "proxy_type": str(proxy_type),
+            "ips": ips,
+        }
+
+        logger.info(f"Async getting proxy expiration: {ips}")
+
+        try:
+            async with session.get(
+                self._proxy_expiration_url,
+                params=params,
+                timeout=self._api_timeout,
+            ) as response:
+                response.raise_for_status()
+                data = await response.json()
+
+                if isinstance(data, dict):
+                    code = data.get("code")
+                    if code is not None and code != 200:
+                        msg = extract_error_message(data)
+                        raise_for_code(
+                            f"Get expiration error: {msg}", code=code, payload=data
+                        )
+
+                    return data.get("data", data)
+
+                return data
+
+        except asyncio.TimeoutError as e:
+            raise ThordataTimeoutError(
+                f"Get expiration timed out: {e}", original_error=e
+            ) from e
+        except aiohttp.ClientError as e:
+            raise ThordataNetworkError(
+                f"Get expiration failed: {e}", original_error=e
+            ) from e
+
     # =========================================================================
     # Location API Methods
     # =========================================================================