The Challenge of Real-Time Detection
Unlike a bank API where you poll a balance endpoint, detecting on-chain payments requires actively watching the blockchain. Every 3 seconds a new block is finalized on BNB Smart Chain — and you need to check whether any of your deposit addresses received funds in that block.
Doing this naively (polling every address balance) would require thousands of RPC calls per minute. Paychainly solves this with a log-filter approach that scales to tens of thousands of addresses at near-zero RPC cost.
Stage 1: Block Discovery
The BlockDiscoveryService polls eth_blockNumber every 3 seconds. It uses a "safe head" of current block minus 2 to avoid reorg issues. Each new block range is pushed into the block-filter queue with priority 1 for live blocks.
Stage 2: Log Filtering
The BlockFilterProcessor calls eth_getLogs for the USDT Transfer event, filtered to the exact set of monitored deposit addresses. This single RPC call returns all matching transfers in the block range — regardless of how many addresses you're watching.
{
address: USDT_CONTRACT,
topics: [TRANSFER_TOPIC, null, monitoredAddresses],
fromBlock: "0x...",
toBlock: "0x..."
}Stage 3: Transaction Processing
Matching transaction hashes flow into the tx-process queue. Each processor writes a Transaction row with a unique constraint on txHash — providing automatic deduplication even if the same block is processed twice.
Stage 4: Sweep
After a deposit is recorded, a sweep job is queued. The sweep processor (concurrency 1 to prevent nonce collisions) tops up BNB for gas, then forwards the USDT to your master wallet — minus the platform fee.
Backfill on Restart
If the service crashes, it reads the last checkpointed block from network_configs.listenerLastBlock and replays any missed blocks. No deposits are lost.