README

PHP client library for the Tokenly API.

Requirements

• PHP 8.3+
• Guzzle HTTP 7.x

Installation

composer require tokenly-app/tokenly-php-client

Getting credentials

Register at tokenlyapp.com, create an app, and obtain your App Key and App Secret from the SDK page.

Usage

Instantiate the client

use Tokenly\TokenlyClient;

$client = new TokenlyClient(
    appKey: 'your-app-key',
    appSecret: 'your-app-secret',
);

Get token balance

Retrieve the current token balance for your app.

use Tokenly\TokenlyClient;

$client = new TokenlyClient('your-app-key', 'your-app-secret');

$balance = $client->getTokenBalance();

echo $balance->balance;        // net balance
echo $balance->tokensSent;     // total tokens sent
echo $balance->tokensReceived; // total tokens received
echo $balance->appId;          // your app ID

Gift tokens

Send tokens to another registered app using its app code.

use Tokenly\TokenlyClient;

$client = new TokenlyClient('your-app-key', 'your-app-secret');

$response = $client->giftTokens('TARGET_APP_CODE');

echo $response->message;                   // "Tokens gifted successfully"
echo $response->transaction->id;           // transaction ID
echo $response->transaction->targetAppCode; // recipient app code
echo $response->transaction->createdAt;    // ISO 8601 timestamp

Error handling

Every method throws a specific exception on failure. All exceptions extend TokenlyException, so you can catch them individually or as a group.

use Tokenly\TokenlyClient;
use Tokenly\Exceptions\AuthenticationException;
use Tokenly\Exceptions\ForbiddenException;
use Tokenly\Exceptions\TokenlyException;
use Tokenly\Exceptions\ValidationException;

$client = new TokenlyClient('your-app-key', 'your-app-secret');

try {
    $response = $client->giftTokens('TARGET_APP_CODE');
} catch (AuthenticationException $e) {
    // 401 — invalid or missing credentials
} catch (ForbiddenException $e) {
    // 403 — app is inactive or lacks permission
} catch (ValidationException $e) {
    // 400 — invalid request (e.g. gifting tokens to yourself)
} catch (TokenlyException $e) {
    // any other API error
}

API reference

giftTokens(string $targetAppCode): GiftTokensResponse

Sends tokens to another app.

GiftTokensResponse properties

Transaction properties

getTokenBalance(): TokenBalanceResponse

Returns the token balance for your app.

TokenBalanceResponse properties

Running tests

./vendor/bin/pest