docs: expand coverage for checks, transfers, and stats

Author: ragnarok22

docs/examples.md

@@ -9,7 +9,7 @@ import os
 
 from cryptobot import CryptoBotClient
 from cryptobot.errors import CryptoBotError
-from cryptobot.models import Asset, ButtonName, Status
+from cryptobot.models import Asset, ButtonName, CheckStatus, Status
 
 client = CryptoBotClient(api_token=os.environ["CRYPTOBOT_API_TOKEN"])
 ```
@@ -218,6 +218,97 @@ listener = Listener(
 listener.listen()
 ```
 
+## Airdrop with Crypto Checks
+
+Create checks for a batch of users and track activations.
+
+```python
+from cryptobot.models import Asset
+
+
+def airdrop_checks(client: CryptoBotClient, user_ids: list, amount: float, asset: Asset = Asset.USDT):
+    """Create pinned checks for a list of users."""
+    results = []
+    for user_id in user_ids:
+        try:
+            check = client.create_check(
+                asset=asset,
+                amount=amount,
+                pin_to_user_id=user_id,
+            )
+            results.append({"user_id": user_id, "check_id": check.check_id, "url": check.bot_check_url})
+        except CryptoBotError as exc:
+            results.append({"user_id": user_id, "error": f"{exc.code}: {exc.name}"})
+    return results
+
+
+def check_activations(client: CryptoBotClient, asset: Asset = Asset.USDT):
+    """Report activated vs active checks."""
+    checks = client.get_checks(asset=asset)
+    activated = [c for c in checks if c.activated_at is not None]
+    pending = [c for c in checks if c.activated_at is None]
+    return {"activated": len(activated), "pending": len(pending), "total": len(checks)}
+
+
+# Usage
+recipients = [111111, 222222, 333333]
+drops = airdrop_checks(client, recipients, amount=0.5, asset=Asset.TON)
+for drop in drops:
+    print(drop)
+
+print("Status:", check_activations(client, Asset.TON))
+```
+
+## App Stats Dashboard
+
+Pull statistics and display a summary report.
+
+```python
+def stats_report(client: CryptoBotClient, start_at: str = None, end_at: str = None):
+    """Print a summary of app statistics."""
+    stats = client.get_stats(start_at=start_at, end_at=end_at)
+    print(f"Volume:           {stats.volume}")
+    print(f"Conversion:       {stats.conversion}")
+    print(f"Unique users:     {stats.unique_users_count}")
+    print(f"Invoices created: {stats.created_invoice_count}")
+    print(f"Invoices paid:    {stats.paid_invoice_count}")
+    print(f"Period:           {stats.start_at} to {stats.end_at}")
+
+
+# Last 7 days
+stats_report(client, start_at="2026-03-11T00:00:00Z", end_at="2026-03-18T00:00:00Z")
+```
+
+## Transfer Ledger
+
+Scan outgoing transfers and build a local ledger.
+
+```python
+from decimal import Decimal
+
+
+def transfer_ledger(client: CryptoBotClient, asset: Asset = None):
+    """Build a ledger of all outgoing transfers."""
+    ledger = []
+    for transfer in client.iter_transfers(asset=asset, page_size=200):
+        ledger.append({
+            "id": transfer.transfer_id,
+            "user_id": transfer.user_id,
+            "asset": transfer.asset.name,
+            "amount": transfer.amount,
+            "status": transfer.status.name,
+            "spend_id": transfer.spend_id,
+            "completed_at": transfer.completed_at,
+        })
+
+    total = sum(Decimal(str(t["amount"])) for t in ledger)
+    return {"entries": ledger, "total": str(total), "count": len(ledger)}
+
+
+result = transfer_ledger(client, asset=Asset.TON)
+print(f"Total transferred: {result['total']} ({result['count']} transfers)")
+```
+
 ## Testnet Smoke Check
 
 Quick validation script for non-production environments.

docs/index.md

@@ -1,16 +1,16 @@
 # Welcome to CryptoBot Python
 
 CryptoBot Python is an unofficial, friendly client library for the [Crypto Bot](https://pay.crypt.bot/) API.
-It provides typed models and synchronous/async clients for invoices, transfers, balances, exchange rates, and webhook handling.
+It provides typed models and synchronous/async clients for invoices, transfers, checks, balances, exchange rates, statistics, and webhook handling.
 
 ## Highlights
 
 - Synchronous API client built on `httpx`
 - Async API client built on `httpx`
-- Dataclass response models (`Invoice`, `Transfer`, `Balance`, `ExchangeRate`, `Currency`)
-- Enum safety for assets, statuses, and paid button names
+- Dataclass response models (`Invoice`, `Transfer`, `Check`, `Balance`, `ExchangeRate`, `Currency`, `AppStats`)
+- Enum safety for assets, statuses, check statuses, and paid button names
 - Mainnet/testnet support with configurable timeout and retries
-- Built-in invoice pagination helpers (`iter_invoice_pages`, `iter_invoices`)
+- Pagination iterators for invoices, transfers, and checks
 - FastAPI webhook listener with signature verification and optional replay protection
 - Structured API errors via `CryptoBotError` (`code`, `name`)
 

docs/troubleshooting.md

@@ -276,7 +276,7 @@ def smoke_test() -> bool:
 
 ## Getting Help
 
-1. [Crypto Bot API docs](https://help.crypt.bot/crypto-pay-api)
+1. [Crypto Pay API docs](https://help.send.tg/en/articles/10279948-crypto-pay-api)
 2. [Examples](examples)
 3. [Advanced Topics](advanced)
 4. [GitHub issues](https://github.com/ragnarok22/cryptobot_python/issues)

docs/usage.md

@@ -193,6 +193,76 @@ async with AsyncCryptoBotClient(api_token=os.environ["CRYPTOBOT_API_TOKEN"]) as
     )
 ```
 
+### Deleting an Invoice
+
+Delete an active invoice that is no longer needed:
+
+```python
+deleted = client.delete_invoice(invoice_id=12345)
+print("Deleted:", deleted)
+```
+
+### Retrieving Transfers
+
+List outgoing transfers with optional filters:
+
+```python
+# Get all transfers
+transfers = client.get_transfers()
+
+# Filter by asset or specific IDs
+transfers = client.get_transfers(asset=Asset.TON, count=50)
+transfers = client.get_transfers(transfer_ids=[100, 101, 102])
+
+# Look up by spend_id
+transfers = client.get_transfers(spend_id="reward_2026_02_10_user_123456789")
+```
+
+### Crypto Checks
+
+Create a check that any Telegram user (or a pinned user) can activate:
+
+```python
+from cryptobot.models import Asset
+
+# Create an open check
+check = client.create_check(asset=Asset.USDT, amount=1.0)
+print(check.check_id, check.bot_check_url)
+
+# Pin a check to a specific user
+check = client.create_check(asset=Asset.TON, amount=0.25, pin_to_user_id=123456789)
+```
+
+Retrieve and manage checks:
+
+```python
+# List active checks
+checks = client.get_checks(asset=Asset.USDT, status="active")
+
+# Get specific checks by ID
+checks = client.get_checks(check_ids=[10, 11, 12])
+
+# Delete a check
+client.delete_check(check_id=checks[0].check_id)
+```
+
+### App Statistics
+
+Get aggregated statistics for your app:
+
+```python
+stats = client.get_stats(
+    start_at="2026-01-01T00:00:00Z",
+    end_at="2026-03-01T00:00:00Z",
+)
+print(f"Volume: {stats.volume}")
+print(f"Unique users: {stats.unique_users_count}")
+print(f"Paid invoices: {stats.paid_invoice_count}")
+print(f"Conversion: {stats.conversion}")
+```
+
+Both `start_at` and `end_at` are optional ISO 8601 strings. When omitted, `start_at` defaults to 24 hours ago and `end_at` defaults to now.
+
 ## Environment Configuration
 
 ### Testnet vs Mainnet
@@ -352,7 +422,9 @@ Asset.TRX     # TRON
 
 ### Pagination with iterators
 
-When dealing with many invoices, prefer the built-in paginated iterator helpers:
+When dealing with many records, prefer the built-in paginated iterator helpers. They are available for invoices, transfers, and checks.
+
+**Invoices:**
 
 ```python
 # Iterate by page
@@ -364,7 +436,21 @@ for invoice in client.iter_invoices(asset=Asset.USDT, status=Status.paid, page_s
     print(invoice.invoice_id, invoice.status)
 ```
 
-Async pagination with equivalent helpers:
+**Transfers:**
+
+```python
+for transfer in client.iter_transfers(asset=Asset.TON, page_size=100):
+    print(transfer.transfer_id, transfer.amount)
+```
+
+**Checks:**
+
+```python
+for check in client.iter_checks(asset=Asset.USDT, status="active", page_size=100):
+    print(check.check_id, check.bot_check_url)
+```
+
+Async pagination works with `async for`:
 
 ```python
 import os
@@ -390,7 +476,7 @@ async with AsyncCryptoBotClient(api_token=os.environ["CRYPTOBOT_API_TOKEN"]) as
         print(invoice.invoice_id, invoice.status)
 ```
 
-Both iterator variants support `start_offset` and validate `page_size` in the same `1..1000` range.
+All iterator variants support `start_offset` and validate `page_size` in the `1..1000` range.
 
 ### Invoice Status Checking
 

docs/webhook_security.md

@@ -255,6 +255,6 @@ def test_valid_signature():
 
 ## References
 
-- [Crypto Bot API docs](https://help.crypt.bot/crypto-pay-api)
+- [Crypto Pay API docs](https://help.send.tg/en/articles/10279948-crypto-pay-api)
 - [OWASP Webhook Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Webhook_Security_Cheat_Sheet.html)
 - [FastAPI security docs](https://fastapi.tiangolo.com/tutorial/security/)