DEV Community: Tunmise Ola

Building a Token & NFT Portfolio API for Ethereum with FastAPI and Web3

Tunmise Ola — Thu, 28 May 2026 22:57:14 +0000

Introduction

Ethereum wallets can hold ETH, dozens of ERC-20 tokens, and NFTs spread across multiple collections — yet most tools only show you one piece at a time. I set out to fix that by building a Token & NFT Portfolio API: a FastAPI service that aggregates Ethereum wallet balances, fungible tokens, and NFTs into clean, structured JSON responses.

Whether you're building a crypto dashboard, an NFT explorer, a wallet intelligence tool, or an Ethereum analytics platform, this API gives you a single endpoint to query instead of cobbling together multiple providers.

Here's what we built, how it works, and what comes next.

What It Does

The API solves a deceptively simple problem: given a wallet address, return everything that wallet holds — tokens, NFTs, and native balances — in a consistent, developer-friendly format.

That means:

Ethereum wallet portfolio tracking — query token and NFT holdings for any wallet address
NFT portfolio retrieval — surface NFT holdings by collection, token ID, and metadata
Fungible token balance aggregation — aggregate ERC-20 balances for a given wallet
Clean JSON responses — typed, predictable response shapes that frontend apps can trust
Auto-generated API docs — Swagger UI and ReDoc ship out of the box with FastAPI

Tech Stack

Layer	Technology
Framework	FastAPI
Server	Uvicorn
Blockchain data	Web3 APIs
HTTP client	httpx (async)
Data modeling	Pydantic
Auth tokens	python-jose
Config	python-dotenv
Wallet utilities	web3, eth-account
Database (future)	SQLAlchemy + Alembic + PostgreSQL

Project Structure

The codebase follows a clean separation of concerns — routes own HTTP logic, services own business logic, schemas own data shapes, and utils own helpers.

token-nft_portfolio_api/
│
├── app/
│   ├── main.py     
│   ├── routes/        
│   ├── services/      
│   ├── schemas/         
│   └── utils/           
│
├── requirements.txt
├── .env                 # API keys (never committed)
├── .gitignore
└── README.md

This structure scales well. Adding a new feature area means dropping a new service module and wiring up a route — the rest of the app stays untouched.

API Endpoints

`GET /portfolio/summary/{wallet_address}`

Returns a complete Ethereum portfolio overview for the given wallet — ETH balance, ERC-20 token holdings, and NFTs.

{
  "wallet": "0x123...",
  "chain": "ethereum",
  "tokens": [
    {
      "symbol": "ETH",
      "balance": "1.25"
    }
  ],
  "nfts": [
    {
      "name": "CryptoPunk",
      "token_id": "1234"
    }
  ]
}

`GET /portfolio/nft/{wallet_address}`

Fetches the full NFT holdings for a wallet: collection name, token ID, and available metadata. Useful for building NFT gallery views or ownership verification flows.

`GET /wallet/balance/{wallet_address}`

Returns the native ETH balance for the specified wallet address. Lightweight endpoint for quick balance checks.

Getting Started

Clone and install:

git clone https://github.com/tunmi-stom/token-nft_portfolio_api.git
cd token-nft_portfolio_api

python -m venv venv
source venv/bin/activate        # Linux/macOS
# venv\Scripts\activate         # Windows

pip install -r requirements.txt

Configure your environment:

# .env
MORALIS_API_KEY=your_api_key_here

Start the server:

uvicorn app.main:app --reload

The API will be live at http://127.0.0.1:8000. Hit /docs for the interactive Swagger UI, or /redoc for the ReDoc interface.

Design Decisions Worth Talking About

Why async?
Blockchain data fetching is I/O-bound. When a single portfolio request might fan out into three separate API calls (native balance, ERC-20s, NFTs), running them sequentially is wasteful. FastAPI's async support with httpx lets those calls happen concurrently, cutting response times significantly.

Use Cases

This API is intentionally generic at its core, but the endpoints map directly to real product surfaces:

NFT portfolio dashboards — display a collector's holdings with live metadata
Wallet explorers — let users paste an address and see everything it holds
Blockchain analytics platforms — feed aggregated token data into charts and reports
Crypto accounting tools — pull balances for tax lot tracking or portfolio valuation
Web3 portfolio managers — show users their Ethereum portfolio value in one view

What's Coming Next

The current version is a solid read-only data layer. Here's where it goes from here:

Transaction history — full inbound/outbound history per wallet
Multi-wallet support — aggregate across multiple addresses in a single request
USD portfolio valuation — attach live price feeds to compute total value
Caching layer — Redis-backed TTL caching to reduce Moralis API calls under load
Authentication & rate limiting — per-API-key auth and usage throttling
Solana support — extend the service layer to SPL tokens and Metaplex NFTs
WebSocket live updates — push balance changes to connected clients in real time
Docker deployment — containerized setup for consistent prod/dev environments

Wrapping Up

This project started as a personal tool and grew into something I wanted other developers to be able to use. Querying Ethereum data cleanly — across ETH balances, ERC-20 tokens, and NFTs — is more work than it looks. FastAPI makes it manageable, and Pydantic keeps the response shapes honest.

The full source is on GitHub: github.com/tunmi-stom/token-nft_portfolio_api

Contributions are welcome. Fork it, open an issue, or build something with it.

Built by Tunmise Ola.

How to Create Custom API Documentation in FastAPI

Tunmise Ola — Wed, 20 May 2026 09:16:18 +0000

Have you ever wondered if you could actually change or edit your /docs or /redoc API documentation page? Or are you tired of seeing the same docs page every time you develop an API? Well, you guessed right if you thought it was possible, because yes, it is.
In this article, discover how to develop and customize your own docs page.

Table of Content:

Introduction
Prerequisites
What FastAPI Gives You By Default
Changing the Documetation URLs
Disabling Default Docs
Creating your own Docs Page
Conclusion

Introduction

API Documentation is a feature of an API that gives an overview of an API. That is, its endpoints, the API's current version, etc. FastAPI Documentation is a built-in feature of FastAPI that allows users to have an overview of the capabilities and information about the API, without having to create the API Documentation.

API documentation is an important part of every API because it provides developers with an overview of how the API works, including its available endpoints, request and response formats, authentication methods, current version, and other important details.

One of the reasons many developers love FastAPI is its built-in documentation system. Unlike many backend frameworks where developers need to manually create and maintain documentation, FastAPI automatically generates interactive API documentation out of the box.

With FastAPI, developers can easily test endpoints, inspect request schemas, and understand the capabilities of an API directly from the browser. Even better, FastAPI also allows you to customize these documentation pages to fit your branding, security needs, or developer experience goals.

In this article, we will explore how FastAPI documentation works and how you can create fully custom documentation pages for your APIs.

Prerequisites

To follow along with this article, you should have foreknowledge of the following:

Basic Frontend Programming (HTML, CSS & JS).
Basic Python syntax knowledge.
A General understanding of how APIs work.

Python Packages to install:
FastAPI - The framework to help us create the API.
Uvicorn - A lightning-fast ASGI server to run the FastAPI App.

Run in in your command line:

pip install fastapi uvicorn

What FastAPI Gives You By Default

Create a FastAPI App
To create an API, create a Python file main.py
In this file, type the following:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"message": "My first API built with FastAPI"}

Then open the file's directory in your command line and type:

uvicorn main:app --reload

Then open your browser and enter http://localhost:8000/ and you will see the API. Like this:

Then FastAPI generates two docs for you:
Swagger UI: http://localhost:8000/docs
Redocly: http://localhost:8000/redoc
Your API's default documentation pages will look like these:
For Swagger:

For Redocly:

Changing the Documentation URLs

One of the things you can customise is the Documentations URLs. You can change the default documentation by changing the parameters of app to this:

app = FastAPI(
    docs_url="/documentation",
    redoc_url="/reference", 
)

When you try to access the /docs or /redoc endpoints, it returns Not Found.

Disabling Default Docs

You can disable the documentations page by setting the parameters of the app variable to None:

app = FastAPI(
    docs_url=None,
    redoc_url=None, 
)

Creating your own Docs Page

By default, a FastAPI application returns JSON responses for API endpoints. However, since browsers can also render HTML, you can build a fully custom documentation page by returning HTML instead of JSON for a specific route.

To do this, you simply create an endpoint that returns HTML content using FastAPI’s HTMLResponse.

You can also disable the default Swagger and ReDoc documentation pages if you want full control over your API documentation interface.

Example: Custom Documentation Page

from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI(
    docs_url=None,
    redoc_url=None,
)

@app.get("/")
def root():
    return {"message": "FastAPI APP"}

@app.get("/docs", include_in_schema=False, response_class=HTMLResponse)
def custom_docs():
    return """
<!DOCTYPE html>
<html>
<head>
    <title>FastAPI Custom Docs</title>
</head>
<body>
    <h1>FastAPI Custom Docs</h1>
    <p>This is a simple custom documentation page.</p>
</body>
</html>
"""

How it works

The /docs endpoint now returns HTML instead of JSON.
response_class=HTMLResponse tells FastAPI to render the response as HTML.
include_in_schema=False hides this route from the autogenerated API documentation.
Setting docs_url=None disables the default Swagger UI.

Result

When you visit:

/docs

you will see your custom HTML documentation page instead of the default FastAPI Swagger interface.

From here, you can fully customize the page with:

CSS styling
JavaScript interactivity
Branding and logos
Links to API guides or SDKs

Conclusion

FastAPI gives you a powerful starting point with automatic documentation, but its real strength is flexibility. You can either use the built-in tools or completely replace them with your own custom developer experience.

If you’re building production-grade APIs, especially something like wallet infrastructure or developer tools, custom documentation is not just a nice-to-have feature — it’s a competitive advantage.

Building Ethereum Wallet Authentication with FastAPI and Web3.py

Tunmise Ola — Sun, 17 May 2026 21:00:33 +0000

Structuring and building a web3 wallet authentication is not as hard as it sounds and with the right guidance and attitude, you will find building backend systems for dApps (not just wallet auth) as more of a hobby than a tedious work.

Table of Content:

Introduction
Foreknowledge
Prerequisites
The architecture
Nonce generation
Signing Flow
Verification of the Signature
JSON Web Token (JWT) Issuance
Best Practices
Conclusion

Introduction:
In traditional web applications, authentication is usually built around usernames, emails, and passwords. Web3 applications take a completely different approach. Instead of proving identity with a password, users prove ownership of a wallet through cryptographic signatures.

This is where wallet authentication comes in. Wallet authentication allows users to securely log into decentralized applications (dApps) using wallets like MetaMask, or Trust Wallet without creating traditional accounts or storing passwords.
In this article, we will build a complete Ethereum wallet authentication backend. We will cover the architecture, nonce generation, wallet signing flow, signature verification, and JWT issuance.
By the end of this guide, you will understand how modern dApps authenticate users securely while keeping the backend lightweight and scalable.

Foreknowledge:
Before you continue with the tutorial for implementation, you should have foreknowledge of these concepts:

Basic Python programming
APIs and HTTP requests
REST architecture
JSON data handling
Basic understanding of blockchain wallets

You do not need advanced blockchain knowledge to follow through this tutorial. As long as you understand how APIs work, you can build wallet authentication systems.

Prerequisites
To follow along, make sure you have the following installed:

Python 3.10+
Pip
Virtual environment
Git

You will also need these Python libraries:

pip install fastapi uvicorn web3 eth-account jose python-dotenv

You should also have:

A crypto wallet like MetaMask
Basic understanding of signing messages

You can find the github repo here
You can find the Live API here

The Architecture
Before writing code, let us understand the authentication flow.
Unlike traditional login systems, wallet authentication does not use passwords. Instead, the backend generates a unique message (nonce), and the wallet signs it.
The flow works like this:

User connects wallet
Backend generates nonce
Frontend asks wallet to sign nonce
User signs the message
Signed message is sent to backend
Backend verifies signature
Backend issues JWT token
User becomes authenticated

A visual representation can be:
Frontend
↓
Request Nonce
↓
Backend Generates Nonce
↓
Wallet Signs Message
↓
Frontend Sends Signature
↓
Backend Verifies Signature
↓
JWT Token Issued

This process proves that the user owns the wallet without exposing private keys.

Nonce Generation
A nonce is a one-time random string generated by the backend.
Its main purpose is to:

prevent replay attacks
ensure every login request is unique
create a secure signing challenge Example nonce generation:

import secrets

nonce = secrets.token_hex(16)

This generates a secure random hexadecimal string.
Example:

9f3d1a8bc44e1ff03c2e71ab93a12d4c

This nonce is usually stored temporarily in three ways:

Redis
PostgreSQL
in-memory cache A common backend structure looks like this:

nonces = {}

address = wallet_address.lower()
nonces[address] = nonce

When the frontend requests authentication, the backend responds with the nonce tied to that wallet address.

Signing Flow
Once the frontend receives the nonce, it asks the user to sign it using their wallet.

The frontend typically uses libraries like:

ethers.js
web3.js

Example signing flow using ethers.js:

const signer = provider.getSigner()

const signature = await signer.signMessage(nonce)

At this stage:

the wallet does NOT send private keys
the wallet only produces a cryptographic proof
the backend can later verify ownership

The frontend then sends:

wallet address
signature
nonce

to the backend verification endpoint.

Verification of the Signature

This is the core security layer of wallet authentication.

The backend verifies:

the signature is valid
the signer actually owns the wallet
the nonce matches the stored challenge

Using Web3.py and eth-account:

from eth_account.messages import encode_defunct
from web3 import Web3

message = encode_defunct(text=nonce)

recovered_address = Web3().eth.account.recover_message(
    message,
    signature=signature
)

if recovered_address.lower() != wallet_address.lower():
    raise Exception("Invalid signature")

How this works:

Ethereum signatures can mathematically recover the signer’s wallet address.
if the recovered address matches the submitted wallet address, authentication succeeds.
if not, the request is rejected.

Once verification succeeds:

delete the nonce
prevent replay attacks
continue authentication

Example:

del nonces[wallet_address.lower()]

JSON Web Token (JWT) Issuance
After successful verification, the backend issues a JWT token.

JWTs allow authenticated access to protected endpoints without repeatedly signing messages.

Example JWT generation:

import jwt
from datetime import datetime, timedelta

payload = {
    "sub": wallet_address,
    "exp": datetime.utcnow() + timedelta(hours=24)
}

token = jwt.encode(payload, SECRET_KEY, algorithm="HS256")

The token contains:

wallet address
expiration time
authentication claims

The frontend stores this token and includes it in future API requests.
Example:

Authorization: Bearer YOUR_JWT_TOKEN

Best Practices
When building production-grade wallet authentication systems:

Use Expiring Nonces

Never reuse a nonce.

Use HTTPS

Always encrypt requests.

Add Rate Limiting

Prevent spam attacks.

Store JWT Secret Securely

Use environment variables.

Add Wallet Chain Validation

Ensure users sign from the correct network.

Use Short JWT Expiration

Reduce token abuse risk.

Conclusion
Wallet authentication is one of the foundational systems behind modern Web3 applications. While it may initially seem complex, the entire process boils down to a simple cryptographic challenge-response flow.

Using FastAPI and Ethereum tools, you can build secure authentication systems that:

eliminate passwords
improve user ownership
simplify onboarding
integrate seamlessly with dApps

Once you understand wallet authentication, building more advanced Web3 backend systems such as:

wallet portfolio trackers
NFT dashboards
staking platforms
DAO voting systems
on-chain analytics APIs

becomes significantly easier.
Wallet authentication is becoming the standard identity layer for decentralized applications. Understanding this system gives backend developers a strong foundation for building secure Web3 infrastructure. The future of authentication is shifting toward ownership-based identity, and wallet authentication is one of the strongest examples of that transition.
Happy Coding!

Built and deployed a Wallet Authentication API using FastAPI + PostgreSQL + Web3.py.

Tunmise Ola — Wed, 13 May 2026 01:50:57 +0000

Features:
• Wallet signature verification
• JWT authentication
• Multi-chain support
• Nonce-based security
• Production-ready architecture

Tech stack:
FastAPI, SQLAlchemy, PostgreSQL, Web3.py

GitHub: https://github.com/tunmi-stom/wallet_auth_api
Live API: https://wallet-auth-api.onrender.com