PHPackages amashukov/toncenter-client-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. amashukov/toncenter-client-php ActiveLibrary[HTTP & Networking](/categories/http) amashukov/toncenter-client-php ============================== Typed toncenter v2 HTTP client for The Open Network — {ok, result} envelope unwrapping, retry-aware via any PSR-18 client, typed Value Objects (masterchain info, account state, run-get-method stack reader, transactions). Pluggable wallet RPC adapter. v0.1.0(2w ago)0205↑92.3%1MITPHPPHP >=8.3CI passing Since May 24Pushed 2w agoCompare [ Source](https://github.com/AndreyMashukov/toncenter-client-php)[ Packagist](https://packagist.org/packages/amashukov/toncenter-client-php)[ RSS](/packages/amashukov-toncenter-client-php/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (11)Versions (2)Used By (1) amashukov/toncenter-client-php ============================== [](#amashukovtoncenter-client-php) Typed PHP toncenter v2 client for The Open Network — PSR-18 transport, `{ok, result}` envelope unwrapping, retry-aware, typed Value Objects. [![CI](https://camo.githubusercontent.com/e31e1fe2e5b30c5beef0e66930f57b82f79353693acbe5ea804cd9c8fe3b8f10/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f416e647265794d617368756b6f762f746f6e63656e7465722d636c69656e742d7068702f63692e796d6c3f6272616e63683d6d61696e266c6162656c3d4349)](https://github.com/AndreyMashukov/toncenter-client-php/actions)[![PHPStan L9](https://camo.githubusercontent.com/0073aec21d9f7f44ed91f0e4e04c0e4833d8bc36073193ebf893081b6029ae0f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f416e647265794d617368756b6f762f746f6e63656e7465722d636c69656e742d7068702f7374616e2e796d6c3f6272616e63683d6d61696e266c6162656c3d5048505374616e2532304c39)](https://github.com/AndreyMashukov/toncenter-client-php/actions)[![Latest Version](https://camo.githubusercontent.com/6334a927ca0586e1e1ad3a702f2e697ee22390c445ef6f625f83dd07ba801c24/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616d617368756b6f762f746f6e63656e7465722d636c69656e742d706870)](https://packagist.org/packages/amashukov/toncenter-client-php)[![Downloads](https://camo.githubusercontent.com/8362c20a28872ab1e3740b6816f363b7bffb7b1a2018cc0cbbb933df9ac99ece/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616d617368756b6f762f746f6e63656e7465722d636c69656e742d706870)](https://packagist.org/packages/amashukov/toncenter-client-php)[![PHP](https://camo.githubusercontent.com/f85d984b0e6b5056be7a72111a10567429379f282d9936b65be65b51a89ca1be/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f616d617368756b6f762f746f6e63656e7465722d636c69656e742d7068702f706870)](https://packagist.org/packages/amashukov/toncenter-client-php)[![License](https://camo.githubusercontent.com/2888c4ae204df58886a32ec290a3cf6894fd6ef2760e1e78de0d7e213d0c860b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616d617368756b6f762f746f6e63656e7465722d636c69656e742d706870)](LICENSE)[![Stars](https://camo.githubusercontent.com/27593478b0436b07ee33d8c543e07915ba12670815da71a3e790d2e60e0e0bdb/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f416e647265794d617368756b6f762f746f6e63656e7465722d636c69656e742d7068703f7374796c653d736f6369616c)](https://github.com/AndreyMashukov/toncenter-client-php) A **typed PHP client for the [toncenter v2 HTTP API](https://toncenter.com/api/v2/)** on [The Open Network (TON)](https://ton.org). It speaks any [PSR-18](https://www.php-fig.org/psr/psr-18/) HTTP client, unwraps the `{ok, result}` envelope into typed exceptions in one place, and returns Value Objects instead of loose arrays — masterchain info, account state, a run-get-method stack reader, and typed transactions. TON balances exceed `PHP_INT_MAX` past ~9,223 TON, so every nano-TON value comes back as a decimal string, never a lossy float. Includes `ToncenterWalletRpc`, a drop-in `WalletRpcInterface` adapter for [`ton-wallet-php`](https://github.com/AndreyMashukov/ton-wallet-php). Features -------- [](#features) - **`{ok, result}` envelope unwrapping in one place** — a non-`200` status, `ok: false`, or a missing `result` becomes a `TonRpcException`; business code never touches the envelope. - **Typed Value Objects** — masterchain info, account state, run-get-method stack reader, and a five-state transaction status (`Pending`, `Success`, `ComputePhaseFailed`, `ActionPhaseFailed`, `Aborted`) derived from the TVM compute / action phases. - **Decimal-string big numbers** — balances and gas values are returned as decimal strings, safe past `PHP_INT_MAX`. - **Transport-agnostic** — bring your own PSR-18 client and PSR-17 factories. The retry policy and the `X-Api-Key` rate-limit header are middleware concerns, not baked into the client. - **542 / 429 retry decider** — toncenter emits transient `542` ("no workers available") and `429`; the recommended retry status set is documented so a retry middleware can target exactly those. - **Wallet RPC adapter** — `ToncenterWalletRpc` implements `Amashukov\TonWallet\WalletRpcInterface` (`getSeqno` + `sendBoc`) so a [`ton-wallet-php`](https://github.com/AndreyMashukov/ton-wallet-php) wallet broadcasts through toncenter with no glue code. Why amashukov/toncenter-client-php ---------------------------------- [](#why-amashukovtoncenter-client-php) The common alternative is hand-rolled Guzzle calls scattered across a service layer, each re-implementing envelope checks, bigint parsing, and 542/429 retry logic. This package centralizes all of that behind a typed surface with PHPStan level 9, returns Value Objects instead of arrays, and stays transport-agnostic so retry / API-key concerns live in your PSR-18 pipeline. Installation ------------ [](#installation) ``` composer require amashukov/toncenter-client-php ``` Usage ----- [](#usage) Any PSR-18 client and PSR-17 factory pair works. The example below wires [`amashukov/http-client-php`](https://github.com/AndreyMashukov/http-client-php)(cURL transport + retry / header-injection middleware) with [`nyholm/psr7`](https://github.com/Nyholm/psr7) for the PSR-7 messages: ``` use Amashukov\HttpClient\CurlClient; use Amashukov\HttpClient\Middleware\HeaderInjectionMiddleware; use Amashukov\HttpClient\Middleware\RetryMiddleware; use Amashukov\HttpClient\Pipeline; use Amashukov\Toncenter\ToncenterClient; use Nyholm\Psr7\Factory\Psr17Factory; $psr17 = new Psr17Factory(); $http = new Pipeline( new CurlClient($psr17, $psr17, timeoutSeconds: 60), [ // X-Api-Key lifts the rate limit from 1 RPS to 10 RPS (optional). new HeaderInjectionMiddleware(['X-Api-Key' => $apiKey]), // Toncenter emits transient 542 ("no workers available") + 429; retry those. new RetryMiddleware(maxAttempts: 3, retryStatusCodes: [429, 500, 502, 503, 504, 542]), ], ); $client = new ToncenterClient($http, $psr17, $psr17); $info = $client->getMasterchainInfo(); // TonMasterchainInfo $balance = $client->getBalance('EQ...'); // decimal-string nano-TON $account = $client->getAddressInformation('EQ...'); if ($account->isActive()) { // ... } ``` ### Reading get-method results [](#reading-get-method-results) ``` $result = $client->runMethod('EQ...', 'get_wallet_data'); if ($result->isOk()) { $balance = $result->stack->readBigInt(); // numeric-string $ownerSlice = $result->stack->readSliceBoc(); // base64 BOC } ``` The stack reader is a cursor over a TON `TupleItem` sum-type (`TonTupleItemInt` / `Cell` / `Slice` / `Builder` / `Null` / `Tuple`) and decodes both decimal and `0x`-prefixed bigints via GMP. ### Broadcasting a wallet transfer [](#broadcasting-a-wallet-transfer) ``` use Amashukov\Toncenter\ToncenterWalletRpc; $rpc = new ToncenterWalletRpc($client); $seqno = $rpc->getSeqno($walletRawAddress); // 0 if the wallet is not yet deployed $rpc->sendBoc($signedTransferBocBase64); ``` ### API [](#api) MethodReturns`getMasterchainInfo()``TonMasterchainInfo``getBalance(string $address)``string` (decimal nano-TON)`getAddressInformation(string $address)``TonAccountInfo``isContractDeployed(string $address)``bool``getTypedTransactions(string $address, array $opts = [])``list``getTypedTransaction(string $address, string $lt, string $hash)``TonTransaction``runMethod(string $address, string $method, array $stack = [])``TonRunMethodResult``sendBoc(string $bocBase64)``TonSendBocResult`Requirements ------------ [](#requirements) - PHP 8.3+ - `ext-gmp` (bigint decoding of get-method stack values) - A PSR-18 client + PSR-17 request / stream factories Related packages ---------------- [](#related-packages) PackageRole[amashukov/ton-wallet-php](https://github.com/AndreyMashukov/ton-wallet-php)Wallet v4r2 + `WalletRpcInterface` this client adapts (dependency)[amashukov/http-client-php](https://github.com/AndreyMashukov/http-client-php)PSR-18 cURL client + retry / header-injection middleware[amashukov/ton-cell-php](https://github.com/AndreyMashukov/ton-cell-php)TLB Cell / Builder / BOC layer[amashukov/ton-php](https://github.com/AndreyMashukov/ton-php)TON meta-package[amashukov/blockchain-context-bundle](https://github.com/AndreyMashukov/blockchain-context-bundle)Symfony bundle wiring the whole familyQuality ------- [](#quality) - **PHPStan level 9**, clean. - **php-cs-fixer** `@PER-CS` ruleset. - **GitHub Actions CI** on every push. License ------- [](#license) MIT — see [LICENSE](LICENSE). ### Health Score 42 — FairBetter than 88% of packages Maintenance97 Actively maintained with recent releases Popularity16 Limited adoption so far Community8 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 16d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/4b3e86ca79a82515b23e0239b1d3616c747e59b64c40e169d538d5c759c9bbc4?d=identicon)[Andrey Mashukov](/maintainers/Andrey%20Mashukov) --- Top Contributors [![AndreyMashukov](https://avatars.githubusercontent.com/u/24682497?v=4)](https://github.com/AndreyMashukov "AndreyMashukov (3 commits)") --- Tags blockchainjson-rpcphppsr-18rpcthe-open-networktontoncenterpsr-18rpcjson-rpcblockchaintonthe open networktoncenter ### Code Quality TestsPHPUnit Static AnalysisPHPStan, Rector Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/amashukov-toncenter-client-php/health.svg) ``` [![Health](https://phpackages.com/badges/amashukov-toncenter-client-php/health.svg)](https://phpackages.com/packages/amashukov-toncenter-client-php) ``` ### Alternatives [guzzlehttp/psr7 PSR-7 message implementation that also provides common utility methods 7.9k1.1B3.7k](/packages/guzzlehttp-psr7)[tempest/framework The PHP framework that gets out of your way. 2.2k31.1k11](/packages/tempest-framework)[cakephp/cakephp The CakePHP framework 8.8k19.1M1.7k](/packages/cakephp-cakephp)[telnyx/telnyx-php Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network. 35729.6k2](/packages/telnyx-telnyx-php)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 84735.1k](/packages/flow-php-flow)[laudis/neo4j-php-client Neo4j-PHP-Client is the most advanced PHP Client for Neo4j 185671.3k41](/packages/laudis-neo4j-php-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)