PHPackages                             oktayaydogan/usdt-multichain-scanner - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. oktayaydogan/usdt-multichain-scanner

ActiveLibrary[Utility & Helpers](/categories/utility)

oktayaydogan/usdt-multichain-scanner
====================================

Multi-network USDT incoming payment scanner (ERC20 / BEP20)

v1.3.1(5mo ago)09MITPHPPHP ^8.1

Since Jan 19Pushed 5mo agoCompare

[ Source](https://github.com/oktayaydogan/usdt-multichain-scanner)[ Packagist](https://packagist.org/packages/oktayaydogan/usdt-multichain-scanner)[ RSS](/packages/oktayaydogan-usdt-multichain-scanner/feed)WikiDiscussions main Synced today

READMEChangelog (5)DependenciesVersions (3)Used By (0)

USDT Multichain Scanner
=======================

[](#usdt-multichain-scanner)

Production-ready, **read-only** USDT incoming payment scanner for multiple blockchains.

This library normalizes USDT transfers across chains and returns a single DTO format. You decide how to match customers and credit balances (idempotent by `txid`).

---

Supported Networks
------------------

[](#supported-networks)

- EVM (type: `evm`)
    - Ethereum
    - BNB Smart Chain (BSC)
    - Polygon
    - Arbitrum
    - Optimism
- Tron (type: `tron`)

---

Install
-------

[](#install)

```
composer require oktayaydogan/usdt-multichain-scanner
```

---

Configuration (Unified Model)
-----------------------------

[](#configuration-unified-model)

All networks use the same config shape:

```
return [
  'networks' => [
    '' => [
      'enabled' => true|false,
      'type' => 'evm'|'tron',
      'address' => '...',
      // optional:
      'api_key' => '...',
      'endpoint' => '...',
      'usdt_contract' => '...',
      'timeout' => 10,
      'chain_id' => 1,
    ],
  ],
];
```

### Defaults (if you omit fields)

[](#defaults-if-you-omit-fields)

**EVM defaults**

- `endpoint` is selected by network key:
    - `bsc` → BscScan
    - `polygon` → PolygonScan
    - `arbitrum` → ArbiScan
    - `optimism` → Optimism Etherscan
    - anything else → Etherscan
- `usdt_contract` defaults:
    - `bsc` → BSC USDT contract
    - others → ERC20 USDT contract

**Tron defaults**

- `endpoint` defaults to TronScan API base: `https://apilist.tronscanapi.com`
- TRC20 USDT contract is built-in.
- TronScan expects an API Key in headers as `TRON-PRO-API-KEY` (recommended / may be required depending on endpoint and policy).

---

Minimal Config Examples
-----------------------

[](#minimal-config-examples)

### BSC + Tron

[](#bsc--tron)

```
return [
  'networks' => [
    'bsc' => [
      'enabled' => true,
      'type' => 'evm',
      'address' => '0xYourBscAddress',
      'api_key' => 'BSCSCAN_API_KEY',
    ],
    'tron' => [
      'enabled' => true,
      'type' => 'tron',
      'address' => 'TYourTronAddress',
      'api_key' => 'TRONSCAN_API_KEY', // sent as TRON-PRO-API-KEY
    ],
  ],
];
```

### Ethereum only

[](#ethereum-only)

```
return [
  'networks' => [
    'ethereum' => [
      'enabled' => true,
      'type' => 'evm',
      'address' => '0xYourEthAddress',
      'api_key' => 'ETHERSCAN_API_KEY',
    ],
  ],
];
```

---

Usage
-----

[](#usage)

```
use OktayAydogan\UsdtMultichainScanner\Registry\ScannerRegistry;

$config = require __DIR__ . '/config/usdt.php';

$registry = new ScannerRegistry($config);
$transfers = $registry->fetchAll();

foreach ($transfers as $tx) {
  // 1) idempotent check: UNIQUE(network, txid)
  // 2) customer match (your whitelist)
  // 3) credit balance
}
```

---

Security Model
--------------

[](#security-model)

- Read-only API usage
- No private keys
- No signing / sweeping
- Safe for cron & workers

---

License
-------

[](#license)

MIT

---

Fallback Providers
------------------

[](#fallback-providers)

The scanner automatically falls back if the primary provider fails.

### EVM

[](#evm)

- Primary: network-specific Scan API (Etherscan, BscScan, etc.)
- Fallback: optional secondary endpoint via `fallback_endpoint`

### Tron

[](#tron)

- Primary: TronScan API
- Fallback: TronGrid public API

Example:

```
'tron' => [
  'enabled' => true,
  'type' => 'tron',
  'address' => 'T...',
  'api_key' => 'TRONSCAN_KEY',
  // optional overrides
  'endpoint' => 'https://apilist.tronscanapi.com',
  'fallback_endpoint' => 'https://api.trongrid.io/v1',
],
```

---

Cursor / Since Support
----------------------

[](#cursor--since-support)

You can limit scans to **new transactions only** using `since`.

- EVM: `since` = unix timestamp (seconds)
- Tron: `since` = unix timestamp (milliseconds)

Example:

```
'bsc' => [
  'enabled' => true,
  'type' => 'evm',
  'address' => '0x...',
  'api_key' => 'BSCSCAN_KEY',
  'since' => 1710000000,
],
```

Store the latest processed timestamp and pass it back on the next run.

---

Retry & Backoff
-------------------

[](#retry--backoff)

HTTP requests automatically retry on failure.

Defaults:

- retries: 2
- backoff: exponential (300ms \* attempt)

Safe for rate-limited APIs.

---

Async / Worker Usage
--------------------

[](#async--worker-usage)

See `examples/worker.php` for a cron/queue-friendly pattern.

---

---

Advanced Retry & Backoff Configuration
------------------------------------------

[](#advanced-retry--backoff-configuration)

You can fine-tune retry behavior per network.

```
'bsc' => [
  'enabled' => true,
  'type' => 'evm',
  'address' => '0x...',
  'api_key' => 'BSCSCAN_KEY',
  'retry' => [
    'retries' => 3,
    'base_backoff_ms' => 500,
  ],
],
```

Features:

- Exponential backoff
- Jitter (prevents thundering herd)
- Retries on 429 / 5xx
- Separate config per network

---

---

Observability (Logging & Metrics)
-------------------------------------

[](#observability-logging--metrics)

The scanner supports pluggable observability via an `Observer` interface.

You can hook:

- Logs (PSR-3 compatible adapters)
- Metrics (Prometheus / Datadog / Cloud Monitoring)

### Available Signals

[](#available-signals)

- `http.request`
- `http.error`
- `http.latency_ms`

### Custom Observer Example

[](#custom-observer-example)

```
use OktayAydogan\UsdtMultichainScanner\Support\Observer;

class MyObserver implements Observer {
  public function info(string $message, array $context = []): void {
    error_log($message . json_encode($context));
  }
  public function error(string $message, array $context = []): void {
    error_log('[ERROR] ' . $message . json_encode($context));
  }
  public function metric(string $name, float|int $value, array $tags = []): void {
    // push to metrics backend
  }
}
```

---

Unit Tests
----------

[](#unit-tests)

This package includes PHPUnit test scaffolding.

Run tests:

```
composer require --dev phpunit/phpunit
vendor/bin/phpunit
```

Tests cover:

- Factory creation
- Config parsing
- Scanner instantiation

---

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance71

Regular maintenance activity

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

165d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/31257020?v=4)[Oktay Aydoğan](/maintainers/oktayaydogan)[@oktayaydogan](https://github.com/oktayaydogan)

---

Top Contributors

[![oktayaydogan](https://avatars.githubusercontent.com/u/31257020?v=4)](https://github.com/oktayaydogan "oktayaydogan (32 commits)")

### Embed Badge

![Health badge](/badges/oktayaydogan-usdt-multichain-scanner/health.svg)

```
[![Health](https://phpackages.com/badges/oktayaydogan-usdt-multichain-scanner/health.svg)](https://phpackages.com/packages/oktayaydogan-usdt-multichain-scanner)
```

###  Alternatives

[overtrue/pinyin

Chinese to pinyin translator.

4.5k6.9M78](/packages/overtrue-pinyin)[purplepixie/phpdns

PHP DNS Direct Query Module

731.4M5](/packages/purplepixie-phpdns)[rainlab/builder-plugin

Builder plugin for October CMS

17147.6k1](/packages/rainlab-builder-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)