Ready Web3 Boilerplate: FastAPI + Web3 Crypto Auth (MetaMask) + PostgreSQL + Docker
A modern, high-performance REST API core designed according to Clean Architecture principles with integration of authentication via cryptographic signature of Web3 wallets (EVM / MetaMask / WalletConnect). The project is fully containerized using Docker and optimized for instant local deployment or production deployment.
This template is developed as a universal, secure, and architecturally polished foundation (User Management System) for developing P2P platforms, arbitration services, crypto marketplaces, Web3 SaaS solutions, and decentralized applications (dApps). It completely eliminates the need to write basic authorization and profile logic from scratch.
Architectural Features and Technology Stack
1. Passwordless Web3 Authentication: Instead of the classic vulnerable email/password combination, cryptographic verification of the user's public key based on message signing (EIP-191 format) is implemented. Verification is performed natively on the backend using eth-account and eth-keys libraries, ensuring maximum session security.
2. Clean Architecture and Pydantic v2: Clear separation of layer responsibilities. SQLAlchemy models are fully isolated, database interactions are built on independent routers, and input and output data validation is handled by Pydantic v2 schemas (without manual assembly of JSON dictionaries in controllers).
3. End-to-End UUID v7 Standard: All child and related entities of the system (profiles, user configurations) use modern, time-ordered UUID v7 identifiers. This prevents malicious users from brute-forcing incremental IDs, hides the actual data volumes of the system, and speeds up indexing in PostgreSQL.
4. Atomicity and Lazy Initialization of Data: Profiles and system configurations are tightly linked to the user through cascading relationships (ondelete="CASCADE"). Creating an empty anonymous profile and default interface settings occurs atomically within a single transaction at the moment of the first wallet connection, eliminating race conditions.
5. Full Automation of Docker and CI/CD: The infrastructure is completely isolated from the host system. The configured deployment script automatically checks the availability of PostgreSQL, and the create_all directive reliably initializes the database structure. An automatic isolated database seed script is implemented, which checks and forcibly creates or updates superadmin rights for a specified administrative Web3 wallet upon container startup.
6. Optimization for Type Generators: Swagger Specification. REST routes are fully ready for conflict-free automatic generation of strict frontend types (TypeScript) through Orval or OpenAPI-codegen utilities.
Available REST Specification of Endpoints
Authentication:
POST /api/v1/auth/connect: Verification of the crypto message signature and issuance of a non-expiring JWT Bearer session token. Automatically registers a new wallet if it is not in the database.
Web3 Account Management (Access via JWT):
GET /api/v1/users/me: Retrieve full information about the current wallet (status, rating, slots, transaction limits).
PUT /api/v1/users/me: Update public account metadata (display_name).
Profile Management (Access via JWT):
GET /api/v1/profiles/me: Retrieve anonymous profile (biography, social links, extra_data).
PUT /api/v1/profiles/me: Edit profile data.
System Configurations (Access via JWT):
GET /api/v1/configs/me: Retrieve individual settings (interface theme, language, time zone, privacy settings, and json notifications).
PUT /api/v1/configs/me: Change system configurations of the wallet interface.
Monitoring: GET /health: System health check for production load balancers.
Quick Start for Local Development
Deploying an isolated ecosystem with a single command and automatic change pulling (Hot-Reload):
docker compose up --build
A modern, high-performance REST API core designed according to Clean Architecture principles with integration of authentication via cryptographic signature of Web3 wallets (EVM / MetaMask / WalletConnect). The project is fully containerized using Docker and optimized for instant local deployment or production deployment.
This template is developed as a universal, secure, and architecturally polished foundation (User Management System) for developing P2P platforms, arbitration services, crypto marketplaces, Web3 SaaS solutions, and decentralized applications (dApps). It completely eliminates the need to write basic authorization and profile logic from scratch.
Architectural Features and Technology Stack
1. Passwordless Web3 Authentication: Instead of the classic vulnerable email/password combination, cryptographic verification of the user's public key based on message signing (EIP-191 format) is implemented. Verification is performed natively on the backend using eth-account and eth-keys libraries, ensuring maximum session security.
2. Clean Architecture and Pydantic v2: Clear separation of layer responsibilities. SQLAlchemy models are fully isolated, database interactions are built on independent routers, and input and output data validation is handled by Pydantic v2 schemas (without manual assembly of JSON dictionaries in controllers).
3. End-to-End UUID v7 Standard: All child and related entities of the system (profiles, user configurations) use modern, time-ordered UUID v7 identifiers. This prevents malicious users from brute-forcing incremental IDs, hides the actual data volumes of the system, and speeds up indexing in PostgreSQL.
4. Atomicity and Lazy Initialization of Data: Profiles and system configurations are tightly linked to the user through cascading relationships (ondelete="CASCADE"). Creating an empty anonymous profile and default interface settings occurs atomically within a single transaction at the moment of the first wallet connection, eliminating race conditions.
5. Full Automation of Docker and CI/CD: The infrastructure is completely isolated from the host system. The configured deployment script automatically checks the availability of PostgreSQL, and the create_all directive reliably initializes the database structure. An automatic isolated database seed script is implemented, which checks and forcibly creates or updates superadmin rights for a specified administrative Web3 wallet upon container startup.
6. Optimization for Type Generators: Swagger Specification. REST routes are fully ready for conflict-free automatic generation of strict frontend types (TypeScript) through Orval or OpenAPI-codegen utilities.
Available REST Specification of Endpoints
Authentication:
POST /api/v1/auth/connect: Verification of the crypto message signature and issuance of a non-expiring JWT Bearer session token. Automatically registers a new wallet if it is not in the database.
Web3 Account Management (Access via JWT):
GET /api/v1/users/me: Retrieve full information about the current wallet (status, rating, slots, transaction limits).
PUT /api/v1/users/me: Update public account metadata (display_name).
Profile Management (Access via JWT):
GET /api/v1/profiles/me: Retrieve anonymous profile (biography, social links, extra_data).
PUT /api/v1/profiles/me: Edit profile data.
System Configurations (Access via JWT):
GET /api/v1/configs/me: Retrieve individual settings (interface theme, language, time zone, privacy settings, and json notifications).
PUT /api/v1/configs/me: Change system configurations of the wallet interface.
Monitoring: GET /health: System health check for production load balancers.
Quick Start for Local Development
Deploying an isolated ecosystem with a single command and automatic change pulling (Hot-Reload):
docker compose up --build