Use Cases and Benefits

Referenced Files in This Document - README.md - server.py - app/api/v1/payments.py - app/schemas/payment.py - app/db/models/payment.py - app/db/models/token.py - app/db/models/transaction.py - app/blockchain/manager.py - app/blockchain/base.py - app/services/blockchain/scanner.py - app/workers/listener.py - app/workers/sweeper.py - app/workers/webhook.py - app/utils/crypto.py - app/core/config.py

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

cTrip Payment Gateway is a high-performance, multi-chain cryptocurrency payment gateway designed to simplify crypto payments for applications. It offers automated payment detection, confirmation monitoring, and funds sweeping across multiple EVM-compatible blockchains. The system is built with FastAPI, supports asynchronous operations, and leverages background workers for scalable, resilient processing. It integrates HD Wallet management for secure address generation and webhook notifications for real-time updates.

Key capabilities include: - Multi-chain support for BSC, Ethereum, and local testing environments - Automated detection of native and ERC20 transfers - Asynchronous API and database operations - Background workers for scanning and sweeping - Webhooks for payment status notifications - Migration system using Alembic

These features enable practical use cases such as e-commerce integration, decentralized exchange liquidity provision, blockchain-based service monetization, and cross-chain payment facilitation.

Section sources - README.md

Project Structure

The repository is organized into modular components that separate concerns across API, blockchain integration, database models, services, workers, and configuration. This layout supports maintainability, scalability, and clear separation of responsibilities.

graph TB subgraph "API Layer" A["app/api/v1/payments.py"] end subgraph "Services" B["app/services/blockchain/scanner.py"] C["app/services/webhook.py"] end subgraph "Workers" D["app/workers/listener.py"] E["app/workers/sweeper.py"] F["app/workers/webhook.py"] end subgraph "Blockchain" G["app/blockchain/manager.py"] H["app/blockchain/base.py"] end subgraph "Database Models" I["app/db/models/payment.py"] J["app/db/models/token.py"] K["app/db/models/transaction.py"] end subgraph "Utilities" L["app/utils/crypto.py"] end subgraph "Configuration" M["app/core/config.py"] end N["server.py"] N --> A A --> I A --> L A --> G B --> H B --> I B --> J D --> B E --> H E --> I F --> C G --> H M --> G M --> D M --> E M --> F

Diagram sources - server.py - app/api/v1/payments.py - app/services/blockchain/scanner.py - app/workers/listener.py - app/workers/sweeper.py - app/workers/webhook.py - app/blockchain/manager.py - app/blockchain/base.py - app/db/models/payment.py - app/db/models/token.py - app/db/models/transaction.py - app/utils/crypto.py - app/core/config.py

Section sources - README.md - server.py

Core Components

This section outlines the primary components and their roles in enabling the gateway’s capabilities.

  • API Layer
  • Payment creation endpoint validates chain and token, generates a unique payment address via HD Wallet, and persists payment metadata.

  • Schemas define request/response structures and constraints for payment operations.

  • Blockchain Integration

  • Manager resolves configured chains and instantiates appropriate blockchain clients.

  • Base client encapsulates Web3 operations, gas estimation, transaction building, and receipt polling.

  • Services

  • Scanner service detects incoming native and ERC20 payments by scanning blocks and matching logs, then confirms transactions based on required confirmations.

  • Webhook service handles asynchronous notifications for payment events.

  • Workers

  • Listener triggers periodic scanning and confirmation checks across configured chains.
  • Sweeper periodically sweeps confirmed payments using the HD Wallet.

  • Webhook actor sends notifications to external systems.

  • Database Models

  • Payment model tracks payment lifecycle, amounts, confirmations, and timestamps.
  • Token model defines supported tokens per chain.

  • Transaction model records sweep transactions and statuses.

  • Utilities and Configuration

  • HD Wallet manager derives addresses deterministically for secure, auditable payment routing.
  • Settings centralizes environment-specific configuration, secrets, and chain definitions.

Section sources - app/api/v1/payments.py - app/schemas/payment.py - app/blockchain/manager.py - app/blockchain/base.py - app/services/blockchain/scanner.py - app/workers/listener.py - app/workers/sweeper.py - app/workers/webhook.py - app/db/models/payment.py - app/db/models/token.py - app/db/models/transaction.py - app/utils/crypto.py - app/core/config.py

Architecture Overview

The system follows an asynchronous, event-driven architecture with clear separation between API, background processing, blockchain interaction, and persistence.

graph TB Client["Client Application"] --> API["FastAPI Payments Endpoint"] API --> DB["Database Models"] API --> HDW["HD Wallet Manager"] API --> Chains["Blockchain Manager"] Chains --> W3["Web3 Clients"] WorkerListener["Worker: Listener"] --> Scanner["Scanner Service"] WorkerSweeper["Worker: Sweeper"] --> SweeperSvc["Sweeper Service"] Scanner --> W3 Scanner --> DB SweeperSvc --> W3 SweeperSvc --> DB DB --> WebhookActor["Webhook Actor"] WebhookActor --> External["External Webhook Receiver"]

Diagram sources - server.py - app/api/v1/payments.py - app/blockchain/manager.py - app/blockchain/base.py - app/services/blockchain/scanner.py - app/workers/listener.py - app/workers/sweeper.py - app/workers/webhook.py

Detailed Component Analysis

Payment Creation Workflow

This sequence illustrates how a client creates a payment, receives a unique address, and how the system validates chain and token eligibility.

sequenceDiagram participant Client as "Client" participant API as "Payments Endpoint" participant DB as "Database" participant HDW as "HD Wallet Manager" participant Chains as "Blockchain Manager" Client->>API : "POST /api/v1/payments" API->>Chains : "Validate chain availability" API->>DB : "Lookup token if provided" API->>HDW : "Generate unique payment address" API->>DB : "Persist Payment record" API-->>Client : "PaymentRead (id, address, amount, status)"

Diagram sources - app/api/v1/payments.py - app/blockchain/manager.py - app/db/models/token.py - app/utils/crypto.py

Section sources - app/api/v1/payments.py - app/schemas/payment.py

Payment Detection and Confirmation

The scanner service continuously scans blocks to detect incoming payments and confirms them based on required confirmations. It distinguishes between native and ERC20 transfers.

flowchart TD Start(["Start Scan Cycle"]) --> LoadState["Load Chain State
and Latest Block"] LoadState --> BuildLists["Build Pending Payments Lists
Native vs ERC20"] BuildLists --> IterateBlocks["Iterate Blocks in Batch"] IterateBlocks --> CheckNative["Check Native Transfers
Match to Payment Addresses"] IterateBlocks --> CheckERC20["Fetch ERC20 Logs
Match to Token and Address"] CheckNative --> MarkDetected["Mark Matching Payments as 'detected'"] CheckERC20 --> MarkDetected MarkDetected --> ConfirmLoop["Compute Confirmations
vs Required"] ConfirmLoop --> Confirmed{"Reached Required?"} Confirmed --> |Yes| SetConfirmed["Set Status 'confirmed'
Trigger Webhook"] Confirmed --> |No| Skip["Skip"] SetConfirmed --> Persist["Commit Changes"] Skip --> Persist Persist --> End(["End Cycle"])

Diagram sources - app/services/blockchain/scanner.py - app/db/models/payment.py

Section sources - app/services/blockchain/scanner.py - app/db/models/payment.py

Funds Sweeping and Settlement

The sweeper worker aggregates confirmed payments and builds transactions to sweep funds using the HD Wallet, ensuring operational efficiency and reduced overhead for platform operators.

sequenceDiagram participant Sweeper as "Sweeper Worker" participant DB as "Database" participant HDW as "HD Wallet Manager" participant W3 as "Web3 Client" participant Chain as "Blockchain" Sweeper->>DB : "Select confirmed payments" Sweeper->>HDW : "Derive destination and fees" Sweeper->>W3 : "Build and sign transaction" W3->>Chain : "Send raw transaction" Chain-->>W3 : "Receipt" W3-->>Sweeper : "Tx Hash" Sweeper->>DB : "Record Transaction and update status"

Diagram sources - app/workers/sweeper.py - app/utils/crypto.py - app/blockchain/base.py - app/db/models/transaction.py

Section sources - app/workers/sweeper.py - app/utils/crypto.py - app/blockchain/base.py - app/db/models/transaction.py

Webhook Notifications

When payments reach confirmed status, the system dispatches webhook notifications asynchronously to external systems for real-time integration.

sequenceDiagram participant Scanner as "Scanner Service" participant DB as "Database" participant WebhookActor as "Webhook Actor" participant External as "External Receiver" Scanner->>DB : "Update Payment to 'confirmed'" Scanner->>WebhookActor : "Send Webhook Task" WebhookActor->>External : "POST Notification Payload" External-->>WebhookActor : "ACK/NACK" WebhookActor-->>DB : "Log Delivery Outcome"

Diagram sources - app/services/blockchain/scanner.py - app/workers/webhook.py

Section sources - app/services/blockchain/scanner.py - app/workers/webhook.py

Dependency Analysis

The system exhibits strong modularity with clear dependencies between modules. The API depends on database models, schemas, and blockchain utilities. Workers orchestrate services and interact with blockchain clients and the database. Configuration drives chain selection and runtime behavior.

graph LR API["API: payments.py"] --> Models["Models: payment.py, token.py"] API --> Schemas["Schemas: payment.py"] API --> Utils["Utils: crypto.py"] API --> ChainsMgr["Blockchain Manager"] ChainsMgr --> Base["Blockchain Base"] Scanner["Scanner Service"] --> Base Scanner --> Models Listener["Worker: Listener"] --> Scanner Sweeper["Worker: Sweeper"] --> Base Sweeper --> Models WebhookActor["Worker: Webhook"] --> External["External Receiver"]

Diagram sources - app/api/v1/payments.py - app/db/models/payment.py - app/db/models/token.py - app/schemas/payment.py - app/utils/crypto.py - app/blockchain/manager.py - app/blockchain/base.py - app/services/blockchain/scanner.py - app/workers/listener.py - app/workers/sweeper.py - app/workers/webhook.py

Section sources - app/core/config.py - app/blockchain/manager.py

Performance Considerations

  • Asynchronous Operations: The API and services leverage asynchronous patterns to improve throughput and reduce latency under concurrent load.
  • Background Workers: ARQ tasks process scanning and sweeping independently, preventing blocking of the main API and enabling horizontal scaling.
  • Gas Estimation and Caching: The base blockchain client caches gas prices and uses buffered gas limits to optimize transaction costs and reduce RPC calls.
  • Batch Scanning: The scanner processes blocks in batches to balance responsiveness and resource usage.
  • Confirmation Thresholds: Adjustable confirmations reduce false positives while minimizing settlement delays.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common operational issues and their mitigations:

  • Chain Configuration Issues
  • Symptom: Unsupported chain errors during payment creation.

  • Resolution: Verify chain entries in configuration and ensure RPC URLs are set correctly.

  • Payment Not Detected

  • Symptom: Payments remain pending despite inbound transfers.

  • Resolution: Confirm scanner is running, check batch sizes and confirmations thresholds, and verify chain state last scanned block.

  • Webhook Failures

  • Symptom: Webhooks not delivered or delayed.

  • Resolution: Check webhook URL and secret configuration, inspect actor logs, and review retry behavior.

  • Database Connectivity

  • Symptom: Operational errors when persisting or querying payment data.
  • Resolution: Validate database URL per environment and ensure migrations are applied.

Section sources - app/api/v1/payments.py - app/services/blockchain/scanner.py - app/workers/webhook.py - app/core/config.py

Conclusion

cTrip Payment Gateway delivers a robust, extensible foundation for integrating cryptocurrency payments across multiple blockchains. Its asynchronous architecture, automated detection and confirmation, HD Wallet-based address management, and webhook integrations provide clear benefits for merchants, developers, and platform operators. By reducing infrastructure complexity, improving operational efficiency, and enabling real-time tracking and settlement, cTrip helps organizations accelerate adoption of crypto payments with confidence.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Use Case Scenarios and Benefits

  • E-commerce Integration for Accepting Cryptocurrency Payments
  • Scenario: An online retailer accepts ETH and USDC on Ethereum and BSC.
  • Benefits: Merchants gain access to multiple cryptocurrencies without maintaining separate banking infrastructures; developers receive a ready-to-use payment processing solution; platform operators reduce operational overhead.

  • Integration Pattern: Use the payment creation endpoint to generate unique addresses per order; rely on scanner and sweeper for detection and settlement; configure tokens and chains via configuration files.

  • Decentralized Exchange Liquidity Provision

  • Scenario: A DEX uses cTrip to automate liquidity provisioning and withdrawal.
  • Benefits: Automated sweeping reduces manual intervention; real-time tracking ensures accurate bookkeeping; multi-chain support simplifies cross-chain swaps.

  • Integration Pattern: Configure multiple chains and tokens; schedule sweeper runs to aggregate liquidity; monitor transaction models for audit trails.

  • Blockchain-Based Service Monetization

  • Scenario: A SaaS platform bills customers in native tokens or stablecoins.
  • Benefits: Seamless multi-currency billing; transparent, immutable records; reduced chargeback risks.

  • Integration Pattern: Issue invoices with payment addresses; track confirmations; emit webhooks to internal billing systems.

  • Cross-Chain Payment Facilitation

  • Scenario: A marketplace enables payments across Ethereum and BSC with unified settlement.
  • Benefits: Unified UX for users; streamlined reconciliation; lower operational costs.
  • Integration Pattern: Configure chains and tokens; use scanner to detect incoming payments on each chain; sweep funds into a single operational wallet.

Expected Performance Metrics (Conceptual)

  • Throughput: Hundreds of concurrent payment requests with sub-second response times for payment creation.
  • Detection Latency: Sub-minute detection for native transfers; ERC20 detection bounded by block time and batch size.
  • Settlement Latency: Immediate confirmation upon reaching required confirmations; sweeping completes within a few minutes post-confirmation.
  • Scalability: Horizontal scaling of workers and database connections; sharding of chain states for multi-chain deployments.

Cost Savings and Competitive Advantages

  • Cost Savings: Reduced engineering effort compared to building custom blockchain integrations; lower maintenance overhead with managed workers and migrations.
  • Competitive Advantages: Faster time-to-market for crypto payments; improved reliability with asynchronous processing and robust error handling; transparent auditability via database models.

Security and Operational Efficiency

  • Security Improvements: Deterministic HD Wallet derivation for auditable address generation; validated private keys and secrets; minimal exposure of sensitive credentials.
  • Operational Efficiency: Automated scanning and sweeping reduce manual oversight; webhook notifications enable real-time integrations; configurable chains and tokens streamline onboarding.

[No sources needed since this section provides general guidance]