Metadata-Version: 2.4
Name: Tonviewer
Version: 1.1.9
Summary: Tonviewer is a Python library that allows you to fetch ( real-time balance of wallet , transactions , price ) data .
Author-email: AhMed <alexcrow221@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/DevZ44d/Tonviewer.git
Project-URL: Documentation, https://github.com/DevZ44d/Tonviewer
Project-URL: Source, https://github.com/DevZ44d/Tonviewer
Project-URL: Issues, https://github.com/DevZ44d/Tonviewer/issues
Project-URL: Community, https://t.me/PyCodz
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: colorama
Requires-Dist: tonsdk
Dynamic: license-file

<p align="center">
  <img align="center" width="350" src="https://github.com/user-attachments/assets/779356f9-84af-4247-83f0-32be2229c569" />
</p>


<p align="center">

<a href="https://pypi.org/project/Tonviewer/">
    <img src="https://img.shields.io/pypi/v/Tonviewer?color=blue&logo=pypi&logoColor=blue">
  </a>

  <a href="https://t.me/Pycodz">
    <img src="https://img.shields.io/badge/Telegram-Channel-blue.svg?logo=telegram">
  </a>
  
  <a href="https://t.me/DevZ44d" target="_blank">
    <img alt="Telegram Owner" src="https://img.shields.io/badge/Telegram-Owner-blue.svg?logo=telegram" />
  </a>
</p>

<p align="center">

  <a href="https://pepy.tech/projects/Tonviewer/">
    <img src="https://static.pepy.tech/personalized-badge/tonviewer?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=blue&left_text=downloads">
  </a>

  <a href="https://pepy.tech/projects/Tonviewer/">
    <img src="https://img.shields.io/badge/license-MIT-blue.svg">
  </a>
</p>

#### 🚀 Quick Start
```python
from Tonviewer import Wallet, HashTx
from Tonviewer.dollers import Dollers

def main():
    # Replace with your wallet address
    wallet = Wallet("wallet_address_here")

    # Get wallet info (balance + TON details)
    wallet.info()

    # Example: Get last 3 transactions (default limit = 1)
    wallet.transactions(limit=3)
    
    # get (Sent TON, Received TON, NFT Transfer, Transfer Token, Gas Relay) with limit
    _map = {
            "send":           "Sent TON",
            "sent":           "Sent TON",
            "send ton":       "Sent TON",
            "sent ton":       "Sent TON",
            "receive":        "Received TON",
            "received":       "Received TON",
            "receive ton":    "Received TON",
            "received ton":   "Received TON",
            "nft":            "NFT Transfer",
            "nft transfer":   "NFT Transfer",
            "transfer token": "Transfer Token",
            "jetton":         "Transfer Token",
            "token":          "Transfer Token",
            "gas relay":      "Gas Relay",
            "gas":            "Gas Relay",
            "relay":          "Gas Relay",
        }
    wallet.action(action="sent ton", limit=4)
    
    # Print Ton Price --> $
    Ton_price = Dollers()
    print(Ton_price._TON_USDT())

def get_transaction_by_hash():
    # Pass a transaction hash
    tx = HashTx(
        hashtx="b4566294bb20e0c22c57109f1128b903d4446d12710b3926b48c42cfc60dd097"
    )

    tx.get()  # Prints and returns dict

if __name__ == "__main__":
    main()
    get_transaction_by_hash()
```

### Installation and Development 🚀

- Via Git:
```shell
$ python -m pip install git+https://github.com/DevZ44d/Tonviewer.git
```

- Via PyPi:
```shell
$ python -m pip install --upgrade Tonviewer
```
### Tonviewer

- **_Tonviewer_** is a Python library that allows you to fetch real-time data.

- It enables users to view wallet **balances** and **live coin information** and get **transactions** of Wallet with ease, making it perfect for TON developers, analysts, and bot creators.

### ✨ Features

- 🧾  **Real-time** TON wallet balance fetching.
- 🔎 **Transaction by Hash** → Simply pass a transaction hash, it grabs the page via Selenium.
- 📄 **Parse Raw HTML** → Already have the page source? Pass it directly.
- 🟢 **Successful TX** → Extracts `Time`, `Action`, `From`, `To`, `Paid For`, `Price`, `Status`, `Comment`.
- 🔴 **Failed TX** → Extracts only the essentials (`Time`, `Action`, `From`, `To`, `Comment`, `Status`).
- ⚠️ **Invalid Hash** → Clean error message when the transaction address is not valid.
- 🧾 **Auto JSON Print** → Prints a formatted JSON result **and** returns it as a Python `dict`.


### Using in Terminal 🚀
```shell
Tonviewer -[OPTIONS] "[Wallet]"
```

### Usage 📚
```text
Tonviewer -[OPTIONS] "[FOR-OPTION]"

Options
    -w, --wallet                    Prints balance of wallet .
    -i, --info                      Get wallet info
    -t, --transactions              Get transactions of Wallet . 
    -l, --limit                     Number of times to get transactions .
    -a, --action                    Filter by action .
    -H, --hashtx                    Pass a transaction hash
    -h, --help                      Display help message .
    -v, --version                   Show Version Of Libarary and info .
```

### 🚀 Usage (_Class Terminal_)
- 🔹 Get wallet info:
```shell
Tonviewer -w "UQ..." -i
```

- 🔹 All transactions  (-t <wallet> [-l <limit>]):
```shell
Tonviewer -t "UQ..." -l 3
```

- 📦 Pass a transaction hash:
```shell
Tonviewer -H "d0..."
```

- 🔹 Action filter  (-w <wallet> -a <action> [-l <limit>]) .
```shell
Tonviewer -w "UQ..." -a "Sent TON" -l 5
```


### 📦 Example format response of `Wallet` Method:
```json
{
  "Balance": "0.70629411 TON ≈ 0.854 $",
  "Status": "active",
  "Last Activity": "2026-02-26 05:06:48 PM",
  "Name": "ddddi.t.me",
  "Icon": "https://cache.tonapi.io/imgproxy/wVVaalJBHOeiyU0Tf_bqX1QQjbvEl5oFOS8OvwIV5Do/rs:fill:200:200:1/g:no/aHR0cHM6Ly90Lm1lL2kvdXNlcnBpYy8zMjAvZGRkZGkuanBn.webp",
  "NFT Count": 351
}
```
### 📦 Example format response of `Transactions` Method ,
```json
{
  "transactions": [
    {
      "Hash": "e1d33799a2ab8160514aca0f3a757161d141ceeaee06bf27284b464ca9161124",
      "Time": "08 Mar 05:11:07 AM",
      "Action": "Received TON",
      "From": "UQAh_cfG6nAD8EazS3dED8mtQo3bmeGn6nMM8TAZ-9h50k1D",
      "To": "ddddi.t.me",
      "Price": "+0.772 TON ≈ 1.03790 $",
      "State": "Success",
      "Comment": "احبك",
      "Limit": "1"
    },
    {
      "Hash": "965e0cfc878ceb81fbbdddbf0b7c19dad5ec790ab1888e2a5ba72638224a5308",
      "Time": "07 Mar 01:25:09 AM",
      "Action": "NFT Transfer",
      "From": "UQAh_cfG6nAD8EazS3dED8mtQo3bmeGn6nMM8TAZ-9h50k1D",
      "To": "ddddi.t.me",
      "State": "Success",
      "Limit": "2"
    }
  ],
  "skipped": "Skipped 0 unsupported transactions"
}

```

### 📦 Example Output of `HashTx` Method (`NFT`,`BID`,`TON`,`AUCTION`) .

### ✅ Successful Transaction :
```json
{
  "actions": [
    {
      "Time": "2026-03-02 07:38:07 PM",
      "Action": "OK GASRELAY",
      "From": "TONAPI gas proxy",
      "To": "UQBAZ3qWaaoIC8Pq5ELnz2ofYoGN_E3mhzxhE-8EWTpMYgyc",
      "Price": "0.154 TON",
      "Comment": "Relay for gas",
      "Status": "SUCCESS"
    },
    {
      "Time": "2026-03-02 07:38:07 PM",
      "Action": "OK JETTONTRANSFER",
      "From": "UQBAZ3qWaaoIC8Pq5ELnz2ofYoGN_E3mhzxhE-8EWTpMYgyc",
      "To": "UQAh_cfG6nAD8EazS3dED8mtQo3bmeGn6nMM8TAZ-9h50k1D",
      "Price": "1.3 USD₮",
      "Status": "SUCCESS",
      "Comment": "Congratulations"
    }
  ]
}
```

### ❌ Failed Transaction:
```json
{
  "actions": [
    {
      "Time": "2024-01-28 08:37:32 PM",
      "Action": "FAILED AUCTION BID",
      "From": "UQAh_cfG6nAD8EazS3dED8mtQo3bmeGn6nMM8TAZ-9h50k1D",
      "To": "UQC7Ptcp7G1IhS2t__alZVlPQF7TtXk7XgsLf-wCBbHMboYF",
      "Price": "20.000 TON ≈ 24.96000 $",
      "Status": "FAILED"
    }
  ]
}
```

### ⚠️ Invalid Hash:
```json
{
  "Error": "This doesn't look like a valid transaction address. Where'd you get that?"
}
```

### 💬 Help & Support .
- Follow updates via the **[Telegram Channel](https://t.me/Pycodz)**.
- For general questions and help, join our **[Telegram chat](https://t.me/PyCodz_Chat)**.


