README

PHP SDK by TronZap.com

English | Español | Português | Русский

Official PHP SDK for the TronZap API. This SDK allows you to easily integrate with TronZap services for TRON energy rental.

TronZap.com allows you to buy TRON energy, making USDT (TRC20) transfers cheaper by significantly reducing transaction fees.

👉 Register for an API key to start using TronZap API and integrate it via the SDK.

Installation

You can install the package via composer:

composer require tron-energy-market/tronzap-sdk-php

Check out at Packagist: https://packagist.org/packages/tron-energy-market/tronzap-sdk-php

Requirements

PHP 7.4 or higher with the curl and json extensions
CA certificates for cURL: the SDK verifies the API's TLS certificate. If PHP has no CA bundle configured (common on Windows), set curl.cainfo in php.ini or pass the path of a CA file as the fifth constructor argument.

Usage

use TronZap\Client as TronZapClient;
use TronZap\Exception\TronZapException;

// Initialize the client
$apiToken = 'your_api_token';
$apiSecret = 'your_api_secret';
$client = new TronZapClient($apiToken, $apiSecret);
// Optional: base URL, timeout in seconds (30 by default) and a CA bundle file
// $client = new TronZapClient($apiToken, $apiSecret, 'https://api.tronzap.com', 30.0, '/path/to/cacert.pem');

try {
    // Get account balance
    $balance = $client->getBalance();
    print_r($balance);
    
    // Get address info (resources and balances)
    $addressInfo = $client->getAddressInfo('TRX_ADDRESS');
    print_r($addressInfo);

    // Get available services
    $services = $client->getServices();
    print_r($services);

    // Estimate energy amount for USDT transfer
    $estimate = $client->estimateEnergy('FROM_TRX_ADDRESS', 'TO_TRX_ADDRESS');
    print_r($estimate);

    // Create an energy transaction
    $transaction = $client->createEnergyTransaction(
        'TRX_ADDRESS',       // TRON wallet address
        $estimate['amount'], // Energy amount
        1,                   // Duration (hours): one of the durations getServices() lists
        'my-tx-id',          // External ID (optional)
        true                 // Activate address (optional)
    );
    print_r($transaction);

    // Buy bandwidth
    $bandwidth = $client->createBandwidthTransaction(
        'TRX_ADDRESS',   // TRON wallet address
        345,             // Bandwidth amount
        'bandwidth-1'    // External ID (optional)
    );
    print_r($bandwidth);

    // Buy a resource bundle (energy + bandwidth in one transaction)
    $bundle = $client->createResourceBundleTransaction(
        'TRX_ADDRESS',   // TRON wallet address
        65000,           // Energy amount
        345,             // Bandwidth amount
        1,               // Duration (hours)
        'bundle-1',      // External ID (optional)
        true             // Activate address (optional)
    );
    print_r($bundle);

    // Check transaction status
    $status = $client->checkTransaction($transaction['id']);
    print_r($status);

    // Create AML check for an address
    $amlCheck = $client->createAmlCheck(
        'address',
        'TRX',
        'TRX_ADDRESS'
    );
    print_r($amlCheck);

    // Check AML status
    $amlStatus = $client->checkAmlStatus($amlCheck['id']);
    print_r($amlStatus);
} catch (TronZapException $e) {
    echo "Error: " . $e->getMessage() . " (Code: " . $e->getCode() . ")\n";
}

Available Methods

getServices() - Get list of available services and prices
getBalance() - Get current account balance
getAddressInfo(address) - Get address resources (energy, bandwidth) and balances (TRX, USDT)
createEnergyTransaction(address, energyAmount, duration, externalId, activateAddress) - Create a transaction for energy purchase
createBandwidthTransaction(address, amount, externalId) - Create a transaction for bandwidth purchase
createResourceBundleTransaction(address, energyAmount, bandwidthAmount, duration, externalId, activateAddress) - Create a transaction that purchases energy and bandwidth in one bundle
createAddressActivationTransaction(address, externalId) - Create a transaction for address activation
checkTransaction(transactionId, externalId) - Check status of a transaction
getDirectRechargeInfo() - Get direct recharge service information
getAmlServices() - Get AML services and pricing
createAmlCheck(type, network, address, hash, direction) - Create a new AML check
checkAmlStatus(id) - Get status for an AML check
getAmlHistory(page, perPage, status) - Get AML checks history
getSubscriptions() - Get subscription plans and prices, keyed by subscription ID
startSubscription(subscriptionId, address, durationDays, transactionsLimit, externalId, activateAddress) - Subscribe an address to a plan
checkSubscription(id, externalId) - Get status of a subscription, by id or external id
stopSubscription(id, externalId) - Stop a subscription
getSubscriptionHistory(page, perPage, status) - Get subscription history

For a hash check (createAmlCheck('hash', ...)), address is the recipient address of the transaction, where the funds were received, and direction says which side you are on: deposit if the funds were sent to your address (address is your address), withdrawal if you sent them (address is the external recipient's address). The risk is scored for the counterparty: the sender of a deposit, the recipient of a withdrawal. When you omit direction for a hash check, the SDK sends deposit.

Subscriptions

A subscription keeps an address supplied with energy for every transaction until it is stopped or runs out of days or transactions. getSubscriptions() returns the plans keyed by their subscription ID, in the order the API lists them. Pass that key, such as 'unlimited_energy', to startSubscription, not the plan's numeric id. Starting a subscription charges the plan's initial price.

foreach ($client->getSubscriptions() as $subscriptionId => $plan) {
    echo "$subscriptionId: initial {$plan['initial_price']}, {$plan['price']} per transaction\n";
}

$subscription = $client->startSubscription(
    'unlimited_energy', // Plan key from getSubscriptions()
    'TRX_ADDRESS',      // TRON wallet address
    30,                 // Duration in days, 0 for no time limit
    0,                  // Transactions limit, 0 for no limit
    'subscription-42',  // External ID (optional)
    false               // Activate address (optional)
);

$subscription = $client->checkSubscription(null, 'subscription-42');

$subscription = $client->stopSubscription($subscription['id']);

$history = $client->getSubscriptionHistory(1, 10, 'active');

Start, check and stop return the subscription with its params; the history items carry the usage counters transactions_used, energy_used and total_price instead. A subscription with a transactions limit cannot be stopped (CANNOT_STOP_SUBSCRIPTION).

Error Handling

The SDK uses a hierarchy of exceptions for precise error handling:

TronZapException
├── ApiException             — API-level errors (response code != 0)
├── InvalidRequestException  — Invalid arguments, rejected before sending
├── NetworkException         — Network/connectivity errors
│   ├── ConnectionException  — Could not connect to server
│   ├── TimeoutException     — Request timed out
│   └── SslException         — SSL/TLS errors
└── HttpException            — HTTP non-2xx responses
    ├── RateLimitException   — HTTP 429 Too Many Requests
    ├── UnauthorizedException — HTTP 401/403
    └── ServerException      — HTTP 5xx errors

Example

use TronZap\Client as TronZapClient;
use TronZap\Exception\ApiException;
use TronZap\Exception\ConnectionException;
use TronZap\Exception\HttpException;
use TronZap\Exception\InvalidRequestException;
use TronZap\Exception\NetworkException;
use TronZap\Exception\RateLimitException;
use TronZap\Exception\ServerException;
use TronZap\Exception\SslException;
use TronZap\Exception\TimeoutException;
use TronZap\Exception\TronZapException;
use TronZap\Exception\UnauthorizedException;

$client = new TronZapClient('your_api_token', 'your_api_secret');

try {
    $transaction = $client->createEnergyTransaction('TRX_ADDRESS', 65000, 1);
} catch (ApiException $e) {
    // API-level error (invalid params, insufficient funds, etc.)
    echo "API error [{$e->getCode()}]: {$e->getMessage()}\n";

    // Error key alias, e.g. "invalid_tron_address" or "invalid_tron_address.from_address"
    if ($e->getErrorKey()) {
        echo "Error key: {$e->getErrorKey()}\n";
    }

    // Quote it when contacting support
    echo "Request ID: {$e->getRequestId()}\n";

    if ($e->getCode() === TronZapException::INVALID_TRON_ADDRESS) {
        echo "Check the TRON address format.\n";
    }
} catch (InvalidRequestException $e) {
    echo "Invalid arguments: {$e->getMessage()}\n";
} catch (RateLimitException $e) {
    echo "Too many requests, please slow down.\n";
} catch (UnauthorizedException $e) {
    echo "Invalid API token or signature.\n";
} catch (ServerException $e) {
    echo "TronZap server error [{$e->getStatusCode()}].\n";
} catch (HttpException $e) {
    echo "HTTP error [{$e->getStatusCode()}]: {$e->getMessage()}\n";
} catch (TimeoutException $e) {
    echo "Request timed out.\n";
} catch (SslException $e) {
    echo "SSL error: {$e->getMessage()}\n";
} catch (ConnectionException $e) {
    echo "Connection failed: {$e->getMessage()}\n";
} catch (NetworkException $e) {
    echo "Network error: {$e->getMessage()}\n";
} catch (TronZapException $e) {
    echo "Error [{$e->getCode()}]: {$e->getMessage()}\n";
}

API Error Codes

Code	Constant	Description
1	`AUTH_ERROR`	Authentication error – Invalid API token or signature
2	`INVALID_SERVICE_OR_PARAMS`	Invalid service or parameters
5	`WALLET_NOT_FOUND`	Internal wallet not found. Contact support.
6	`INSUFFICIENT_FUNDS`	Insufficient funds
10	`INVALID_TRON_ADDRESS`	Invalid TRON address, or the address already has an active subscription
11	`INVALID_ENERGY_AMOUNT`	Invalid energy amount
12	`INVALID_DURATION`	Invalid duration
20	`TRANSACTION_NOT_FOUND`	Transaction/subscription not found (alias: `TRANSACTION_NOT_FOUND`)
21	`CANNOT_STOP_SUBSCRIPTION`	Cannot stop subscription, e.g. it has a transactions limit
24	`ADDRESS_NOT_ACTIVATED`	Address not activated
25	`ADDRESS_ALREADY_ACTIVATED`	Address already activated
30	`AML_CHECK_NOT_FOUND`	AML check not found
35	`SERVICE_NOT_AVAILABLE`	Service not available
50	`INVALID_BANDWIDTH_AMOUNT`	Invalid bandwidth amount
500	`INTERNAL_SERVER_ERROR`	Internal server error – Contact support

Development

composer install
composer test
composer lint

The tests run against a local HTTP/TLS server and never call the real API. examples/basic-usage.php is a smoke test against a real environment; the instructions are at the top of the file.

License

The MIT License (MIT). Please see License File for more information.

Support

For support, please contact support@tronzap.com.

tron-energy-market / tronzap-sdk-php

Package info

Security

Statistics