Details

https://github.com/5zyyy/paper-paws-pocgithub.com

🔎 Overview

This proof of concept is a paper trading simulator designed specifically for meme coins on the Solana blockchain. Built fully using python, it has basic features and functionality, allowing users to practice trading strategies without risking real assets, making it an ideal tool for both newcomers and experienced traders looking to test new approaches.

🏛️ Architecture

  • Frontend: Streamlit

  • Database: DuckDB (Local)

  • API: CoinGecko, BitQuery

  • Backend: Python

Database Structure

The POC v1 uses DuckDB as its local database system, implementing two primary tables to manage trading data efficiently.

Transactions Table

CREATE TABLE IF NOT EXISTS transactions (
    date DATE,
    time TIME,
    symbol TEXT,
    token TEXT,
    contract_address TEXT,
    action TEXT,
    market_cap REAL,
    token_price REAL,
    token_amt REAL,
    total REAL
);

  • date - Date of the trade

  • time - Time of the trade

  • symbol - Token symbol/ticker (e.g., PPAWS)

  • token - Token name

  • contract_address - Token's contract address

  • action - Type of trade (buy/sell)

  • market_cap - Market cap at time of trade

  • token_price - Token price at time of trade

  • token_amt - Amount of tokens traded

  • total - Total SOL value of trade

Positions Table

CREATE TABLE IF NOT EXISTS positions (
    date DATE,
    time TIME,
    symbol TEXT,
    token TEXT,
    contract_address TEXT,
    market_cap REAL,
    average_market_cap REAL,
    initial_investment REAL,
    remaining REAL,
    sold REAL,
    unrealized_profit REAL,
    realized_profit REAL,
    roi REAL,
    total_token_amt REAL,
    remaining_token_amt REAL
);

  • date - Position opening date

  • time - Position opening time

  • symbol - Token symbol/ticker (e.g., PPAWS)

  • token - Token name

  • contract_address - Token's contract address

  • market_cap - Current market cap

  • average_market_cap - Average market cap for position

  • initial_investment - Total SOL invested

  • remaining - Current position value

  • sold - Amount sold in SOL

  • unrealized_profit - Current unrealized P/L

  • realized_profit - Total realized P/L

  • roi - Return on Investment (%)

  • total_token_amt - Total tokens purchased

  • remaining_token_amt - Remaining tokens held

API Implementation

Keep your API key confidential and do not share it with anyone to prevent unauthorized access.

CoinGecko API Overview

  • Used for fetching SOL/USD price

  • Free tier API access

  • No authentication required

  • Public endpoint usage

BitQuery API Overview

  • Used for fetching real-time token data

  • Provides market cap and price information

  • Requires API key for authentication

  • Rate limited based on subscription tier

🗃️ Data Management

POC v2 manages data through two local files: settings.yaml and trades.ddb. When the application is first launched, it automatically creates a settings.yaml file with default values for balance, trading fees, and API key storage. The trades.ddb database file, however, must be manually created through the settings page in the user interface. This database is essential for storing trade history and tracking positions, and the application will display a warning message until it's created.

settings.yaml

This YAML file serves as the central configuration hub, maintaining user preferences between sessions and ensuring trading parameters remain consistent. The file is easily accessible and can be modified through the settings interface in the application.

api_key:
balance: 3
priority_buy_fee: 0.01
priority_sell_fee: 0.01

  • api_key - BitQuery API key

  • balance - Available balance (default: 3 SOL)

  • priority_buy_fee - Priority buy fee (default: 0.01)

  • priority_sell_fee - Priority sell fee (default: 0.01)

trades.ddb

The trades database is the core storage system for all trading activity within POC v1. This DuckDB database maintains comprehensive records of all transactions and positions. It tracks every buy and sell order and stores detailed token information. The database enables real-time portfolio monitoring and provides the foundation for all trading functionality within the application. Through this database, users can access their complete trading history and monitor their current positions and performance metrics. The database contains 2 tables:

  • transactions table - Records every buy and sell trade executed by the user, storing essential details like date, time, token information, trade type, and transaction values.

  • positions table - Tracks all portfolio positions and their performance metrics, including investment amounts, current values, profits/losses, and token quantities.

Benefits of local storage for data privacy

Implementing a fully local data storage system ensures that all trading data, user settings, and API credentials remain solely on the user's machine, with no transmission to external servers or cloud storage.

This local data management approach ensures that sensitive information, such as trading strategies and portfolio values, stays private and secure. Users maintain complete ownership of their data, with the ability to manage, backup, or delete their information as needed. The application's design eliminates concerns about data breaches or unauthorized access to trading information, as there are no external connections beyond the necessary API calls for real-time market data.

The only external communication occurs through the BitQuery API for token data and CoinGecko API for SOL prices, but these interactions are limited to retrieving market information and do not involve sending any user data outward. This architecture provides users with the confidence that their trading activities and performance metrics remain completely private while still enabling full functionality for paper trading.

🗂️ Project File Structure

paper-paws-poc/
├── src/                       # Source code directory
│   ├── app.py                     # Main application entry point
│   ├── trade.py                   # Trade interface implementation
│   ├── portfolio.py               # Portfolio management interface
│   ├── trade_history.py           # Trade history interface
│   ├── settings.py                # Settings management interface
│   │
│   └── helpers/               # Helper modules directory
│       ├── __init__.py
│       ├── api_helper.py          # BitQuery API integration
│       ├── database_helper.py     # Database operations
│       ├── helpers.py             # General utility functions
│       ├── settings_helper.py     # Settings management utilities
│       └── trades_helper.py       # Trade processing logic
│
├── requirements.txt           # Python dependencies
├── settings.yaml              # Application configuration
├── trades.ddb                 # DuckDB database file
├── build.py                   # Executable build script
├── Dockerfile                 # Docker configuration
└── README.md                  # Project documentation

📦 Dependencies

Python (3.13+)
Streamlit (1.41.1)
Pandas (2.2.3)
DuckDB (1.1.3)
PyYAML (6.0.2)
Streamlit Extras (0.5.0)
PyInstaller (6.11.0)

PreviousThe ProjectNextFeatures

Last updated