amashukov/toncenter-client-php

Typed PHP toncenter v2 client for The Open Network — PSR-18 transport, {ok, result} envelope unwrapping, retry-aware, typed Value Objects.

A typed PHP client for the toncenter v2 HTTP API on The Open Network (TON). It speaks any 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.

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 wallet broadcasts through toncenter with no glue code.

Why amashukov/toncenter-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

composer require amashukov/toncenter-client-php

Usage

Any PSR-18 client and PSR-17 factory pair works. The example below wires amashukov/http-client-php (cURL transport + retry / header-injection middleware) with 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

$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

use Amashukov\Toncenter\ToncenterWalletRpc;

$rpc = new ToncenterWalletRpc($client);

$seqno = $rpc->getSeqno($walletRawAddress); // 0 if the wallet is not yet deployed
$rpc->sendBoc($signedTransferBocBase64);

API

Requirements

• PHP 8.3+
• ext-gmp (bigint decoding of get-method stack values)
• A PSR-18 client + PSR-17 request / stream factories

Related packages

Quality

• PHPStan level 9, clean.
• php-cs-fixer @PER-CS ruleset.
• GitHub Actions CI on every push.

License

MIT — see LICENSE.