tonwise 0.1.0

Python SDK for TonWise — Trust & Safety API for the TON blockchain

TonWise Python SDK

Python SDK for TonWise — Trust & Safety API for the TON blockchain. Detect rug pulls, sybil clusters, contract spoofing, and drainer activity in 3 lines of code.

pip install tonwise

Quickstart

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:

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

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:

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:

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. 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

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

License

MIT — see 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