Metadata-Version: 2.4
Name: tonwise
Version: 0.1.0
Summary: Python SDK for TonWise — Trust & Safety API for the TON blockchain
Project-URL: Homepage, https://tonguard.app
Project-URL: Documentation, https://tonguard.app/docs
Project-URL: Repository, https://github.com/tonwise/tonwise-python
Project-URL: Issues, https://github.com/tonwise/tonwise-python/issues
Project-URL: Pricing & API key, https://tonguard.app/pricing
Author-email: TonWise Team <support@tonguard.app>
License: MIT
License-File: LICENSE
Keywords: anti-scam,blockchain,fraud-detection,rug-pull,security,sybil,telegram,ton
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: aiohttp>=3.9
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: aioresponses>=0.7.6; extra == 'dev'
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: responses>=0.24; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

# TonWise Python SDK

[![PyPI](https://img.shields.io/pypi/v/tonwise.svg)](https://pypi.org/project/tonwise/)
[![Python](https://img.shields.io/pypi/pyversions/tonwise.svg)](https://pypi.org/project/tonwise/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Python SDK for [TonWise](https://tonguard.app) — Trust & Safety API for the TON blockchain.
Detect rug pulls, sybil clusters, contract spoofing, and drainer activity in 3 lines of code.

```bash
pip install tonwise
```

## Quickstart

```python
from tonwise import TonWiseClient

with TonWiseClient(api_key="tg_live_xxx") as client:
    result = client.scan("EQA1234567...")
    print(f"Safe: {result.is_safe}, Dump probability: {result.dump_probability}%")
```

## Async usage

For AI agents, trading bots, and FastAPI / aiohttp services:

```python
import asyncio
from tonwise import AsyncTonWiseClient

async def main():
    async with AsyncTonWiseClient(api_key="tg_live_xxx") as client:
        result = await client.scan("EQA1234567...")
        print(f"Safe: {result.is_safe}, Sybils: {result.sybil_clusters}")

asyncio.run(main())
```

## Webhooks

Subscribe to real-time security events. Supported event types:

- `scam` — confirmed scam contract
- `spoof` — confusable / invisible-character token spoofing
- `dump_alert` — high dump probability (>70%)
- `sybil_cluster` — coordinated wallet activity
- `pump_warning` — pump-and-dump pattern detected
- `manifest_forgery` — fake jetton metadata
- `w5_batch_drain` — drainer activity via W5 batch transfers
- `*` — subscribe to all events

```python
client.register_webhook(
    url="https://your-app.com/tonwise-callback",
    events=["scam", "dump_alert"],
)

# List your webhooks
hooks = client.list_webhooks()

# Disable a webhook
client.delete_webhook(webhook_id=42)
```

### Verify HMAC-SHA256 signatures

Every webhook payload is signed with the secret returned at registration:

```python
import hmac, hashlib

def verify_signature(secret: str, body: bytes, signature_header: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(received, expected)
```

## Error handling

The SDK raises typed exceptions so you can branch cleanly:

```python
from tonwise import TonWiseClient, AuthError, RateLimitError, APIError

try:
    result = client.scan("EQA1234...")
except AuthError:
    # 401 — bad or revoked API key
    ...
except RateLimitError as e:
    # 429 — wait e.retry_after seconds and retry
    time.sleep(e.retry_after)
except APIError as e:
    # other 4xx / 5xx — inspect e.status_code and e.body
    ...
```

## Features

- Sync (`requests`) and async (`aiohttp`) clients — both first-class
- Webhook management: register / list / delete
- Type hints + Pydantic v2 response models
- Rate-limit aware: `RateLimitError.retry_after` exposes the server's hint
- Custom `base_url` for staging environments

## Get an API key

Visit [tonguard.app/pricing](https://tonguard.app/pricing).
The free tier gives **1 000 calls/day** — no credit card required.

| Tier        | Calls/day | Webhooks | Price       |
| ----------- | --------- | -------- | ----------- |
| Free        | 1 000     | 1        | $0          |
| Pro         | 50 000    | 5        | $99/month   |
| Business    | 250 000   | 10       | $499/month  |
| Enterprise  | unlimited | 10+      | custom      |

## Development

```bash
git clone https://github.com/tonwise/tonwise-python
cd tonwise-python
pip install -e ".[dev]"
pytest
```

## License

MIT — see [LICENSE](LICENSE).

## Links

- 🌐 Website: <https://tonguard.app>
- 📖 API docs: <https://tonguard.app/docs>
- 📡 Threat Intel channel: <https://t.me/tonwise_intel>
- 🐛 Issues: <https://github.com/tonwise/tonwise-python/issues>
