API Blockchain Python

A secure and scalable REST API for blockchain transaction management built with FastAPI, featuring wallet creation, transaction processing, and on-chain validation with enterprise-grade security patterns.

Architecture Overview

This project implements a Clean Architecture with Domain-Driven Design (DDD) principles, ensuring separation of concerns, testability, and maintainability.

Architecture Layers

├── app/
│   ├── application/          # Application Layer (Use Cases, Handlers, Schemas)
│   │   └── v1/
│   │       ├── transaction/  # Transaction feature module
│   │       └── wallet/       # Wallet feature module
│   ├── domain/              # Domain Layer (Entities, Repository Interfaces)
│   │   ├── transaction/
│   │   └── wallet/
│   ├── infrastructure/      # Infrastructure Layer (External integrations)
│   │   ├── blockchain/      # Web3 integrations
│   │   ├── db/             # Database implementations
│   │   └── config.py       # Configuration management
│   └── shared/             # Shared utilities
└── tests/                  # Unit tests (98% coverage)

Key Features

Security First

HashiCorp Vault integration for private key management
No private keys stored in database - keys secured in Vault
Transaction signing happens securely via Vault
Async operations for high concurrency

Blockchain Integration

Real Web3 connectivity (Mainnet/Testnet support)
ETH and ERC20 token transaction support
Transaction confirmation validation with configurable thresholds
On-chain transaction verification

Database & Persistence

PostgreSQL with async connection pooling
SQLAlchemy ORM with proper migrations
Transaction history with status tracking
Soft deletes for audit trails

Monitoring & Observability

Prometheus metrics for comprehensive monitoring
Grafana dashboards for visualization
Structured JSON logging with Structlog + Loguru
Real-time performance tracking for all operations
Business metrics for transaction analytics

Technology Stack

FastAPI - Modern async web framework
Web3.py - Ethereum blockchain interaction
HashiCorp Vault - Secrets management
PostgreSQL - Primary database
SQLAlchemy - ORM with async support
Alembic - Database migrations
Pytest - Testing framework (98% coverage)
Docker - Containerization

Monitoring Stack:

Prometheus - Metrics collection and storage
Grafana - Visualization and dashboards
Structlog + Loguru - Structured logging
FastAPI Instrumentator - Automatic API metrics

Design Patterns & Principles

Why These Patterns?

Clean Architecture: Ensures business logic independence from external frameworks
Repository Pattern: Abstracts data access, enabling easy testing and swapping implementations
Dependency Injection: Promotes loose coupling and testability
Use Case Pattern: Encapsulates business logic in reusable components
Feature-based Modules: Organizes code by business features rather than technical layers

Benefits

High Testability (98% test coverage achieved)
Easy Maintenance - Clear separation of concerns
Scalability - Async-first design
Security - Vault integration for sensitive data
Flexibility - Easy to swap implementations

API Endpoints

Wallet Management

Create Wallets

POST /v1/wallets
Content-Type: application/json

{
  "n": 5
}

Response:

{
  "addresses": ["0xabc...", "0xdef..."],
  "status": "success"
}

List All Wallets

GET /v1/wallets

Transaction Management

Create On-Chain Transaction

POST /v1/transaction
Content-Type: application/json

{
  "address_from": "0x742d35Cc6554C65532e42C8b24fd213ee707b96",
  "address_to": "0x8ba1f109551bD432803012645Hac136c",
  "asset": "ETH",
  "value": "0.001",
  "contract_address": null
}

For ERC20 Tokens:

{
  "address_from": "0x742d35Cc6554C65532e42C8b24fd213ee707b96",
  "address_to": "0x8ba1f109551bD432803012645Hac136c",
  "asset": "USDT",
  "value": "10.5",
  "contract_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
}

Value Format Options:

String decimal (recommended): "0.0001"
Float: 0.0001
Integer string: "1"

Internal Conversion:

0.0001 ETH → 100000000000000 Wei (stored as integer)
Uses Decimal library for precision-safe calculations
No floating-point precision issues

Response:

{
  "hash": "0x123...",
  "status": "pending",
  "effective_fee": 0.001234,
  "created_at": "2023-12-01T10:00:00Z"
}

Note: All fee values in responses are returned in ETH decimal format for consistency.

Validate Transaction

GET /v1/transaction/{tx_hash}?require_confirmations=true&min_confirmations=6

Response:

{
  "is_valid": true,
  "transfers": [
    {
      "asset": "eth",
      "address_from": "0x742d35Cc...",
      "value": "1.0"
    }
  ],
  "confirmations": 12,
  "is_confirmed": true,
  "min_confirmations_required": 6
}

Note: All transfer values are returned in ETH decimal format (converted from Wei).

Setup & Installation

Prerequisites

Docker & Docker Compose
Git

Step 1: Clone Repository

git clone <repository-url>
cd api-blockchain-python

Step 2: Environment Configuration

Configure environment variables in docker-compose.yml. The main settings you may want to customize are in the api service:

api:
  build: .
  container_name: blockchain-api
  environment:
    - POSTGRES_DSN=postgresql://user:password@postgres:5432/custody
    - VAULT_URL=http://vault:8200
    - VAULT_TOKEN=root
    - VAULT_SECRET_PATH=eth_wallets
    - WEB3_PROVIDER_URL=https://sepolia.infura.io/v3/YOUR_PROJECT_ID  # Update this
    - LOG_LEVEL=INFO
    - ENVIRONMENT=development
    - APP_VERSION=1.0.0
    - ENABLE_METRICS=true

Important: Update the WEB3_PROVIDER_URL with your own Infura project ID or blockchain provider URL.

Step 3: Start All Services via Docker Compose

# Start all infrastructure (PostgreSQL, Vault, API, Prometheus, Grafana)
docker-compose up -d

# Check if all services are running
docker-compose ps

# View application logs (optional)
docker-compose logs -f blockchain-api

Step 4: Database Setup

# Run migrations automatically via Docker
docker exec blockchain-api alembic upgrade head

Step 5: Access Application

The application will be available at:

API: http://localhost:8000
Interactive Documentation: http://localhost:8000/docs
Grafana (monitoring): http://localhost:3000 (admin/admin)
Prometheus (metrics): http://localhost:9090

Testing

Run Tests

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov

# Run tests with coverage
export PYTHONPATH=.
pytest --cov=app --cov-report=term-missing

Test Coverage

The project maintains 98% test coverage across all critical components:

Detailed Coverage by Module:

Application Layer (Use Cases): 96% coverage
- Transaction Use Cases: 98% coverage (212/212 lines)
- Wallet Use Cases: 93% coverage (50/54 lines)
Domain Layer: 86% coverage
- Transaction Entities: 100% coverage (18/18 lines)
- Wallet Entities: 100% coverage (8/8 lines)
- Repository Interfaces: 73-77% coverage (abstract interfaces)
Infrastructure Layer: 98% coverage
- Database Repositories: 100% coverage (189/189 lines)
- Blockchain Integration: 97% coverage (62/64 lines)
Shared Components: 99% coverage
- Monitoring & Metrics: 98% coverage (137/140 lines)
- Utilities & Validators: 100% coverage (34/34 lines)
- Logging: 100% coverage (43/43 lines)

Total: 845 lines covered out of 866 total lines (98% coverage)

The test suite includes:

253 test cases covering all critical paths
Unit tests for all business logic
Integration tests for database operations
Mock tests for external services (Vault, Web3)
Error scenario testing for robust error handling

Security Considerations

Private Key Management

Never store private keys in database
Use HashiCorp Vault for all sensitive data
Rotate Vault tokens regularly
Audit Vault access logs

Transaction Security

Validate all inputs rigorously
Use transaction confirmations to prevent reorganization attacks
Implement rate limiting in production
Monitor gas prices for fee optimization

Network Security

Use HTTPS in production
Implement API authentication (JWT recommended)
Rate limit endpoints to prevent abuse
Monitor suspicious patterns

Deployment

Step 1: Production Environment Configuration

Create .env file for production:

# Database (Production)
POSTGRES_DSN=postgresql://user:secure_password@prod-db:5432/custody_prod

# Vault (Production)
VAULT_URL=https://vault.yourcompany.com
VAULT_TOKEN=<production-token>

# Blockchain (Production)
WEB3_PROVIDER_URL=https://mainnet.infura.io/v3/YOUR_PRODUCTION_PROJECT_ID

# Monitoring (Production)
LOG_LEVEL=INFO
ENVIRONMENT=production
APP_VERSION=1.0.0
ENABLE_METRICS=true

Step 2: Start All Services

# Start all services (PostgreSQL, Vault, API, Prometheus, Grafana)
docker-compose up -d

# Check service health
docker-compose ps

Step 3: Run Database Migrations

# Run migrations to create/update database schema
docker exec blockchain-api alembic upgrade head

Step 4: Verify Deployment

# Check API health
curl http://localhost:8000/health

# Check metrics endpoint
curl http://localhost:8000/metrics

# Test API endpoints
curl http://localhost:8000/docs

# Check monitoring services
curl http://localhost:9090  # Prometheus
curl http://localhost:3000  # Grafana (admin/admin)

Monitoring & Observability

This project includes a complete monitoring and observability stack with Prometheus, Grafana, and structured logging.

Quick Start Monitoring

Development with monitoring:

# Set monitoring environment variables
export LOG_LEVEL=INFO
export ENABLE_METRICS=true
export ENVIRONMENT=development

# Access monitoring services
# API: http://localhost:8000
# Prometheus: http://localhost:9090
# Grafana: http://localhost:3000 (admin/admin)

Available Monitoring Endpoints

Health Check: GET /health
Prometheus Metrics: GET /metrics
API Documentation: GET /docs
Root Information: GET /

Key Metrics Tracked

API Performance:

Request rates and response times
Error rates by endpoint
HTTP status code distribution

Blockchain Operations:

Transaction creation/validation rates
Confirmation tracking
Web3 provider response times
Gas fee analysis

Security & Infrastructure:

Vault operation success/failure rates
Database query performance
Connection pool usage
Wallet creation rates

Business Metrics:

Transaction volume by asset (ETH/tokens)
Success rates by transaction type
Fee optimization tracking

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github/workflows		.github/workflows
app		app
migrations		migrations
tests		tests
.gitignore		.gitignore
.python-version		.python-version
Dockerfile		Dockerfile
README-PT.md		README-PT.md
README.md		README.md
alembic.ini		alembic.ini
api-blockchain-dashboard.json		api-blockchain-dashboard.json
dashboard.yaml		dashboard.yaml
datasources.yaml		datasources.yaml
debug_pytest.py		debug_pytest.py
docker-compose.yml		docker-compose.yml
main.py		main.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
run_tests.py		run_tests.py

devworlds/api-blockchain-python

Folders and files

Latest commit

History

Repository files navigation

API Blockchain Python

Architecture Overview

Architecture Layers

Key Features

Security First

Blockchain Integration

Database & Persistence

Monitoring & Observability

Technology Stack

Design Patterns & Principles

Why These Patterns?

Benefits

API Endpoints

Wallet Management

Create Wallets

List All Wallets

Transaction Management

Create On-Chain Transaction

Validate Transaction

Setup & Installation

Prerequisites

Step 1: Clone Repository

Step 2: Environment Configuration

Step 3: Start All Services via Docker Compose

Step 4: Database Setup

Step 5: Access Application

Testing

Run Tests

Test Coverage

Security Considerations

Private Key Management

Transaction Security

Network Security

Deployment

Step 1: Production Environment Configuration

Step 2: Start All Services

Step 3: Run Database Migrations

Step 4: Verify Deployment

Monitoring & Observability

Quick Start Monitoring

Available Monitoring Endpoints

Key Metrics Tracked

Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages