Marketapp API Python SDK

Async Python library for Marketapp.ws automation
v1.1.0 — Pydantic V2 | Auto-Pay Integration | Full Marketplace & Rent

---

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

pip install marketapp-api

Requirements:

• Python 3.9+
• Marketapp API Token (Get it at Marketapp 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:

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:

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

Support the Project:

UQBsyxZvyQxDwAeOxoaWwO2HJoAmCKUoJlS_OpLzWHD9i2Xj

License: MIT — free for commercial and personal use.

---

GitHub