Package: pytoncenter
PytoncenterIntroductionPytoncenter is aTON Centerclient with type hints that introduces advanced features such asaddress subscriptions,obtaining transaction flowssimilar to TON Viewer,parallel processing of multiple calls, androbust debug tools. Developers can use this package to create TON data analysis platforms, Dapp backends, and other services with enhanced functionality and efficiency.FeaturesEnhance your development workflow with Pytoncenter, offering:Rich Typing: Elevate your coding experience with comprehensive typing for improved code clarity and error detection.Field Validation & Transformation: Automate data integrity checks and format conversions supported byPydantic, ensuring data accuracy effortlessly.TVM Data Format Conversion: Seamlessly interact with TVM by automatically converting complex data structures like Addresses and Cells, based on C++ Python bindingTonpyConcurrency & Rate Limiting: Execute parallel requests smoothly while managing request rates efficiently to maintain optimal performance, thanks to theaiolimiterAdvanced Simplicity: Access sophisticated functionalities like transaction subscriptions, message parsing, and method result decoding with ease and simplicity.V2 & V3 API Support: Supporting bothV2andV3APIs, Pytoncenter provides a comprehensive range of features for your development needs.Simplify your development process with our feature-rich package designed for efficiency and ease of use.Quick Start1. Install the packageTo get started, install Pytoncenter using pip:pip3installpytoncenter2. Export the TONCENTER_API_KEYTo use the TON Center API, you need to obtain an API key from theTON Center. After obtaining the API key from@tonapibot, export it as an environment variable:exportTONCENTER_API_KEY=your_api_keyExample 1. Get Account Info (API V3)This example demonstrates how to obtain account information and jetton wallet balances using the TON Center API V3.frompytoncenterimportget_clientfrompytoncenter.v3.modelsimport*importasyncioasyncdefmain():client=get_client(version="v3",network="testnet")my_address="0QC8zFHM8LCMp9Xs--w3g9wmf7RwuDgJcQtV-oHZRSCqQXmw"account=awaitclient.get_account(GetAccountRequest(address=my_address))jetton_wallets=awaitclient.get_jetton_wallets(GetJettonWalletsRequest(owner_address=my_address,limit=10))masters=awaitclient.multicall({w.address:client.get_jetton_masters(w.jetton)forwinjetton_wallets})print("=== Account Info ===")print(" -","Symbol","TON","Balance:",account.balance/1e9)print("=== Jetton Wallets ===")forwalletinjetton_wallets:jetton=masters.get(wallet.address,None)ifjettonisNone:continuecontent=jetton.jetton_contentsymbol=content.symbolifcontentelse"unknown"decimals=(content.decimalsifcontentelse0)or9print(" -","Symbol",symbol,"Balance",wallet.balance/10**decimals)if__name__=="__main__":asyncio.run(main())Example 2. Decode Get Method Result (API V3)Here is an example for decoding get method by declaring the decoder and Type of the field explicitly. Decoder will decode the result based on the type of the field. If you are not sure about the type of the field, you can use AutoDecoder to decode the result.importasynciofrompprintimportpprintfrompytoncenterimportget_clientfrompytoncenter.decoderimportAutoDecoder,JettonDataDecoderfrompytoncenter.v3.modelsimport*asyncdefmain():client=get_client(version="v3",network="testnet")req=GetAccountRequest(address="kQBqSpvo4S87mX9tjHaG4zhYZeORhVhMapBJpnMZ64jhrP-A")account_info=awaitclient.get_account(req)# Check account status is activeassertaccount_info.status=="active","Account is not active"print("=====================================")req=RunGetMethodRequest(address="kQBqSpvo4S87mX9tjHaG4zhYZeORhVhMapBJpnMZ64jhrP-A",method="get_jetton_data",stack=[])result=awaitclient.run_get_method(req)print(result)print("===============Jetton Decoder======================")decoder=JettonDataDecoder()jetton_data=decoder.decode(result)pprint(jetton_data,width=120)print("===============Auto Decoder======================")decoder=AutoDecoder()jetton_data=decoder.decode(result)pprint(jetton_data,width=120)if__name__=="__main__":asyncio.run(main())You may get the following jetton data in the console:OrderedDict([('total_supply',5000000000),('mintable',True),('admin_address',EQC8zFHM8LCMp9Xs--w3g9wmf7RwuDgJcQtV-oHZRSCqQZ__),('jetton_content',<CellSlice[9]bits,[1]refs,[A21FCFE4756B6AD7A1E88E65483CCDAB3BBBD9F8AEF5F5060C5FC8A36737AC36]hash>),('jetton_wallet_code','b5ee9c7241022501000a......'),])If you use AutoDecoder, you may get the following result:OrderedDict([('idx_0',5000000000),('idx_1',-1),# Because auto decoder does not know the type, it will decode the result as number('idx_2',EQC8zFHM8LCMp9Xs--w3g9wmf7RwuDgJcQtV-oHZRSCqQZ__),# Address field will automatically decode to Address object('idx_3','b5ee9c7241022501000a......'),# Cell and Slice will apply b64decode to hex string('idx_4','b5ee9c7241022501000a......'),])However, for jetton data, there is a more efficient way to retreive the result by V3 API.client=get_client(version="v3",network="testnet")jettons=awaitclient.get_jetton_masters(GetJettonMastersRequest(address="kQBqSpvo4S87mX9tjHaG4zhYZeORhVhMapBJpnMZ64jhrP-A"))jetton=jettons[0]print("Total Supply: ",jetton.total_supply)print("Mintable: ",jetton.mintable)print("last transaction lt: ",jetton.last_transaction_lt)ifjetton.jetton_contentisnotNone:print("Jetton content - Symbol: ",jetton.jetton_content.symbol)print("Jetton content - Name: ",jetton.jetton_content.name)print("Jetton content - Decimals: ",jetton.jetton_content.decimals)print("Jetton content - Image: ",jetton.jetton_content.image)The output will be:TotalSupply:5000000000Mintable:True
lasttransactionlt:19051958000005Jettoncontent-Symbol:USDT
Jettoncontent-Name:USDT
Jettoncontent-Decimals:6Jettoncontent-Image:https://coinhere.io/wp-content/uploads/2020/08/Tether-USDT-icon-1.pngExample 3. Client Config Customization# you can customize the qps by passing the qps parameter, default is 9.5 if api key is provided, otherwise 1client=get_client(version="v2",network="mainnet",qps=7.77)# By default, the client will read the TONCENTER_API_KEY from the environment variable, you can pass the api_key parameter to customize the api keyclient=get_client(version="v2",network="mainnet",api_key="you-api-key")# By default, the client will use the default endpoint by network, you can pass the custom_endpoint parameter to customize the endpointclient=get_client(version="v3",network="mainnet",qps=3.14,custom_endpoint="https://api.toncenter.com/v3")Example 4. Get transaction traceimportasynciofrompytoncenterimportget_clientfrompytoncenter.v3.modelsimport*frompytoncenter.addressimportAddressfrompytoncenter.utilsimportformat_trace,create_address_mapping"""Take this transaction as example:https://testnet.tonviewer.com/transaction/84b7c9467a0a24e7a59a5e224e9ef8803563621f4710fe8536ae7803fe245d61The output transactions should be the whole trace of the transaction. The source transaction hash ishttps://testnet.tonviewer.com/transaction/dc40feab455e86fa0736508febed224891c965ef6cbf55f5ec309247e8d38664"""asyncdefmain():client=get_client(version="v3",network="testnet")trace=awaitclient.get_trace_alternative(GetTransactionTraceRequest(hash="84b7c9467a0a24e7a59a5e224e9ef8803563621f4710fe8536ae7803fe245d61",sort="asc"))addr_mapping=create_address_mapping({Address("0QApdUMEOUuHnBo-RSdbikkZZ3qWItZLdXjyff9lN_eS5Zib"):"Alan Wallet V4",Address("kQCQ1B7B7-CrvxjsqgYT90s7weLV-IJB2w08DBslDdrIXucv"):"Alan USD Jetton Wallet",Address("kQDO_0Z0SuVpqpaNE0dPxUiFCNDpdR4ODW9KQAwgQGwc5wiB"):"Oracle Jetton Wallet",Address("kQCpk40ub48fvx89vSUjOTRy0vOEEZ4crOPPfLEvg88q1EeH"):"Oracle",Address("kQA0FY6YIacA0MgDlKN_qMQuXVZqL3qStyyaNkVB-svHQqsJ"):"New Alarm",})output=format_trace(trace,address_mapping=addr_mapping)print(output)if__name__=="__main__":asyncio.run(main())Sample output:Examples (V3)Get Transaction TracesDecode Jetton Get Method ResultDecode Custom Get Method ResultMulticallSubscribe transactions of addressGet Account BalanceGet Previous TransactionGet Next TransactionWait message existsExamples (V2)Get Transaction TracesDecode Jetton Get Method ResultDecode Custom Get Method ResultExecute ParallellySubscribe transactions for addressExamples (Address)Address ParserUsecaseSubscription and handle on eventCustom Decoder With Singleton PatternCustom Message Payload ParserDevelopment GuidePlease refer to theDevelopment Guidefor more information on how to contribute to this project.