FXFunds — Stablecoin Payments Bot 💸

FXFunds Stablecoin Payments Bot is a blockchain payment automation tool that verifies stablecoin payments, tracks transaction confirmations and manages payment records for USDT on Ethereum (ERC20), Tron (TRC20) and TON. Built by FXFunds.

Overview

The bot takes a payment request (who should be paid, how much, in which token and on which network) and the transaction you observed on-chain, then decides the payment status: pending, detected, confirming, confirmed or failed, with a clear reason. A payment ledger keeps the history, blocks the same transaction hash from being credited twice, fires notifications on status changes and exports to JSON or CSV.

It is read-only. It never needs private keys or seed phrases, and it never signs or sends transactions. You supply transaction data from your own blockchain API, RPC node or explorer.

Key Capabilities

• Payment Verification — Checks network, token, destination address, amount and transaction hash format against the payment request.
• Confirmation Tracking — Compares confirmations with each network's requirement (configurable per payment).
• Multi-Network Support — Network profiles for USDT on ERC20, TRC20 and TON.
• Automatic Status Updates — Moves each payment through pending → detected → confirming → confirmed, or to failed with a reason.
• Duplicate Detection — A transaction hash that has already been credited cannot confirm a second payment.
• Payment Notifications — Pass a callback to receive detected, confirmed and failed events and forward them to email, Slack, Telegram or a webhook.
• Payment History & Reporting — The ledger exports every payment record to JSON or CSV.
• Error Handling — Underpayment, overpayment, wrong address, wrong token and wrong network each get a specific reason.

How the Bot Works

Step	What happens
1. Monitor	Your code fetches transactions from a blockchain API, RPC endpoint or explorer
2. Detect	Pass the transaction and the payment request to the bot
3. Validate	Network, hash format, token, destination address and amount are checked
4. Confirm	Confirmations are compared with the required number
5. Update	The payment status is set, with a reason
6. Notify	Your callback receives the event when the status changes
7. Record	The ledger stores the result for history and reconciliation

Payment Statuses

Status	Meaning
pending	No matching transaction observed yet
detected	Transaction matches but has 0 confirmations
confirming	Transaction matches; confirmations below the requirement
confirmed	Transaction matches and has enough confirmations
failed	Wrong network, token or address, underpaid, invalid hash, or duplicate

Quick Start

Node.js

npm install @fxfunds/stablecoin-payments

npx @fxfunds/stablecoin-payments \
  --network trc20 --id INV-1001 \
  --address TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj --amount 250 \
  --hash a3f1c9e2b7d84f60c1e5a9b3d7f2e8c4a6b0d9e3f7c1a5b8e2d6f0c4a9b3e7d1 \
  --confirmations 20

import { PaymentLedger } from "@fxfunds/stablecoin-payments";

const ledger = new PaymentLedger((event, result) => {
  console.log(`${event}: ${result.paymentId} — ${result.reason}`);
});

const result = ledger.process(
  { paymentId: "INV-1001", network: "trc20", token: "USDT", address: "T...", amount: 250 },
  { txHash: "...", network: "trc20", token: "USDT", toAddress: "T...", amount: 250, confirmations: 20 }
);
console.log(result.status); // "confirmed"
console.log(ledger.toCSV());

Python

pip install fxfunds-stablecoin-payments

fxfunds-payments --network ton --id INV-2001 --address <wallet> --amount 100 \
  --hash <tx_hash> --confirmations 1
# or
python -m fxfunds_stablecoin_payments --network ton --address <wallet> ...

from fxfunds_stablecoin_payments import PaymentLedger, PaymentRequest, ObservedTransaction

ledger = PaymentLedger(lambda event, r: print(event, r.payment_id, r.reason))
req = PaymentRequest("INV-2001", "ton", "USDT", "<wallet>", 100)
tx = ObservedTransaction("<tx_hash>", "ton", "USDT", "<wallet>", 100, confirmations=1)
print(ledger.process(req, tx).status)  # "confirmed"
print(ledger.to_csv())

Run with no arguments to see a demo. Add --json for JSON output.

CLI Options

Option	Description
--network	erc20, trc20 or ton
--id	Payment or invoice ID
--address	Wallet that should receive the payment
--amount	Expected amount
--token	Token symbol (default USDT)
--required	Required confirmations (default: network value)
--tolerance	Allowed shortfall (default 0)
--hash	Observed transaction hash (omit for pending)
--to / --tx-amount / --tx-token / --tx-network	Observed values, if different from the request
--confirmations	Observed confirmations

Sample Output

FXFunds Stablecoin Payments Bot — demo
============================================================
  INV-1001   PENDING     No matching transaction observed yet.
  [notify] detected → INV-1001
  INV-1001   DETECTED    Transaction seen, awaiting first confirmation.
  INV-1001   CONFIRMING  7/19 confirmations.
  [notify] confirmed → INV-1001
  INV-1001   CONFIRMED   Payment verified.
  [notify] failed → INV-1002
  INV-1002   FAILED      Duplicate: transaction hash already credited.

Supported Networks

Network	Token	Default Confirmations	Address Match
Ethereum (ERC20)	USDT	12	Case-insensitive
Tron (TRC20)	USDT	19	Exact
TON	USDT	1	Exact

Defaults can be changed per payment with requiredConfirmations / --required. They are reference values, not guarantees from any network or provider. On TON, use the same address format (EQ… or UQ…) for the request and the transaction.

Project Structure

fxfunds-stablecoin-payments/
├── index.ts                        # TypeScript bot
├── fxfunds_stablecoin_payments.py  # Python bot
├── package.json                    # NPM package config
├── package-lock.json               # NPM lock file
├── tsconfig.json                   # TypeScript config
├── pyproject.toml                  # PyPI package config
├── setup.py                        # Legacy setup shim
├── schema.json                     # JSON-LD structured data
├── zenodo.json                     # Zenodo metadata
├── heartbeat.txt                   # Auto-updated daily
├── mkdocs.yml                      # ReadTheDocs config
├── .readthedocs.yaml               # ReadTheDocs build config
├── docs/
│   ├── index.md                    # Documentation
│   └── requirements.txt
├── dataset/
│   └── stablecoin_payment_benchmarks.csv
├── kaggle/
│   └── notebook.ipynb
├── .github/workflows/
│   ├── heartbeat.yml               # Auto-commit daily
│   ├── npm-publish.yml             # Auto-publish to NPM
│   └── pypi-publish.yml            # Auto-publish to PyPI
├── README.md
└── LICENSE

Dataset

dataset/stablecoin_payment_benchmarks.csv holds 20 synthetic payment scenarios across ERC20, TRC20 and TON, covering every status and failure reason, with the bot's verdict for each. It is for testing and demonstration only and does not contain real on-chain transactions.

Security and Data Handling

• Read-only: the bot never signs, broadcasts or transfers anything.
• No private keys or seed phrases are needed or accepted.
• Store blockchain API credentials in environment variables or a secrets manager, never in code.
• Validate data from external providers before relying on it.
• Review the code, add tests and check your integrations before processing real payments.

FAQ

What is FXFunds Stablecoin Payments Bot? Software that verifies stablecoin payments, tracks confirmations and manages payment records for USDT on ERC20, TRC20 and TON.

Which networks can it check? USDT on Ethereum (ERC20), Tron (TRC20) and TON.

Can it detect incoming payments automatically? It verifies transactions you pass to it. Connect it to your blockchain API or RPC node with a scheduler or event listener to run it continuously.

Does it prevent duplicate payment processing? Yes. The ledger refuses to credit a transaction hash that already confirmed another payment.

Can it send notifications? Yes. Pass a callback to PaymentLedger and forward events to any channel you use.

Does it transfer funds? No. It is a read-only verification tool.

What is the official FXFunds website? https://fxfunds.com/

Keywords

Stablecoin Payments · USDT · Payment Verification · Crypto Payments · ERC20 · TRC20 · TON · Payment Bot · Confirmation Tracking · Blockchain · Fintech · FXFunds

Links

Platform	URL
Website	https://fxfunds.com/
GitHub	https://github.com/FXFunds/fxfunds-stablecoin-payments
GitHub Pages	https://fxfunds.github.io/fxfunds-stablecoin-payments/
NPM	https://www.npmjs.com/package/@fxfunds/stablecoin-payments
PyPI	https://pypi.org/project/fxfunds-stablecoin-payments/
Hugging Face	https://huggingface.co/datasets/FXFunds/stablecoin-payments-benchmarks
Kaggle	https://www.kaggle.com/datasets/fxfunds/stablecoin-payments-benchmarks
Zenodo	https://zenodo.org/records/XXXXXXX
Docs	https://fxfunds-stablecoin-payments.readthedocs.io
Quora	https://fxfunds.quora.com/
Pinterest	https://www.pinterest.com/fxfunds_1/
Medium	https://medium.com/@FX_Funds

About FXFunds

FXFunds is a trading platform covering multiple financial markets, with digital payment methods including USDT on supported blockchain networks. Learn more at fxfunds.com.

License

MIT — FXFunds