PHP Tron

Tron blockchain & TRC-20 toolkit — by Pavlo Popov (IT-HEALER)
EN RU

API Reference

Complete reference of the public classes and methods of PHP Tron.

All classes live under the ItHealer\Tron namespace. Monetary values are returned as Brick\Math\BigDecimal (cast to string with (string) or ->__toString()). Amounts you pass in may be string, int, float or BigDecimal — strings are recommended for precision.

Tron — main facade

ItHealer\Tron\Tron — the single entry point to the library.

Construction

public static function make(
    ?string $apiKey = null,
    string $baseUri = 'https://api.trongrid.io',
    ?string $proxy = null
): Tron

Creates a client configured for TronGrid (or any compatible node).

public function __construct(Api $api)

Low-level constructor that accepts a fully configured Api instance.

Mnemonics

public function mnemonicGenerate(int $wordCount = 15): array

Generate a new mnemonic. $wordCount ∈ {12, 15, 18, 21, 24}. Returns string[] (the words).

public function mnemonicValidate(string|array $mnemonic): bool

Validate a mnemonic against the BIP39 word list and checksum. Returns bool.

public function mnemonicToSeed(string|array $mnemonic, ?string $passphrase = null): string

Derive the binary seed. Returns the seed as a hex string.

Wallets

public function createWallet(string $name, ?string $passphrase = null, int $mnemonicSize = 15): Wallet

Generate a brand new wallet (a fresh mnemonic is created and the primary address at index 0 is derived). Returns Wallet.

public function importWallet(string $name, string|array $mnemonic, ?string $passphrase = null): Wallet

Restore a wallet from an existing mnemonic. Throws TronException if the mnemonic is invalid. Returns Wallet.

Addresses

public function createAddress(Wallet $wallet, ?string $title = null, ?int $index = null): Address

Derive the next address (or a specific $index) and append it to the wallet. Returns Address.

public function deriveAddress(Wallet $wallet, ?string $title = null, int $index = 0): Address

Derive an address at $index without modifying the wallet. Returns Address.

public function importAddress(string $address, ?string $title = null): Address

Build a watch-only Address (no private key, cannot sign). Returns Address.

public function validateAddress(string|Address $address): bool

Validate an address against the node. Returns bool.

Account, balance & resources

public function getAccount(string|Address $address): AccountDTO

Fetch full account information. Returns AccountDTO.

public function getResources(string|Address $address): AccountResourcesDTO

Fetch bandwidth and energy. Returns AccountResourcesDTO.

public function getBalance(string|Address $address): BigDecimal

TRX balance (in TRX, not SUN). Returns BigDecimal.

TRC-20 tokens

public function getTRC20Contract(string $contractAddress): TRC20Contract

Returns a TRC20Contract helper.

public function getTRC20Balance(string|Address $address, string $contractAddress): BigDecimal

Token balance of an address (already scaled by the token's decimals). Returns BigDecimal.

TRX transfers

public function transferPreview(string|Address $from, string|Address $to, BigDecimal|float|int|string $amount): TransferPreviewDTO

Estimate fees / resulting balance without broadcasting. Returns TransferPreviewDTO.

public function transfer(Address $from, string|Address $to, BigDecimal|float|int|string $amount): TransferSendDTO

Sign and broadcast. $from must be a spendable Address. Throws TronException on failure. Returns TransferSendDTO.

public function transferAll(Address $from, string|Address $to): TransferSendDTO

Send the whole balance minus network fees. Returns TransferSendDTO.

TRC-20 transfers

public function transferTRC20Preview(string $contractAddress, string|Address $from, string|Address $to, BigDecimal|float|int|string $amount, BigDecimal|float|int|string $feeLimit = 30): TRC20TransferPreviewDTO

Returns TRC20TransferPreviewDTO.

public function transferTRC20(string $contractAddress, Address $from, string|Address $to, BigDecimal|float|int|string $amount, BigDecimal|float|int|string $feeLimit = 30): TRC20TransferSendDTO

Sign and broadcast a token transfer. Returns TRC20TransferSendDTO.

public function transferTRC20All(string $contractAddress, Address $from, string|Address $to, BigDecimal|float|int|string $feeLimit = 30): TRC20TransferSendDTO

Send the entire token balance. Returns TRC20TransferSendDTO.

History

public function getTransfers(string|Address $address): Transfers

Returns a Transfers iterator of TRX transfers.

public function getTRC20Transfers(string|Address $address): TRC20Transfers

Returns a TRC20Transfers iterator.

public function getTransactionInfo(string $txid): TransactionInfoDTO

Returns TransactionInfoDTO.

public function getTransfer(string $txid): ?TransferDTO

Returns TransferDTO or null.

Constants

Wallet

ItHealer\Tron\Wallet\Wallet — a value object: a mnemonic/seed pair plus its derived addresses. No I/O of its own.

Properties

Methods

public function addAddress(Address $address): void
public function getAddresses(): array          // Address[]
public function getPrimaryAddress(): ?Address   // index 0
public function findAddress(string $address): ?Address
public function maxIndex(): ?int                // highest derivation index used
public function toArray(): array
public static function fromArray(array $data): Wallet

Address

ItHealer\Tron\Wallet\Address — a single Tron address.

Properties

Methods

public function isSpendable(): bool   // false for watch-only / no key
public function toArray(): array
public static function fromArray(array $data): Address
public function __toString(): string  // returns the address

Crypto\Mnemonic

ItHealer\Tron\Crypto\Mnemonic — static BIP39 helpers (also exposed via the Tron facade).

public static function generate(int $wordCount = 15): array      // string[]
public static function validate(string|array $mnemonic): bool
public static function toSeed(string|array $mnemonic, ?string $passphrase = null): string  // hex

Crypto\Encryption

ItHealer\Tron\Crypto\Encryption — password-based AES-256-GCM (PBKDF2-derived key).

public static function encrypt(string $plaintext, string $password): string  // base64 (salt+iv+tag+ciphertext)
public static function decrypt(string $payload, string $password): string     // throws TronException on wrong password

Storage\WalletStore

ItHealer\Tron\Storage\WalletStore — file-based wallet storage with optional encryption and portable backups.

public function __construct(string $directory, ?string $password = null)

When $password is set, every wallet file is encrypted with AES-256-GCM.

public function save(Wallet $wallet): string   // returns the file path
public function exists(string $name): bool
public function load(string $name): Wallet      // throws TronException if missing / wrong password
public function names(): array                  // string[]
public function all(): array                    // Wallet[]
public function delete(string $name): void
public function backup(Wallet|array $wallets, string $file, string $password): void  // always encrypted
public function restore(string $file, string $password): array                        // Wallet[]

Storage\Database

ItHealer\Tron\Storage\Database — thin SQLite (PDO) wrapper used by the deposit monitor. Requires the pdo_sqlite extension. Creates the file and tables automatically.

public function __construct(string $path)   // ':memory:' is supported
public function pdo(): \PDO

Webhook\WebhookSender

ItHealer\Tron\Webhook\WebhookSender — delivers signed JSON webhooks over HTTP POST.

public function __construct(string $url, ?string $secret = null, int $timeoutMs = 10000)

public function isConfigured(): bool

// Compute the X-Tron-Signature header value: "sha256=<hmac>"
public static function signature(string $body, string $secret): string

// Send a payload. Returns ['ok' => bool, 'code' => int, 'error' => ?string].
public function send(array $payload): array

Webhook\DepositMonitor

ItHealer\Tron\Webhook\DepositMonitor — watches addresses for new incoming TRX / TRC-20 transactions and dispatches webhooks. State lives in SQLite.

public function __construct(Tron $tron, Database $db, ?WebhookSender $sender = null, array $options = [])

$options:

Methods

public function watch(string $address, ?string $label = null): void  // idempotent
public function unwatch(string $address): void
public function watched(): array          // array of rows: id, address, label, watch_from, created_at
public function deposits(int $limit = 50): array  // recent deposits, newest first
public function poll(): array             // one tick; returns newly detected deposit rows
public function run(int $intervalSeconds = 30, ?int $maxTicks = null, ?callable $onDeposit = null): void

A deposit row contains: id, address, txid, asset, contract, amount, from_address, block_time, detected_at, webhook_status, webhook_code, webhook_attempts. See docs/WEBHOOKS.md for the full guide.

Api\TRC20Contract

ItHealer\Tron\Api\TRC20Contract — obtained via Tron::getTRC20Contract().

public readonly string $address;

public function name(): string
public function symbol(): string
public function decimals(): int
public function balanceOf(string $address): BigDecimal

Transfer iterators

Both implement Iterator and page through results automatically. All builder methods return $this (chainable). Cap the number of items you read with a break in your loop.

Transfers (TRX) — ItHealer\Tron\Api\Methods\Transfers

public function onlyConfirmation(?Confirmation $confirmed): static
public function onlyDirection(?Direction $direction): static
public function limit(int $limit): static            // 1..200, page size
public function orderBy(?OrderBy $orderBy): static
public function minTimestamp(?int $minTimestamp): static   // ms
public function maxTimestamp(?int $maxTimestamp): static   // ms
public function searchInterval(bool $searchInterval): static

Iterating yields TransferDTO items.

TRC20Transfers — ItHealer\Tron\Api\Methods\TRC20Transfers

public function onlyConfirmation(?Confirmation $confirmed): static
public function limit(int $limit): static
public function fingerprint(?string $fingerprint): static
public function orderBy(?OrderBy $orderBy): static
public function minTimestamp(?int $minTimestamp): static
public function maxTimestamp(?int $maxTimestamp): static
public function contractAddress(?string $contractAddress): static  // filter by token

Iterating yields TRC20TransferDTO items.

Note: TRC20Transfers does not expose onlyDirection(). Filter incoming transfers by comparing $transfer->to to the watched address.

DTOs

All DTOs are immutable, expose toArray(), and live under ItHealer\Tron\Api\DTO.

AccountDTO

AccountResourcesDTO

TransferPreviewDTO

TransferSendDTO

TRC20TransferPreviewDTO

TRC20TransferSendDTO

TransferDTO

TRC20TransferDTO

TransactionInfoDTO

Enums

Namespace ItHealer\Tron\Api\Enums.

Exceptions

ItHealer\Tron\Exceptions\TronException extends \Exception. It is thrown for invalid input, failed previews/transfers, decryption failures, HTTP errors and storage problems. Wrap calls that touch the network or untrusted input in try/catch.