Metadata-Version: 2.5
Name: fragapi
Version: 0.7.0
Summary: Async & Sync API client for FragAPI
Project-URL: Homepage, https://github.com/apelsynca/fragapi-python
Project-URL: Examples, https://github.com/apelsynca/fragapi-python/tree/main/examples/
Author-email: apelsynca <apelsynca@proton.me>
Maintainer-email: apelsynca <apelsynca@proton.me>
License-Expression: MIT
License-File: LICENSE
Keywords: AsyncIO,FragAPI,Fragment,SDK,TON,blockchain,crypto
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.14.3
Requires-Dist: certifi>=2026.7
Requires-Dist: pydantic>=2.10
Description-Content-Type: text/markdown

# Getting Started

> This library is a python SDK for [FragAPI](https://fragapi.com)

## Installation

```bash theme={"theme":{"light":"github-light-default","dark":"dark-plus"}}
pip install fragapi
```

| Requirement | Version |
| ----------- | ------- |
| Python      | 3.10+   |
| aiohttp     | 3.14+   |
| pydantic    | 2.13+   |

Basic example:

```
import asyncio

from fragapi import FragAPI


async def main() -> None:
    fragapi = FragAPI(token="YOUR_TOKEN_FROM_PANEL")
    me = await fragapi.get_me()
    print(me.balance)  # Your balance


if __name__ == "__main__":
    asyncio.run(main())
```

## Methods

All methods are async and live on the `FragAPI` client.

| Area         | Methods                                                                                 |
| ------------ | --------------------------------------------------------------------------------------- |
| User         | `get_me`                                                                                |
| Stars        | `get_stars_recipient`, `buy_stars`, `buy_stars_bulk`, `get_buy_stars_bulk`, `wait_buy_stars_bulk` |
| Premium      | `get_premium_recipient`, `buy_premium`                                                  |
| Gifts        | `get_collection_gift_model_names`, `get_collection_gift_models`, `get_gift_model`       |
| Deposits     | `request_ton_deposit`, `request_ton_deposit_via_memo`, `list_deposits`                  |
| Transactions | `list_transactions`                                                                     |

Top up your balance by sending TON to the returned address, with either a base64 payload or a plain text memo:

```
deposit = await fragapi.request_ton_deposit(amount=1.5)
print(deposit.address, deposit.amount, deposit.payload)

deposit = await fragapi.request_ton_deposit_via_memo(amount=1.5)
print(deposit.address, deposit.amount, deposit.memo)
```

Bulk stars purchases return right away; wait for the results (or poll `get_buy_stars_bulk` yourself):

```
from fragapi import FragAPI

bulk = await fragapi.buy_stars_bulk(
    items=[
        FragAPI.BuyStars(username="synca", quantity=50),
        FragAPI.BuyStars(username="durov", quantity=100, show_sender=True),
    ]
)
bulk = await fragapi.wait_buy_stars_bulk(id=bulk.id)
for item in bulk.items:
    print(item.username, item.result or item.error)
```

List methods are paginated and return `.items` and `.pagination`:

```
from fragapi.types import TransactionsSorting

transactions = await fragapi.list_transactions(
    page=1, limit=10, sorting=[TransactionsSorting.amount_desc]
)
for transaction in transactions.items:
    print(transaction.amount, transaction.reason)
print(transactions.pagination.max_page)
```

Gift models can be sorted by floor price:

```
from fragapi.types import GiftModelsSorting

models = await fragapi.get_collection_gift_models(
    "plushpepe", sorting=[GiftModelsSorting.floor]
)
```
