Download the PHP package tigusigalpa/whale-alert-php without Composer

Whale Alert PHP/Laravel Client/SDK/Library

An unofficial PHP client library for the Whale Alert Enterprise API.

Disclaimer: This is an unofficial SDK and is not affiliated with, endorsed by, or sponsored by Whale Alert. All product names, logos, and brands are property of their respective owners.

What is this?

This library makes it easy to talk to the Whale Alert Enterprise API from PHP. Whether you want to query transactions and blocks, check blockchain status, or stream real-time whale alerts over WebSocket, the client gives you typed, immutable DTOs and robust error handling out of the box.

It is built around a few ideas that should feel natural in modern PHP:

• It works with any PSR-18 HTTP client, so you are not locked into Guzzle.
• It includes an optional Laravel service provider and facade for framework projects.
• Monetary values stay as strings so you never lose precision.
• Retries, pagination, and WebSocket reconnection are opt-in but easy to enable.

Features

• REST API: Full coverage of the documented endpoints — status, blockchain status, transactions, blocks, and address transactions.
• WebSocket API: Real-time alerts and socials with subscription management, automatic reconnection, ping/pong keep-alive, and event decoding.
• Typed DTOs: Immutable data transfer objects for all API responses, so your IDE can autocomplete fields.
• Financial precision: Amounts and fees are kept as string to avoid the rounding issues that come from float.
• Framework-agnostic: Uses PSR-18 HTTP client abstraction; works with Guzzle or any PSR-18 compatible client.
• Laravel integration: Optional service provider, facade, and config publishing.
• Retry policy: Configurable exponential backoff for idempotent GET requests when the API returns 429 or 5xx errors.
• Pagination: Typed page objects with a lazy iterator and safe next-URL following. The library validates next URLs against the configured base origin so you cannot accidentally follow a malicious link.
• Error handling: Typed exceptions (UnauthorizedException, RateLimitException, and others) for programmatic handling.
• API key security: Your API key is never logged, and error excerpts have api_key values redacted.

Installation

Install the package with Composer:

The package uses Guzzle by default, but you can substitute any PSR-18 HTTP client if you prefer.

Quick Start

REST API

This example creates a client, calls a public endpoint that does not need an API key, and then calls an authenticated endpoint and lists transactions:

WebSocket API

The WebSocket client streams real-time alerts. You register message and error handlers, connect, subscribe, and then call listen() to enter the read loop. Automatic reconnection is opt-in: set maxReconnects greater than zero. It sends RFC 6455 ping frames every 30 seconds by default and requires a pong within 60 seconds; set pingInterval to tune the ping cadence.

Laravel Integration

If you are building a Laravel application, the package can register itself and expose a friendly facade.

1. Add the service provider

For Laravel 11 and later, providers are usually registered in bootstrap/providers.php:

In older Laravel versions, add it to config/app.php instead.

2. Publish the config

Run this command to copy the default configuration into config/whale-alert.php:

3. Set your environment variables

Add these lines to your .env file:

4. Use the facade

5. Or inject the client

If you prefer dependency injection, type-hint the client in a controller or command:

The service provider registers WhaleAlertClient as a singleton, so the same configured instance is reused throughout the request lifecycle.

Configuration

Config Options

The Tigusigalpa\WhaleAlert\Config class controls client behavior:

You can also build a Config from an associative array, which is useful when loading values from Laravel config or a DI container:

Laravel Config

After publishing, config/whale-alert.php looks like this:

Error Handling

Each API error is mapped to a typed exception. You can catch specific exceptions for fine-grained handling, or catch the base ApiException for a generic fallback.

Exception Hierarchy

Retry Policy

Retries are disabled by default. Enable them by setting maxRetries on the Config object or in your Laravel config.

The retry policy is designed to be safe and predictable:

• Only idempotent GET requests are retried. State-changing operations are never retried automatically.
• Retries happen on HTTP 429 (rate limited) and 5xx server errors.
• The 429 response can include a Retry-After header. When present, the client waits at least that long before the next attempt.
• Backoff is exponential: retryDelayMs * 2^attempt, capped at retryMaxDelayMs.

Pagination

List endpoints return a TransactionPage that includes the current slice of transactions and an optional next URL. You can iterate manually or use the built-in helper.

Manual next-page fetching

The same helpers exist for address transactions: getAddressTransactions, getAddressTransactionsNext.

Financial Precision

Cryptocurrency amounts can be very small or very large, and PHP's float type cannot represent them exactly. For that reason, all monetary fields in this library (fee, amount in addresses, and similar) are kept as string.

Keep them as strings for display or pass them to a decimal-arithmetic package such as brick/math. Only cast to float if you fully understand the precision implications.

API Reference

The client exposes one flat API that maps directly to the REST endpoints.

• Status
  • getSupportedBlockchains() — GET /status (public, no key needed)
  • getBlockchainStatus(blockchain) — GET /{blockchain}/status
• Transactions
  • getTransaction(blockchain, hash) — GET /{blockchain}/transaction/{hash}
  • listTransactions(blockchain, options) — GET /{blockchain}/transactions
  • listTransactionsNext(nextUrl) — Follow a pagination URL returned by a previous list call
• Blocks
  • getBlock(blockchain, height) — GET /{blockchain}/block/{height}
• Addresses
  • getAddressTransactions(blockchain, address, options) — GET /{blockchain}/address/{hash}/transactions
  • getAddressTransactionsNext(nextUrl) — Follow a pagination URL for address transactions

For the official API documentation, visit https://developer.whale-alert.io/api-account/documentation.

Examples

Runnable examples are in the examples/ directory:

• examples/rest.php — REST API usage
• examples/websocket.php — WebSocket alerts subscription

Run them from the repository root:

Testing

The project includes unit tests for the REST client, WebSocket client, DTOs, and error handling. Install the test dependencies and run PHPUnit:

License

MIT — see LICENSE

Author

Igor Sazonov — github.com/tigusigalpa