Metadata-Version: 2.5
Name: marketapp-api
Version: 1.0.1
Summary: Async Python library for Marketapp.ws API with automatic TON transaction execution
Author-email: S1qwy <S1qwy@internet.ru>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Classifier: Development Status :: 5 - Production/Stable
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: AsyncIO
Requires-Dist: curl_cffi>=0.7.4
Requires-Dist: tonutils>=0.4.0
Requires-Dist: ton-core>=0.1.0
Requires-Dist: pydantic>=2.0
Import-Name: MarketappAPI

<h1 align="center">Marketapp API Python SDK</h1>

<p align="center">
  <strong>Async Python library for Marketapp.ws automation</strong><br>
  <strong>v1.1.0 — Pydantic V2 | Auto-Pay Integration | Full Marketplace & Rent</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/marketapp-api/"><img src="https://img.shields.io/pypi/v/marketapp-api.svg?style=flat-square" alt="PyPI"></a>
  <a href="https://pypi.org/project/marketapp-api/"><img src="https://img.shields.io/badge/Python-3.9+-blue?style=flat-square" alt="Python Versions"></a>
  <a href="https://pepy.tech/projects/marketapp-api/"><img src="https://static.pepy.tech/personalized-badge/marketapp-api?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=BLUE&left_text=downloads" alt="Downloads"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" alt="License"></a>
</p>

---

## Features

- **Async-first** — Fast and modern async/await support via `MarketappClient`.
- **Pydantic Models** — All API requests and responses are strictly typed and validated using Pydantic V2.
- **Auto-Pay Engine** — Built-in `tonutils` integration! Automatically sign and broadcast TON transactions for purchases, listings, and rent without manual BOC handling.
- **NFT Marketplace** — Buy, sell, cancel sales, and change prices. Support for listing directly to Fragment.
- **Rent System** — Full API coverage for renting out and renting Usernames, Anonymous Numbers, and Gifts. 
- **Fragment Operations** — Buy Telegram Stars, Premium, run Giveaways, and top up Ads/Telegram balances directly via Marketapp API.
- **TonConnect Bridge** — Connect your rented NFTs to Fragment via API.
- **Graceful Error Handling** — Beautiful exceptions for API validations, network issues, and blockchain seqno/balance errors.

---

## Installation

```bash
pip install marketapp-api
```

**Requirements:**
- Python 3.9+
- Marketapp API Token (Get it at [Marketapp API Token](https://marketapp.org/api-token))
- *(Optional for Auto-Pay)* TON wallet seed phrase (12/18/24 words) and a Tonconsole/Toncenter API key.

---

## Quick Start

### Read-Only Mode (No Wallet)
If you only need to parse data or generate raw transaction payloads:

```python
import asyncio
from MarketappAPI import MarketappClient

async def main():
    async with MarketappClient(api_token="your_marketapp_token") as client:
        # Fetch collections
        collections = await client.list_collections()
        print(f"Found {len(collections)} collections.")
        
        # Get NFTs on sale
        gifts = await client.get_gifts_on_sale(limit=5)
        for item in gifts.items:
            print(f"{item.name} is selling for {item.min_bid} {item.currency}")

asyncio.run(main())
```

### Auto-Pay Mode (With Wallet)
The library can automatically sign and execute transactions when a wallet seed is provided:

```python
import asyncio
from MarketappAPI import MarketappClient
from MarketappAPI.types.models import BuyNFTBody, SaleNFTData

async def main():
    client = MarketappClient(
        api_token="your_marketapp_token",
        seed="word1 word2 ... word24",
        api_key="YOUR_TONAPI_KEY",
        wallet_version="V5R1" # or "V4R2"
    )
    
    # 1. Buy an NFT (Auto-pays and waits for blockchain confirmation)
    buy_body = BuyNFTBody(data=[
        SaleNFTData(nft_address="EQ...nft_address", price=5.5)
    ])
    
    print("Sending transaction...")
    result = await client.buy_nft(buy_body)
    
    if result.confirmed:
        print(f"Success! TX Hash: {result.tx_hash}")
        print(f"Balance after: {result.balance_after} GRAM")

asyncio.run(main())
```

---

## API Overview

### Collections & Info
| Method | Description |
|--------|-------------|
| `list_collections()` | List all supported collections |
| `gift_collections()` | List Gift collections |
| `get_collection_attributes()` | Get all attributes and floors for a collection |
| `nft_info()` | Detailed info and status for a specific NFT |

### NFT Marketplace
| Method | Description |
|--------|-------------|
| `put_up_for_sale()` | List an NFT for sale |
| `fragment_sale()` | List an NFT visible on Fragment |
| `fragment_auction()` | Start a Fragment auction |
| `change_price()` | Update sale price |
| `cancel_sale()` | Cancel active sale |
| `buy_nft()` | Buy an NFT |
| `collection_nfts()` | Browse NFTs on sale by collection |
| `nfts_by_owner()` | Get NFTs owned by address |

### Rent System
| Method | Description |
|--------|-------------|
| `get_gifts_available_for_rent()` | Browse Gifts for rent |
| `get_usernames_available_for_rent()`| Browse Usernames for rent |
| `get_numbers_available_for_rent()` | Browse Numbers for rent |
| `rent_out_gifts/usernames/numbers()`| List your items for rent |
| `update_*_settings()` | Update rent duration/prices |
| `rent_nft()` | Pay to rent an item |
| `extend_rent_nft()` | Extend current rental duration |
| `cancel_rent()` | Cancel rent listing |
| `connect_tonconnect()` | Link rented NFT to Fragment via TonConnect |
| `get_login_code()` | Fetch TG login code for rented +888 number |

### Fragment & Stars
| Method | Description |
|--------|-------------|
| `get_stars_prices()` | Get Telegram Stars pricing |
| `buy_stars()` | Buy Stars for a user |
| `buy_stars_giveaway()` | Run a Stars giveaway |
| `buy_premium()` | Buy Telegram Premium |
| `ads_topup()` | Top up Fragment Ads account |
| `telegram_topup()` | Top up Telegram bot/account balance |

*All actions that mutate state (`buy_nft`, `put_up_for_sale`, `buy_stars`, etc.) accept an optional `auto_pay=False` parameter if you want to receive the raw `SendTxSchema` payload instead of executing the transaction.*

---

## Exceptions

All exceptions inherit from `MarketappError`:

| Exception | Description |
|-----------|-------------|
| `ConfigurationError` | Invalid client configuration (e.g., missing API token) |
| `APIError` | General API or network error (e.g., 502 Bad Gateway) |
| `ValidationError` | HTTP 422 - Invalid request body or parameters |
| `TransactionError` | TON transaction failed to build or broadcast |
| `WalletError` | Insufficient balance or failure fetching wallet state |
| `ConfirmationTimeout` | Transaction sent but not confirmed in time |
| `SeqnoError` | Failed to fetch seqno from the blockchain |

---

## Support & License

**Issues:** [GitHub Issues](https://github.com/s1qwy/marketapp-api/issues)

**Support the Project:**

<p align="center">
  <a href="https://app.tonkeeper.com/transfer/UQBsyxZvyQxDwAeOxoaWwO2HJoAmCKUoJlS_OpLzWHD9i2Xj">
    <img src="https://img.shields.io/badge/Donate-GRAM-0098ea?style=for-the-badge&logo=ton&logoColor=white" alt="Donate GRAM">
  </a>
</p>

<p align="center">
  <code>UQBsyxZvyQxDwAeOxoaWwO2HJoAmCKUoJlS_OpLzWHD9i2Xj</code>
</p>

**License:** MIT — free for commercial and personal use.

---

<p align="center">
  <a href="https://github.com/s1qwy/marketapp-api">GitHub</a>
</p>
