### Create Auction

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Creates an auction for a gift with a specified starting bid and duration. Supports predefined duration options in hours.

```APIDOC
## POST /createAuction

### Description
Create an auction for a gift with a known gift_id, starting bid, and duration.

### Method
POST

### Endpoint
/createAuction

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **gift_id** (integer) - Required - The ID of the gift to put up for auction.
- **starting_bid** (number) - Required - The initial bid amount for the auction.
- **authData** (string) - Required - Authentication token.
- **duration** (integer) - Optional - Duration of the auction in hours. Available options: `[1, 2, 3, 6, 12, 24]` (Default: 1).

### Request Example
```json
{
  "gift_id": 11223,
  "starting_bid": 10.0,
  "authData": "your_auth_token",
  "duration": 12
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the auction creation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Get User Info

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Retrieves user-specific information, including balances, memo details, and referrer information. Requires authentication.

```APIDOC
## GET /info

### Description
Returns a dictionary object containing your balances, memo, referrer, and other account information.

### Method
GET

### Endpoint
/info

### Parameters
#### Path Parameters
None

#### Query Parameters
- **authData** (string) - Required - Authentication token.

### Request Example
```http
GET /info?authData=your_auth_token
```

### Response
#### Success Response (200)
- **balances** (object) - User's asset balances.
- **memo** (string) - User's memo details.
- **referrer** (string) - Referrer information.

#### Response Example
```json
{
  "balances": {
    "TON": 100.5,
    "USDT": 50.0
  },
  "memo": "user_memo_string",
  "referrer": "referrer_username"
}
```
```

--------------------------------

### Get Giveaway Info

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Retrieves detailed information about a specific giveaway identified by its unique giveaway ID. Requires authentication.

```APIDOC
## GET /giveawayInfo

### Description
Retrieve giveaway information using a `giveaway_id`.

### Method
GET

### Endpoint
/giveawayInfo

### Parameters
#### Path Parameters
None

#### Query Parameters
- **giveaway_id** (string) - Required - The ID of the giveaway.
- **authData** (string) - Required - Authentication token.

### Request Example
```http
GET /giveawayInfo?giveaway_id=giveaway_def456&authData=your_auth_token
```

### Response
#### Success Response (200)
- **giveaway_details** (object) - An object containing all details of the giveaway.

#### Response Example
```json
{
  "giveaway_details": {
    "id": "giveaway_def456",
    "prize": "Rare Item",
    "end_time": "2023-12-31T23:59:59Z"
  }
}
```
```

--------------------------------

### Configure and Use Proxies for Requests

Source: https://context7.com/bleach-hub/tonnelmp/llms.txt

Demonstrates how to configure and utilize proxy servers for network requests made by TonnelMP functions. It shows setting up HTTP and HTTPS proxies, including authentication, and applying them to various functions like `getGifts`, `info`, and `filterStatsPretty`. The example also illustrates using multiple proxy configurations.

```python
from tonnelmp import getGifts, info, filterStatsPretty

authData = "your_auth_data_here"

# Configure proxy
proxies = {
    "http": "http://username:password@proxy-ip:port",
    "https": "http://username:password@proxy-ip:port"
}

# Use proxy with any function
gifts = getGifts(
    gift_name="toy bear",
    limit=5,
    proxies=proxies
)

account = info(
    authData=authData,
    proxies=proxies
)

stats = filterStatsPretty(
    authData=authData,
    proxies=proxies
)

# Multiple proxies
proxies_multi = {
    "http": "http://user1:pass1@ip1:port1",
    "https": "http://user2:pass2@ip2:port2"
}
```

--------------------------------

### Gift Purchasing and Auction Creation

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Functions for acquiring gifts and initiating auctions. `buyGift` allows users to purchase a gift by its ID and price, with optional parameters for receiver, anonymity, and price display. `createAuction` enables the creation of a timed auction for a gift, specifying the starting bid and duration.

```python
def buyGift(gift_id: int, price: int | float, authData: str, receiver: int, anonymously: bool = False, showPrice: bool = False) -> dict:
    # Buy a gift with known gift_id and price in TON.
    # Optional: receiver, anonymously, showPrice
    # Requires: gift_id, price, authData
    # Returns dict object with status. Either success or error.
    pass

def createAuction(gift_id: int, starting_bid: int | float, authData: str, duration: int) -> dict:
    # Create auction for the gift with known gift_id.
    # Requires: gift_id, starting_bid, authData, duration
    # Returns dict object with status. Either success or error.
    # Available options: duration (Default=1) - [1, 2, 3, 6, 12, 24] hours
    pass
```

--------------------------------

### Get Gift Price (Python)

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Retrieves gift information, specifically the raw price (before a 10% fee is added), for a given gift name and model. This example utilizes the Gift class and getGifts function from the tonnelmp library. Requires gift name, model, limit, and sort parameters.

```python
from tonnelmp import Gift, getGifts

gift = Gift(getGifts(gift_name="toy bear", model="wizard", limit=1, sort="price_asc")[0])
print(gift.price)
```

--------------------------------

### Get User Balances API

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Retrieves the user's balance information, including TON, USDT, and TONNEL balances, along with other account-related details.

```APIDOC
## GET /info

### Description
Retrieves the user's balance information, including TON, USDT, and TONNEL balances, along with other account-related details.

### Method
GET

### Endpoint
/info

### Parameters
#### Query Parameters
- **authData** (str) - Required - User's authentication data.

### Response
#### Success Response (200)
- **status** (str) - "success" indicating the request was successful.
- **balance** (float) - User's TON balance.
- **memo** (str) - User's memo.
- **transferGift** (bool) - Indicates if gift transfer is internal (false) or external (true).
- **usdtBalance** (float) - User's USDT balance.
- **tonnelBalance** (float) - User's TONNEL balance.
- **referrer** (int) - User's referrer Telegram ID.
- **photo_url** (str) - URL of the user's Telegram profile picture.
- **name** (str) - User's Telegram name.

#### Response Example
```json
{
	'status': 'success',
	'balance': 123.123123123,
	'memo': ' ... ',
	'transferGift': false,
	'usdtBalance': 123.123123123,
	'tonnelBalance': 123.123123123,
	'referrer': 123123123,
	'photo_url': ' ... ',
	'name': ' ... '
}
```
```

--------------------------------

### Get user account information and balances - tonnelmp

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Retrieve authenticated user's account details including TON, USDT, and TONNEL balances, Telegram profile information, and referrer data. Requires valid authentication credentials.

```python
from tonnelmp import info
print(info(authData="your_auth_data"))
```

--------------------------------

### Create Auction for Gift - Python

Source: https://context7.com/bleach-hub/tonnelmp/llms.txt

Create a timed auction for an unlisted gift with configurable starting bid and duration. Supports 1, 2, 3, 6, 12, or 24-hour durations. Returns success status with auction details or error message.

```python
from tonnelmp import myGifts, createAuction

authData = "your_auth_data_here"

# Get an unlisted gift
unlisted = myGifts(listed=False, authData=authData)

if unlisted:
    gift = unlisted[0]
    gift_id = gift['gift_id']

    # Create 24-hour auction with starting bid of 15 TON
    result = createAuction(
        gift_id=gift_id,
        starting_bid=15.0,
        authData=authData,
        duration=24  # Options: 1, 2, 3, 6, 12, 24 hours
    )

    if result.get('status') == 'success':
        print(f"Auction created for {gift['name']}")
        print(f"Starting bid: 15 TON, Duration: 24 hours")
    else:
        print(f"Error: {result.get('message')}")
```

--------------------------------

### Get Auctions API

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Retrieves a list of gifts currently up for auction. Supports filtering by name, model, backdrop, symbol, gift number, page, limit, price range, and asset, along with sorting options for auctions.

```APIDOC
## GET /auctions

### Description
Retrieves a list of gifts currently up for auction. Supports filtering by name, model, backdrop, symbol, gift number, page, limit, price range, and asset, along with sorting options for auctions.

### Method
GET

### Endpoint
/auctions

### Parameters
#### Query Parameters
- **gift_name** (str) - Optional - Filter by gift name.
- **model** (str) - Optional - Filter by gift model.
- **backdrop** (str) - Optional - Filter by backdrop name.
- **symbol** (str) - Optional - Filter by symbol name.
- **gift_num** (int) - Optional - Filter by Telegram gift number.
- **page** (int) - Optional - Page number for pagination.
- **limit** (int) - Optional - Maximum number of results per page (max 30).
- **sort** (str) - Optional - Sorting order for auctions. Available options: `"ending_soon", "latest", "highest_bid", "latest_bid"`.
- **price_range** (list | int) - Optional - Filter by price range.
- **asset** (str) - Optional - Filter by asset type. Available options: `"TON", "USDT", "TONNEL"`.
- **authData** (str) - Optional - Authentication data, may be required for certain auction details.

### Response
#### Success Response (200)
- **auctions** (list) - A list of auction objects, each containing details about the auction and the associated gift.

#### Response Example
(Response structure similar to getGifts, with added auction-specific fields like bid details, auction end time, etc.)
```

--------------------------------

### Gift Class Wrapper for Object-Oriented Access

Source: https://context7.com/bleach-hub/tonnelmp/llms.txt

Illustrates using the `Gift` class as a wrapper around gift data dictionaries for object-oriented access to gift properties. It shows how to retrieve gifts using `getGifts`, instantiate the `Gift` class with the returned dictionary, and access attributes like name, price, and ID. The example also includes converting the `Gift` object back to a dictionary.

```python
from tonnelmp import getGifts, Gift

# Get gifts
gifts = getGifts(gift_name="delicious cake", limit=5, sort="price_asc")

for gift_dict in gifts:
    # Wrap dictionary in Gift class
    gift = Gift(gift_dict)

    # Access properties
    print(f"Name: {gift.name}")
    print(f"Model: {gift.model}")
    print(f"Backdrop: {gift.backdrop}")
    print(f"Symbol: {gift.symbol}")
    print(f"Price: {gift.price} {gift.asset}")
    print(f"Gift ID: {gift.gift_id}")
    print(f"Gift Number: {gift.gift_num}")
    print(f"Status: {gift.status}")
    print(f"Export at: {gift.export_at}")
    print(f"Premarket: {gift.premarket}")

    # Get raw dictionary
    raw_data = gift.to_dict()

    print("-" * 50)
```

--------------------------------

### Retrieve Gift Data (Python)

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Fetches detailed data for a specific gift using its ID. If the gift ID starts with a '-', it also includes bundle data. Requires both gift_id and authData.

```python
def giftData(gift_id: int | str, authData: str) -> dict:
    # ... implementation details ...
    pass

# Example usage:
# giftData(gift_id='-123', authData=myAuthData)
```

--------------------------------

### Get My Gifts API

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Retrieves a list of the authenticated user's gifts, with an option to filter by listed or unlisted status.

```APIDOC
## GET /myGifts

### Description
Retrieves a list of the authenticated user's gifts, with an option to filter by listed or unlisted status.

### Method
GET

### Endpoint
/myGifts

### Parameters
#### Query Parameters
- **listed** (bool) - Optional - If `True`, returns gifts currently listed for sale. If `False`, returns unlisted gifts (Default: `True`).
- **page** (int) - Optional - Page number for pagination.
- **limit** (int) - Optional - Maximum number of results per page.
- **authData** (str) - Required - User's authentication data.

### Response
#### Success Response (200)
- **gifts** (list) - A list of gift objects belonging to the user.

#### Response Example
(Response structure similar to getGifts, but filtered to the authenticated user's collection.)
```

--------------------------------

### Get Sale History

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Retrieves a history of gift sales. This endpoint requires authentication and allows filtering by various criteria such as page, limit, type, gift name, model, backdrop, and sort order.

```APIDOC
## GET /saleHistory

### Description
Returns a list with dictionary objects containing gift details for sales history. Authentication is required.

### Method
GET

### Endpoint
/saleHistory

### Parameters
#### Path Parameters
None

#### Query Parameters
- **authData** (string) - Required - Authentication token.
- **page** (integer) - Optional - The page number for pagination.
- **limit** (integer) - Optional - The maximum number of items per page (default: not specified, max: 50).
- **type** (string) - Optional - The type of sale to filter by. Options: "ALL", "SALE", "INTERNAL_SALE", "BID" (Default: "ALL").
- **gift_name** (string) - Optional - Filter by gift name.
- **model** (string) - Optional - Filter by gift model.
- **backdrop** (string) - Optional - Filter by gift backdrop.
- **sort** (string) - Optional - The sorting order for the results. Options: "latest", "price_asc", "price_desc", "gift_id_asc", "gift_id_desc" (Default: "latest").

### Request Example
```http
GET /saleHistory?authData=your_auth_token&limit=10&sort=price_desc
```

### Response
#### Success Response (200)
- **gifts** (list) - A list of dictionaries, each containing gift details.

#### Response Example
```json
{
  "gifts": [
    {
      "gift_id": 12345,
      "name": "Example Gift",
      "price": 100,
      "seller": "seller_username"
    }
  ]
}
```
```

--------------------------------

### GET /api/pageGifts

Source: https://github.com/bleach-hub/tonnelmp/blob/main/references.txt

Retrieves a list of gifts with various filtering and sorting options. Supports pagination and user authentication for specific views.

```APIDOC
## GET /api/pageGifts

### Description
Retrieves a paginated list of gifts with support for filtering by price range, sorting by various criteria, and applying specific filters. User authentication is required for fetching 'my gifts' (both listed and unlisted).

### Method
GET

### Endpoint
/api/pageGifts

### Parameters
#### Query Parameters
- **filter** (string) - Optional - A JSON string representing the filter criteria. Defaults to a standard filter for available, non-refunded TON assets.
- **limit** (integer) - Optional - The number of gifts to return per page.
- **page** (integer) - Optional - The page number for pagination.
- **price_range** (string) - Optional - Specifies the minimum and maximum price for filtering gifts (e.g., '1-100').
- **ref** (integer) - Optional - Reference parameter, defaults to 0.
- **sort** (string) - Optional - A JSON string specifying the sorting order. See sorting options below.
- **user_auth** (string) - Optional - User authentication token. Required for fetching 'my gifts'.

#### Sorting Options (JSON string for the `sort` parameter):
- `"{\"price\":1,\"gift_id\":-1}"` - Price: low to high
- `"{\"price\":-1,\"gift_id\":-1}"` - Price: high to low
- `"{\"message_post_time\":-1,\"gift_id\":-1}"` - Latest
- `"{\"export_at\":1,\"gift_id\":-1}"` - Mint time
- `"{\"rarity\":-1,\"gift_id\":-1}"` - Rarity score
- `"{\"gift_num\":1,\"gift_id\":-1}"` - Gift ID ascending
- `"{\"gift_num\":-1,\"gift_id\":-1}"` - Gift ID descending
- `"{\"modelRarity\":1,\"gift_id\":-1}"` - Model rarity ascending
- `"{\"backdropRarity\":1,\"gift_id\":-1}"` - Backdrop rarity ascending
- `"{\"symbolRarity\":1,\"gift_id\":-1}"` - Symbol rarity ascending

#### Filter Examples (JSON string for the `filter` parameter):
- **Default Filter**: `"{\"price\":{\"$\\exists\":true},\"refunded\":{\"$\\ne\":true},\"buyer\":{\"$\\exists\":false},\"export_at\":{\"$\\exists\":true},\"asset\":\"TON\"}"`
- **Backdrop Filter**: `"{\"backdrop\":{\"$\\regex\":\"^Ranger Green \\\\(\"}}"` (Backdrop name must start with a capitalized letter)
- **Symbol Filter**: `"{\"symbol\":{\"$\\regex\":\"^Manta Ray \\\\(\"}}"` (Symbol name must start with a capitalized letter)
- **Gift Name Filter**: `"gift_name\":\"Astral Shard\"` (Gift name must be capitalized)
- **Gift Model Filter**: `"{\"model\":{\"$\\regex\":\"^Dark Soul \\\\(\"}}"` (Model name must start with a capitalized letter)

#### My Gifts - Listed (Requires `user_auth`):
- **sort**: `"{\"message_post_time\":-1,\"gift_id\":-1}"`
- **filter**: `"{\"seller\":<YOUR_SELLER_ID>,\"buyer\":{\"$\\exists\":false},\"$or\":[{\"price\":{\"$\\exists\":true}},{\"auction_id\":{\"$\\exists\":true}}]}`

#### My Gifts - Unlisted (Requires `user_auth`):
- **sort**: `"{\"gift_num\":1,\"gift_id\":-1}"`
- **filter**: `"{\"seller\":<YOUR_SELLER_ID>,\"buyer\":{\"$\\exists\":false},\"refunded\":{\"$\\ne\":true},\"price\":{\"$\\exists\":false}}"`

### Request Example
```
GET /api/pageGifts?limit=10&page=1&sort=%7B%22price%22%3A1%7D&filter=%7B%22asset%22%3A%22TON%22%7D
```

### Response
#### Success Response (200)
- **gifts** (array) - An array of gift objects.
  - **gift_id** (integer) - Unique identifier for the gift.
  - **gift_name** (string) - The name of the gift.
  - **model** (string) - The model of the gift.
  - **price** (number) - The price of the gift.
  - **seller** (integer) - The ID of the seller.
  - **buyer** (integer) - The ID of the buyer (if sold).
  - **backdrop** (string) - The backdrop associated with the gift.
  - **symbol** (string) - The symbol associated with the gift.
  - **rarity** (number) - The rarity score of the gift.
  - **message_post_time** (string) - Timestamp of the message post.
  - **export_at** (string) - Timestamp of export.
  - **asset** (string) - The asset type of the gift.
  - **refunded** (boolean) - Indicates if the gift has been refunded.
  - **auction_id** (integer) - The ID of the auction, if applicable.
  - **modelRarity** (number) - Rarity score based on the model.
  - **backdropRarity** (number) - Rarity score based on the backdrop.
  - **symbolRarity** (number) - Rarity score based on the symbol.
  - **gift_num** (integer) - A sequential number for the gift.

#### Response Example
```json
{
  "gifts": [
    {
      "gift_id": 12345,
      "gift_name": "Astral Shard",
      "model": "Dark Soul (1)",
      "price": 100.00,
      "seller": 6083232778,
      "buyer": null,
      "backdrop": "Ranger Green (1)",
      "symbol": "Manta Ray (1)",
      "rarity": 95.5,
      "message_post_time": "2023-10-27T10:00:00Z",
      "export_at": "2023-10-26T09:00:00Z",
      "asset": "TON",
      "refunded": false,
      "auction_id": null,
      "modelRarity": 0.8,
      "backdropRarity": 0.7,
      "symbolRarity": 0.9,
      "gift_num": 1
    }
  ],
  "totalGifts": 100,
  "currentPage": 1,
  "totalPages": 10
}
```
```

--------------------------------

### Get Gifts API

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Retrieves a list of gifts based on various filtering and sorting criteria. Supports filtering by name, model, backdrop, symbol, gift number, page, limit, price range, asset, and premarket status. It can also filter for Telegram Marketplace, mintable, and bundled gifts.

```APIDOC
## GET /gifts

### Description
Retrieves a list of gifts based on various filtering and sorting criteria.
Supports filtering by name, model, backdrop, symbol, gift number, page, limit, price range, asset, and premarket status. It can also filter for Telegram Marketplace, mintable, and bundled gifts.

### Method
GET

### Endpoint
/gifts

### Parameters
#### Query Parameters
- **gift_name** (str) - Optional - Filter by gift name.
- **model** (str) - Optional - Filter by gift model.
- **backdrop** (str) - Optional - Filter by backdrop name.
- **symbol** (str) - Optional - Filter by symbol name.
- **gift_num** (int) - Optional - Filter by Telegram gift number.
- **page** (int) - Optional - Page number for pagination.
- **limit** (int) - Optional - Maximum number of results per page (max 30).
- **sort** (str) - Optional - Sorting order. Available options: `"price_asc", "price_desc", "latest", "mint_time", "rarity", "gift_id_asc", "gift_id_desc"` (Default: "price_asc").
- **price_range** (list | int) - Optional - Filter by price range.
- **asset** (str) - Optional - Filter by asset type. Available options: `"TON", "USDT", "TONNEL"` (Default: "TON").
- **premarket** (bool) - Optional - Filter for premarket gifts (Default: `false`).
- **telegramMarketplace** (bool) - Optional - Filter for gifts on Telegram Marketplace.
- **mintable** (bool) - Optional - Filter for mintable gifts.
- **bundle** (bool) - Optional - Filter for bundled gifts.
- **authData** (str) - Required for certain operations, use with caution if not needed for retrieval.

### Response
#### Success Response (200)
- **gifts** (list) - A list of gift objects, each containing detailed gift information.

#### Response Example
```json
[
	{
	'gift_num': 35531,
	'customEmojiId': '5289634279544876303',
	'gift_id': 4840785,
	'name': 'Toy Bear',
	'model': 'Zebra (1.5%)',
	'asset': 'TON',
	'symbol': 'Rabbit (0.2%)',
	'backdrop': 'Burgundy (2%)',
	'availabilityIssued': 0,
	'availabilityTotal': 0,
	'backdropData': {},
	'message_in_channel': 0,
	'price': 12.9,
	'status': 'forsale',
	'limited': false,
	'auction': null,
	'export_at': '2025-05-28T12:25:01.000Z'
	}
]
```
```

--------------------------------

### Get Pretty Market Stats

Source: https://context7.com/bleach-hub/tonnelmp/llms.txt

Fetches and displays market statistics in a human-readable format. It extracts overall and specific gift floor prices, counts, and rarity information. This function relies on the `filterStatsPretty` function and assumes a successful API response structure.

```python
stats = filterStatsPretty(authData=authData)

if stats['status'] == 'success':
    data = stats['data']

    # Get floor price for specific gift
    toy_bear = data.get('toy bear', {})

    # Overall gift floor price
    gift_floor = toy_bear.get('data', {})
    print(f"Toy Bear floor price: {gift_floor['floorPrice']} TON")
    print(f"Total on market: {gift_floor['howMany']}")

    # Specific model floor price
    wizard_model = toy_bear.get('wizard', {})
    if wizard_model:
        print(f"\nWizard model floor: {wizard_model['floorPrice']} TON")
        print(f"Wizard rarity: {wizard_model['rarity']}%")
        print(f"Wizard count: {wizard_model['howMany']}")
```

--------------------------------

### List Gift for Sale (Python)

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Enables listing a gift for sale at a specified price. Requires the gift_id, the desired sale price, and authentication data (authData).

```python
from tonnelmp import listForSale

myAuthData = " ....... "
print(listForSale(gift_id=123, price=123, authData=myAuthData))
```

--------------------------------

### User Information Retrieval

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

The `info` function retrieves a dictionary containing various user-specific details such as balances, memo, and referrer information. This function requires authentication data to access the user's account details.

```python
def info(authData: str) -> dict:
    # Returns a dict object containing your balances, memo, referrer etc.
    # Requires: authData
    pass
```

--------------------------------

### Giveaway Participation

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Functions for interacting with giveaways. `giveawayInfo` retrieves information about a specific giveaway using its ID and authentication. `joinGiveaway` allows a user to join a giveaway, optionally specifying the number of tickets if it's a paid giveaway.

```python
def giveawayInfo(giveaway_id: str, authData: str) -> dict:
    # Retrieve giveaway info from giveaway_id
    # Requires: authData, giveaway_id
    pass

def joinGiveaway(giveaway_id: str, authData: str, ticketCount: int | None=None) -> dict:
    # Join giveaway with known giveaway_id
    # Ticketcount is optional argument. Required if giveaway is paid.
    # Requires: authData, giveaway_id
    pass
```

--------------------------------

### Join Marketplace Giveaway

Source: https://context7.com/bleach-hub/tonnelmp/llms.txt

Allows users to participate in marketplace giveaways. It first retrieves giveaway information such as name, participant count, prize, and end time, then enables joining either a free giveaway or a paid one using a specified number of tickets. This function requires `giveawayInfo` and `joinGiveaway` from the `tonnelmp` library.

```python
from tonnelmp import giveawayInfo, joinGiveaway

authData = "your_auth_data_here"
giveaway_id = "abc123xyz"

# Get giveaway information
info_result = giveawayInfo(
    giveaway_id=giveaway_id,
    authData=authData
)

print(f"Giveaway: {info_result.get('name')}")
print(f"Entries: {info_result.get('participantsCount')}")
print(f"Prize: {info_result.get('prize')}")
print(f"Ends: {info_result.get('endTime')}")

# Join free giveaway
result = joinGiveaway(
    giveaway_id=giveaway_id,
    authData=authData
)

if result.get('status') == 'success':
    print("Successfully joined giveaway!")
else:
    print(f"Error: {result.get('message')}")

# Join paid giveaway with tickets
result = joinGiveaway(
    giveaway_id=giveaway_id,
    authData=authData,
    ticketCount=5
)
```

--------------------------------

### Join Giveaway

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Allows a user to join a giveaway using its giveaway ID. An optional `ticketCount` parameter can be provided if the giveaway requires a paid entry.

```APIDOC
## POST /joinGiveaway

### Description
Join a giveaway using its `giveaway_id`. The `ticketCount` is optional and required only for paid giveaways.

### Method
POST

### Endpoint
/joinGiveaway

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **giveaway_id** (string) - Required - The ID of the giveaway to join.
- **authData** (string) - Required - Authentication token.
- **ticketCount** (integer) - Optional - The number of tickets to purchase for the giveaway (required for paid giveaways).

### Request Example
```json
{
  "giveaway_id": "giveaway_abc789",
  "authData": "your_auth_token",
  "ticketCount": 5
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of joining the giveaway.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Retrieve Account Information - Python

Source: https://context7.com/bleach-hub/tonnelmp/llms.txt

Fetch authenticated user account details including balances in TON, USDT, and TONNEL tokens, memo, transfer settings, referrer ID, and profile information. Returns account object with all user metadata and financial balances.

```python
from tonnelmp import info

authData = "your_auth_data_here"

account = info(authData=authData)

if account.get('status') == 'success':
    print(f"Name: {account['name']}")
    print(f"TON Balance: {account['balance']:.2f} TON")
    print(f"USDT Balance: {account['usdtBalance']:.2f} USDT")
    print(f"TONNEL Balance: {account['tonnelBalance']:.2f} TONNEL")
    print(f"Memo: {account['memo']}")
    print(f"Internal Transfer: {account['transferGift']}")
    print(f"Referrer ID: {account['referrer']}")

# Expected output format:
# {
#     'status': 'success',
#     'balance': 123.123123123,
#     'memo': '...',
#     'transferGift': False,
#     'usdtBalance': 123.123123123,
#     'tonnelBalance': 123.123123123,
#     'referrer': 123123123,
#     'photo_url': '...',
#     'name': '...'
# }
```

--------------------------------

### Retrieve gifts with filters - tonnelmp

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Fetch gift listings from the marketplace with optional filtering by name, model, backdrop, price range, and sorting options. Returns a list of gift dictionaries with detailed metadata including price, status, and availability information.

```python
from tonnelmp import getGifts
print(getGifts(gift_name="toy bear", limit=1))
```

--------------------------------

### Function signature - listForSale() - tonnelmp

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

List a gift from user's inventory for sale on the marketplace at specified price. Requires the tonnelmp gift_id (not Telegram gift_num). Returns status dictionary indicating success or error.

```python
listForSale(gift_id: int, price: int | float, authData: str) -> dict
```

--------------------------------

### Mint Gift

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Mints a gift to a specified TON wallet address. This operation incurs a cost of 0.3 TON and is currently untested.

```APIDOC
## POST /mintGift

### Description
Mints a gift to a specified TON wallet address. Minting costs 0.3 TON. (Not tested yet)

### Method
POST

### Endpoint
/mintGift

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **authData** (string) - Required - Authentication token.
- **wallet** (string) - Required - The TON wallet address to mint the gift to.
- **gift_id** (integer) - Required - The ID of the gift to mint.

### Request Example
```json
{
  "authData": "your_auth_token",
  "wallet": "recipient_ton_wallet_address",
  "gift_id": 54321
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success or failure of the minting operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Filtering by Gift Attributes

Source: https://github.com/bleach-hub/tonnelmp/blob/main/references.txt

Provides examples of JSON structures for filtering gifts based on specific attributes such as backdrop, symbol, gift name, and gift model. These filters use regular expressions for partial matching and require the first letter of the attribute to be capitalized.

```json
{
    "backdrop": {
        "$regex": "^Ranger Green \\("
    }
}
```

```json
{
    "backdrop": {
        "$regex": "^Backdrop name \\("
    }
}
```

```json
{
    "symbol": {
        "$regex": "^Manta Ray \\("
    }
}
```

```json
{
    "symbol": {
        "$regex": "^Symbol name \\("
    }
}
```

```json
{
    "gift_name": "Astral Shard"
}
```

```json
{
    "model": {
        "$regex": "^Dark Soul \\("
    }
}
```

```json
{
    "model": {
        "$regex": "^Model name \\("
    }
}
```

--------------------------------

### Buy Gift

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Purchases a gift using its gift ID and price in TON. Optional parameters allow specifying a receiver, anonymous purchase, and whether to show the price.

```APIDOC
## POST /buyGift

### Description
Buy a gift with a known gift_id and price in TON. The price is the raw price and does not need to be multiplied by 1.1. Both parameters can be retrieved from `getGifts()`.

### Method
POST

### Endpoint
/buyGift

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **gift_id** (integer) - Required - The ID of the gift to buy.
- **price** (number) - Required - The price of the gift in TON.
- **authData** (string) - Required - Authentication token.
- **receiver** (integer) - Optional - Telegram user ID of the recipient if sending to someone else.
- **anonymously** (boolean) - Optional - If true, the buyer's identity is not shown. Defaults to `false`.
- **showPrice** (boolean) - Optional - If true, the price is shown to the user. Defaults to `false`.

### Request Example
```json
{
  "gift_id": 98765,
  "price": 25.50,
  "authData": "your_auth_token",
  "receiver": 123456789,
  "anonymously": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates whether the purchase was successful or resulted in an error.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Get Specific Gift Data

Source: https://context7.com/bleach-hub/tonnelmp/llms.txt

Retrieves detailed information for a specific gift or bundle using its ID. It supports fetching data for individual gifts as well as bundle contents by handling both positive and negative `gift_id` values. This function requires authentication data and the `giftData` function from the `tonnelmp` library.

```python
from tonnelmp import giftData

authData = "your_auth_data_here"
gift_id = 4840785

# Get gift details
details = giftData(
    gift_id=gift_id,
    authData=authData
)

print(f"Gift: {details['name']}")
print(f"Model: {details['model']}")
print(f"Price: {details['price']} {details['asset']}")
print(f"Seller ID: {details['seller']}")
print(f"Status: {details['status']}")

# Get bundle data (for negative gift_ids)
bundle_id = "-123"
bundle = giftData(
    gift_id=bundle_id,
    authData=authData
)

if bundle.get('bundleData'):
    print(f"Bundle contains {len(bundle['bundleData'])} gifts")
    for item in bundle['bundleData']:
        print(f"  - {item['name']}")
```

--------------------------------

### Create and use Gift class wrapper - tonnelmp

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Instantiate a Gift object from gift dictionary data to access gift attributes as properties. Provides convenient dot-notation access to gift metadata like name, price, model, and status.

```python
from tonnelmp import Gift, getGifts
gift = Gift(getGifts(limit=1, sort="latest")[0])
print(gift.name, gift.gift_num, gift.gift_id, gift.price)
```

--------------------------------

### Retrieve Market Statistics and Floor Prices

Source: https://context7.com/bleach-hub/tonnelmp/llms.txt

Fetch comprehensive marketplace statistics including floor prices, trading volumes, and price trends for all gifts and models. Provides formatted statistical data for market analysis.

```python
from tonnelmp import filterStatsPretty

authData = "your_auth_data_here"
```

--------------------------------

### Retrieve User's Gifts - Python

Source: https://context7.com/bleach-hub/tonnelmp/llms.txt

Get all gifts owned by the authenticated user, supporting pagination with page and limit parameters. Can retrieve either listed gifts (for sale) or unlisted gifts in inventory. Returns a list of gift dictionaries containing gift details including limited edition status.

```python
from tonnelmp import myGifts

authData = "query_id=...&user=%7B%22id%22%3A..."

# Get all listed gifts
listed = myGifts(
    listed=True,
    page=1,
    limit=30,
    authData=authData
)

print(f"You have {len(listed)} gifts listed for sale")

# Get unlisted gifts in inventory
unlisted = myGifts(
    listed=False,
    page=1,
    limit=30,
    authData=authData
)

print(f"You have {len(unlisted)} unlisted gifts in inventory")

for gift in unlisted:
    print(f"Gift #{gift['gift_num']}: {gift['name']} ({gift['model']})")
    if gift.get('limited'):
        print(f"  ⚠️ Limited edition - needs unlocking (0.1 TON)")
```

--------------------------------

### Manage Gift Sales API

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Provides endpoints to list gifts for sale and cancel an existing sale.

```APIDOC
## POST /listForSale

### Description
Lists a gift for sale with a specified price.

### Method
POST

### Endpoint
/listForSale

### Parameters
#### Request Body
- **gift_id** (int) - Required - The Tonnel gift ID (not the Telegram gift number) of the gift to list.
- **price** (int | float) - Required - The price at which to list the gift.
- **authData** (str) - Required - User's authentication data.

### Response
#### Success Response (200)
- **status** (str) - "success" or "error" indicating the outcome of the operation.

#### Response Example
```json
{
	"status": "success"
}
```

## POST /cancelSale

### Description
Cancels the sale of a gift that is currently listed.

### Method
POST

### Endpoint
/cancelSale

### Parameters
#### Request Body
- **gift_id** (int) - Required - The Tonnel gift ID of the gift whose sale needs to be cancelled.
- **authData** (str) - Required - User's authentication data.

### Response
#### Success Response (200)
- **status** (str) - "success" or "error" indicating the outcome of the operation.

#### Response Example
```json
{
	"status": "success"
}
```
```

--------------------------------

### Buy Gift (Python)

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Facilitates the purchase of a gift. The final price includes a 10% fee added by Tonnel. Requires gift_id, price, and authentication data (authData). The printed output indicates the transaction status.

```python
from tonnelmp import buyGift

myAuthData = " ... your auth data here ... "
print(buyGift(gift_id=123123, price=123.12, authData=myAuthData))
```

--------------------------------

### Retrieve Sale and Gift Information

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Functions to retrieve sale history and detailed gift statistics. `saleHistory` provides a list of gift details and can be filtered by various parameters, optionally requiring authentication. `filterStats` offers a comprehensive overview of all gifts on the market, including floor price and rarity, without requiring specific gift IDs.

```python
def saleHistory(authData: str, page: int, limit: int, type: str, gift_name: str, model: str, backdrop: str, sort: str) -> list:
    # Returns a list with dict objects containing gifts details.
    # Required: authData
    # Available options: sort (Default="latest"), type (Default="ALL")
    # limit maximum = 50
    pass

def filterStats(authData: str) -> dict:
    # Returns ungrouped dictionary with all gifts and models splitted by underscore containing raw floorprice and count of the model (with rarity) on the market.
    # Requires: authData
    # Return format: {"status": "success/error", "data": {"Toy Bear_Wizard (1.5%)": {"floorprice": int, "howMany": int}}}
    pass
```

--------------------------------

### Make API requests with proxy support - tonnelmp

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Execute API calls through HTTP proxies for anonymity or load balancing. Supports single or multiple proxies by passing a dictionary with proxy URLs. Useful for high-volume requests or geolocation requirements.

```python
from tonnelmp import filterStatsPretty
auth="auth"
proxies= {"https": "http://username:password@ip:port"}
print(filterStatsPretty(authData=auth, proxies=proxies))
```

--------------------------------

### Unlock and Manage Gifts

Source: https://github.com/bleach-hub/tonnelmp/blob/main/README.md

Functions for unlocking listings, returning gifts, and minting new gifts. Unlocking a gift costs 0.1 TON and requires a gift ID and authentication data. Returning a gift transfers it back to the user's Telegram account. Minting a gift requires authentication, a wallet address, a gift ID, and costs 0.3 TON.

```python
def unlockListing(authData: str, gift_id: int) -> dict:
    # Unlock listing for a known gift_id (cost 0.1 TON)
    # Requires: authData, gift_id; 0.1 TON on the balance
    pass

def returnGift(gift_id: int, authData: str) -> dict:
    # Return gift from Tonnel Marketplace to your Telegram account.
    # Requires: gift_id, authData
    pass

def mintGift(authData: str, wallet: str, gift_id: int) -> dict:
    # Mints gift to specified TON wallet address.
    # Minting cost 0.3 TON
    # Requires: authData, wallet, gift_id; 0.3 TON on the balance
    pass
```