tgtc-sdk 0.1.0__tar.gz

tgtc_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TGTC-Suiyoung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tgtc_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: tgtc-sdk
+Version: 0.1.0
+Summary: TGTC BSC 代币数据 API 的 Python 客户端（计费透明：每次返回剩余次数与扣次明细）
+License-Expression: MIT
+Project-URL: Homepage, https://www.tgtcbot.com
+Project-URL: Documentation, https://github.com/TGTC-Suiyoung/tgtc-api-docs
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# tgtc-sdk (Python)
+
+TGTC 数据 API 的 Python 客户端。一行代码接入 BSC 代币数据：基本行情、持仓结构、安全审计、持有人、社交信息、聪明钱动向。
+
+**计费透明**：每次调用都会返回剩余次数与本次扣次明细，余额一眼可见。
+
+## 安装
+
+```bash
+pip install tgtc-sdk
+```
+
+需要先创建 API Key（TGTC Bot 个人中心 → 我的 API）。
+
+## 快速开始
+
+```python
+from tgtc import TGTC
+
+client = TGTC(api_key="你的 API Key")
+
+# 代币聚合查询（默认返回完整产品类别）
+res = client.token("0x...合约地址")
+
+print(res.symbol)          # 代币符号
+print(res.price)           # 当前价格
+print(res.remaining)       # 剩余调用次数
+print(res.used)            # 本次扣次
+```
+
+## 按类别/字段查询
+
+```python
+# 只要行情 + 安全审计，扣次更少
+res = client.token(ca, categories=["basic", "security"])
+
+# 精确字段裁剪（与 categories 二选一）
+res = client.token(ca, fields=["symbol", "price", "honeypot", "buy_tax"])
+```
+
+可选类别：`basic`（基本行情）/ `structure`（持仓结构）/ `holders`（持有人）/ `security`（安全审计）/ `social`（社交信息）/ `traders`（聪明钱动向）。
+
+## 计费明细
+
+| 字段 | 说明 |
+| --- | --- |
+| `remaining` | 剩余调用次数 |
+| `used` | 本次扣次（缓存命中为 0） |
+| `cache_hit` | 是否命中缓存（命中不扣次） |
+| `delay_sec` | 数据新鲜度（0 = 实时） |
+
+## 错误处理
+
+```python
+from tgtc import TGTCError, TGTCQuotaError, TGTCAuthError
+
+try:
+    res = client.token(ca)
+except TGTCAuthError:
+    print("API Key 无效")
+except TGTCQuotaError:
+    print("调用次数不足，请充值")
+except TGTCError as e:
+    print("请求失败：", e)
+```
+
+| 异常 | 触发条件 |
+| --- | --- |
+| `TGTCAuthError` | API Key 缺失或无效 |
+| `TGTCParamError` | 参数错误（CA 格式/类别组合） |
+| `TGTCNotFoundError` | 代币数据不存在 |
+| `TGTCQuotaError` | 调用次数不足 |
+| `TGTCUnavailableError` | 服务初始化或维护中 |
+
+## 路线图
+
+- [x] token：代币聚合查询
+- [ ] token/trending + token/hot：榜单
+- [ ] twitter：推特检测/舆情
+- [ ] track：交易流
+- [ ] market：信号流
+- [ ] wallet：钱包分析
+- [ ] translate：翻译
+
+## 文档
+
+完整接口文档见 [TGTC API Docs](https://github.com/TGTC-Suiyoung/tgtc-api-docs)。

tgtc_sdk-0.1.0/README.md

@@ -0,0 +1,87 @@
+# tgtc-sdk (Python)
+
+TGTC 数据 API 的 Python 客户端。一行代码接入 BSC 代币数据：基本行情、持仓结构、安全审计、持有人、社交信息、聪明钱动向。
+
+**计费透明**：每次调用都会返回剩余次数与本次扣次明细，余额一眼可见。
+
+## 安装
+
+```bash
+pip install tgtc-sdk
+```
+
+需要先创建 API Key（TGTC Bot 个人中心 → 我的 API）。
+
+## 快速开始
+
+```python
+from tgtc import TGTC
+
+client = TGTC(api_key="你的 API Key")
+
+# 代币聚合查询（默认返回完整产品类别）
+res = client.token("0x...合约地址")
+
+print(res.symbol)          # 代币符号
+print(res.price)           # 当前价格
+print(res.remaining)       # 剩余调用次数
+print(res.used)            # 本次扣次
+```
+
+## 按类别/字段查询
+
+```python
+# 只要行情 + 安全审计，扣次更少
+res = client.token(ca, categories=["basic", "security"])
+
+# 精确字段裁剪（与 categories 二选一）
+res = client.token(ca, fields=["symbol", "price", "honeypot", "buy_tax"])
+```
+
+可选类别：`basic`（基本行情）/ `structure`（持仓结构）/ `holders`（持有人）/ `security`（安全审计）/ `social`（社交信息）/ `traders`（聪明钱动向）。
+
+## 计费明细
+
+| 字段 | 说明 |
+| --- | --- |
+| `remaining` | 剩余调用次数 |
+| `used` | 本次扣次（缓存命中为 0） |
+| `cache_hit` | 是否命中缓存（命中不扣次） |
+| `delay_sec` | 数据新鲜度（0 = 实时） |
+
+## 错误处理
+
+```python
+from tgtc import TGTCError, TGTCQuotaError, TGTCAuthError
+
+try:
+    res = client.token(ca)
+except TGTCAuthError:
+    print("API Key 无效")
+except TGTCQuotaError:
+    print("调用次数不足，请充值")
+except TGTCError as e:
+    print("请求失败：", e)
+```
+
+| 异常 | 触发条件 |
+| --- | --- |
+| `TGTCAuthError` | API Key 缺失或无效 |
+| `TGTCParamError` | 参数错误（CA 格式/类别组合） |
+| `TGTCNotFoundError` | 代币数据不存在 |
+| `TGTCQuotaError` | 调用次数不足 |
+| `TGTCUnavailableError` | 服务初始化或维护中 |
+
+## 路线图
+
+- [x] token：代币聚合查询
+- [ ] token/trending + token/hot：榜单
+- [ ] twitter：推特检测/舆情
+- [ ] track：交易流
+- [ ] market：信号流
+- [ ] wallet：钱包分析
+- [ ] translate：翻译
+
+## 文档
+
+完整接口文档见 [TGTC API Docs](https://github.com/TGTC-Suiyoung/tgtc-api-docs)。

tgtc_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tgtc-sdk"
+version = "0.1.0"
+description = "TGTC BSC 代币数据 API 的 Python 客户端（计费透明：每次返回剩余次数与扣次明细）"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = ["requests>=2.25"]
+
+[project.urls]
+Homepage = "https://www.tgtcbot.com"
+Documentation = "https://github.com/TGTC-Suiyoung/tgtc-api-docs"
+
+[tool.setuptools.packages.find]
+include = ["tgtc*"]

tgtc_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tgtc_sdk-0.1.0/tgtc/__init__.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""tgtc-sdk：TGTC 数据 API 的 Python 客户端。
+
+v0.1 覆盖 token（代币聚合）端点，计费透明（每次返回剩余次数与扣次明细）。
+"""
+
+from .client import CATEGORIES, DEFAULT_BASE_URL, TGTC
+from .errors import (TGTCError, TGTCAuthError, TGTCParamError, TGTCNotFoundError,
+                     TGTCQuotaError, TGTCUnavailableError)
+from .models import TokenResult
+
+__version__ = "0.1.0"
+__all__ = [
+    "TGTC", "TokenResult",
+    "TGTCError", "TGTCAuthError", "TGTCParamError", "TGTCNotFoundError",
+    "TGTCQuotaError", "TGTCUnavailableError",
+    "CATEGORIES", "DEFAULT_BASE_URL",
+]

tgtc_sdk-0.1.0/tgtc/client.py

@@ -0,0 +1,97 @@
+# -*- coding: utf-8 -*-
+"""TGTC 客户端：X-API-Key 鉴权 + token 端点封装。
+
+v0.1 只覆盖 token（代币聚合）端点；后续端点按同样模式追加方法即可。
+架构要点：
+  · 计费透明——每次调用返回剩余次数（remaining）与本次扣次（used）
+  · 错误映射——HTTP 状态码转明确异常（见 errors.py）
+  · 零侵入——SDK 只面向 /api/v1 产品接口，不直连任何数据源
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import requests
+
+from .errors import TGTCError, _map_error
+from .models import TokenResult
+
+DEFAULT_BASE_URL = "https://www.tgtcbot.com"
+TOKEN_PATH = "/api/v1/aggregation/token"
+
+# 可选类别（缺省由服务端按产品默认执行）
+CATEGORIES = ("basic", "structure", "holders", "security", "social", "traders")
+
+
+class TGTC:
+    """TGTC 数据 API 客户端。
+
+    用法::
+
+        from tgtc import TGTC
+        client = TGTC(api_key="你的 API Key")
+        res = client.token("0x...")
+        print(res.symbol, res.remaining)   # 符号 + 剩余次数
+    """
+
+    def __init__(self, api_key: Optional[str] = None,
+                 base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 30.0) -> None:
+        if not api_key:
+            raise TGTCError("缺少 API Key：请在个人中心创建 Key 后传入 api_key")
+        self._base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers["X-API-Key"] = api_key
+
+    # ── 内部请求管道 ──────────────────────────────────────────
+    def _post(self, path: str, payload: dict) -> tuple[dict, dict]:
+        """POST JSON 到产品接口；返回 (响应体, 计费明细)。异常已映射为明确类型。"""
+        try:
+            resp = self._session.post(self._base_url + path,
+                                      json=payload, timeout=self._timeout)
+        except requests.RequestException as e:
+            raise TGTCError(f"网络请求失败：{e}") from e
+        meta = {
+            "remaining": resp.headers.get("X-RateLimit-Remaining"),
+            "used": resp.headers.get("X-RateLimit-Used"),
+            "cache_hit": resp.headers.get("X-Cache") == "HIT",
+        }
+        try:
+            body = resp.json() if resp.content else {}
+        except ValueError:
+            body = {}
+        if resp.status_code >= 400:
+            raise _map_error(resp.status_code, str(body.get("detail") or body or resp.reason))
+        if not isinstance(body, dict):
+            raise TGTCError(f"响应格式异常：{body!r}")
+        return body, meta
+
+    # ── 产品端点 ─────────────────────────────────────────────
+    def token(self, ca: str, chain: str = "bsc",
+              categories: Optional[List[str]] = None,
+              fields: Optional[List[str]] = None) -> TokenResult:
+        """代币聚合查询（基本行情/持仓结构/安全审计/持有人/社交/聪明钱，按类别计费）。
+
+        参数:
+            ca: 合约地址（0x 开头 40 位十六进制）
+            chain: 链名，当前仅支持 bsc
+            categories: 可选类别子集；缺省由服务端按产品默认返回
+            fields: 可选字段裁剪（与 categories 互斥，二选一）
+
+        返回:
+            TokenResult：data 为完整响应体，remaining/used 为本次计费明细
+        """
+        payload = {"ca": ca, "chain": chain}
+        if categories:
+            payload["categories"] = [str(c) for c in categories]
+        if fields:
+            payload["fields"] = [str(f) for f in fields]
+        body, meta = self._post(TOKEN_PATH, payload)
+        return TokenResult(data=body,
+                            remaining=meta["remaining"],
+                            used=meta["used"],
+                            cache_hit=meta["cache_hit"],
+                            delay_sec=body.get("data_delay_sec"),
+                            degraded=body.get("degraded_sources"))

tgtc_sdk-0.1.0/tgtc/errors.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+"""tgtc-sdk 异常体系：错误码 → 明确异常，开发者不用猜响应结构。"""
+
+
+class TGTCError(Exception):
+    """SDK 基类异常。所有异常均继承此类的 message 为服务端返回的中文说明。"""
+
+
+class TGTCAuthError(TGTCError):
+    """鉴权失败（401）：API Key 缺失或无效。"""
+
+
+class TGTCParamError(TGTCError):
+    """请求参数错误（400/422）：CA 格式、链名或字段/类别组合不合法。"""
+
+
+class TGTCNotFoundError(TGTCError):
+    """数据不存在（404）：代币数据缺失或暂不可用。"""
+
+
+class TGTCQuotaError(TGTCError):
+    """调用次数不足（429）：本次调用所需扣次超过剩余次数。"""
+
+
+class TGTCUnavailableError(TGTCError):
+    """服务暂不可用（503）：服务初始化中或维护中。"""
+
+
+def _map_error(status_code: int, detail: str) -> TGTCError:
+    """HTTP 状态码 → 异常实例。未知状态码归入 TGTCError。"""
+    if status_code == 401:
+        return TGTCAuthError(detail)
+    if status_code in (400, 422):
+        return TGTCParamError(detail)
+    if status_code == 404:
+        return TGTCNotFoundError(detail)
+    if status_code == 429:
+        return TGTCQuotaError(detail)
+    if status_code == 503:
+        return TGTCUnavailableError(detail)
+    return TGTCError(f"服务返回异常状态码 {status_code}：{detail}")

tgtc_sdk-0.1.0/tgtc/models.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+"""tgtc-sdk 结构化返回。v0.1 覆盖 token 端点；其余端点复用 Result 基类扩展。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class Result:
+    """通用响应信封：数据 + 计费明细（来自响应头，与服务端扣次一致）。"""
+
+    data: Dict[str, Any]
+    remaining: Optional[int] = None      # 剩余次数（X-RateLimit-Remaining）
+    used: Optional[int] = None           # 本次扣次（X-RateLimit-Used）
+    cache_hit: bool = False              # 命中缓存 = 本次免费（X-Cache: HIT）
+    delay_sec: Optional[int] = None      # 数据新鲜度（data_delay_sec，0 = 实时）
+    degraded: Optional[list] = None      # 数据源降级标记（degraded_sources，空 = 全量正常）
+
+    def __post_init__(self) -> None:
+        self.remaining = int(self.remaining) if self.remaining is not None else None
+        self.used = int(self.used) if self.used is not None else None
+        self.delay_sec = int(self.delay_sec) if self.delay_sec is not None else None
+
+    @property
+    def ok(self) -> bool:
+        """请求是否成功（非异常返回即为成功）。"""
+        return True
+
+
+@dataclass
+class TokenResult(Result):
+    """token 端点结构化返回。常用字段提供 property 快捷访问，其余字段走 data 字典。"""
+
+    @property
+    def ca(self) -> Optional[str]:
+        return self.data.get("ca")
+
+    @property
+    def symbol(self) -> Optional[str]:
+        return self.data.get("symbol")
+
+    @property
+    def name(self) -> Optional[str]:
+        return self.data.get("name")
+
+    @property
+    def price(self) -> Optional[float]:
+        return self.data.get("price")
+
+    @property
+    def mcap(self) -> Optional[float]:
+        return self.data.get("mcap")
+
+    @property
+    def liquidity(self) -> Optional[float]:
+        return self.data.get("liquidity")
+
+    @property
+    def volume_24h(self) -> Optional[float]:
+        return self.data.get("volume_24h")
+
+    @property
+    def holder_count(self) -> Optional[int]:
+        return self.data.get("holder_count")
+
+    @property
+    def categories(self) -> list:
+        return list(self.data.get("categories") or [])
+
+    @property
+    def disclaimer(self) -> Optional[str]:
+        return self.data.get("disclaimer")

tgtc_sdk-0.1.0/tgtc_sdk.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: tgtc-sdk
+Version: 0.1.0
+Summary: TGTC BSC 代币数据 API 的 Python 客户端（计费透明：每次返回剩余次数与扣次明细）
+License-Expression: MIT
+Project-URL: Homepage, https://www.tgtcbot.com
+Project-URL: Documentation, https://github.com/TGTC-Suiyoung/tgtc-api-docs
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# tgtc-sdk (Python)
+
+TGTC 数据 API 的 Python 客户端。一行代码接入 BSC 代币数据：基本行情、持仓结构、安全审计、持有人、社交信息、聪明钱动向。
+
+**计费透明**：每次调用都会返回剩余次数与本次扣次明细，余额一眼可见。
+
+## 安装
+
+```bash
+pip install tgtc-sdk
+```
+
+需要先创建 API Key（TGTC Bot 个人中心 → 我的 API）。
+
+## 快速开始
+
+```python
+from tgtc import TGTC
+
+client = TGTC(api_key="你的 API Key")
+
+# 代币聚合查询（默认返回完整产品类别）
+res = client.token("0x...合约地址")
+
+print(res.symbol)          # 代币符号
+print(res.price)           # 当前价格
+print(res.remaining)       # 剩余调用次数
+print(res.used)            # 本次扣次
+```
+
+## 按类别/字段查询
+
+```python
+# 只要行情 + 安全审计，扣次更少
+res = client.token(ca, categories=["basic", "security"])
+
+# 精确字段裁剪（与 categories 二选一）
+res = client.token(ca, fields=["symbol", "price", "honeypot", "buy_tax"])
+```
+
+可选类别：`basic`（基本行情）/ `structure`（持仓结构）/ `holders`（持有人）/ `security`（安全审计）/ `social`（社交信息）/ `traders`（聪明钱动向）。
+
+## 计费明细
+
+| 字段 | 说明 |
+| --- | --- |
+| `remaining` | 剩余调用次数 |
+| `used` | 本次扣次（缓存命中为 0） |
+| `cache_hit` | 是否命中缓存（命中不扣次） |
+| `delay_sec` | 数据新鲜度（0 = 实时） |
+
+## 错误处理
+
+```python
+from tgtc import TGTCError, TGTCQuotaError, TGTCAuthError
+
+try:
+    res = client.token(ca)
+except TGTCAuthError:
+    print("API Key 无效")
+except TGTCQuotaError:
+    print("调用次数不足，请充值")
+except TGTCError as e:
+    print("请求失败：", e)
+```
+
+| 异常 | 触发条件 |
+| --- | --- |
+| `TGTCAuthError` | API Key 缺失或无效 |
+| `TGTCParamError` | 参数错误（CA 格式/类别组合） |
+| `TGTCNotFoundError` | 代币数据不存在 |
+| `TGTCQuotaError` | 调用次数不足 |
+| `TGTCUnavailableError` | 服务初始化或维护中 |
+
+## 路线图
+
+- [x] token：代币聚合查询
+- [ ] token/trending + token/hot：榜单
+- [ ] twitter：推特检测/舆情
+- [ ] track：交易流
+- [ ] market：信号流
+- [ ] wallet：钱包分析
+- [ ] translate：翻译
+
+## 文档
+
+完整接口文档见 [TGTC API Docs](https://github.com/TGTC-Suiyoung/tgtc-api-docs)。

tgtc_sdk-0.1.0/tgtc_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+tgtc/__init__.py
+tgtc/client.py
+tgtc/errors.py
+tgtc/models.py
+tgtc_sdk.egg-info/PKG-INFO
+tgtc_sdk.egg-info/SOURCES.txt
+tgtc_sdk.egg-info/dependency_links.txt
+tgtc_sdk.egg-info/requires.txt
+tgtc_sdk.egg-info/top_level.txt

tgtc_sdk-0.1.0/tgtc_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tgtc_sdk-0.1.0/tgtc_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25

tgtc_sdk-0.1.0/tgtc_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+tgtc