Features
Last updated
Last updated
The buy function in Paper Paws enables users to purchase tokens using their paper SOL balance. Each purchase transaction automatically includes a priority fee, defaulted to 0.01 SOL, which is deducted from the total buy amount to simulate real market conditions on the Solana blockchain.
Before executing any buy order, the system performs several validation checks to ensure a valid transaction:
Contract Address Validation The system verifies that a contract address has been provided. The contract address is essential as it uniquely identifies the token on the Solana blockchain. An empty contract address will trigger an error message indicating that no contract address was entered.
Buy Amount Validation The buy amount must be a positive number greater than 0 SOL. This validation ensures that users cannot enter negative values or zero for their purchases, as these would represent invalid transactions in a real trading environment.
Balance Validation The system checks if the user has sufficient balance to execute the trade. It compares the user's current paper SOL balance against the requested buy amount. If the balance is insufficient to cover the purchase, the transaction is rejected with an appropriate error message.
Priority Fee Validation Before executing the trade, the system verifies that the user has enough balance to cover both the purchase amount and the priority fee (default 0.01 SOL). The actual buy amount is calculated by subtracting the priority fee from the total input amount. If the remaining amount after the fee deduction is zero or negative, the transaction is rejected.
Token Data Validation
The system validates the token's existence and data through the BitQuery API. This includes:
Verifying the contract address is valid on the Solana blockchain
Confirming the token has a valid price (greater than 0)
Checking if market cap data is available
Validating token name and symbol information
API Response Validation
Two critical API validations are performed:
BitQuery API must return valid token data including price, supply, and market cap
CoinGecko API must provide a valid SOL price for calculations
If any validation fails, the system displays a specific error message to help users understand and correct the issue. These validations ensure the integrity of trades and prevent invalid transactions from being processed.
Upon successful validation, the buy order is processed and recorded in the local database. For new tokens, this creates a new position entry, while purchases of existing tokens update the current position. The transaction details, including the date, time, token information, and amounts, are stored in the transaction history. The system also captures the current market cap and token price at the time of purchase for future reference and profit/loss calculations.
The sell function enables users to exit their positions either partially or completely. Each sell transaction includes a priority fee (default 0.01 SOL) that's deducted from the sell amount to simulate real market conditions.
Before executing any sell order, the system performs several validation checks to ensure a valid transaction:
Contract Address Selection The system verifies that a token has been selected from the dropdown menu of available positions. The dropdown only shows tokens where the user has an active position with remaining balance. If no token is selected, the system returns an error message indicating that a token must be selected.
Sell Percentage Validation
The sell percentage can be input in two ways:
Quick selection radio buttons (25%, 50%, 75%, 100%)
Custom percentage input (0-100%)
The system validates that:
A sell percentage has been specified
The percentage is greater than 0
The percentage does not exceed 100%
Position Validation
The system checks if:
The position exists in the database
The position has a remaining balance greater than 0
The current token amount is sufficient for the requested sell percentage
Priority Fee Validation
Before executing the sell, the system verifies:
The sell amount is sufficient to cover the priority fee (default 0.01 SOL)
The remaining amount after fee deduction is greater than 0
Token Data Validation
The system validates current token data through the BitQuery API:
Valid token price data is available
Current market cap can be retrieved
SOL price data is accessible for calculations
API Response Validation
Two critical API validations are performed:
BitQuery API must return valid token data including price, supply, and market cap
CoinGecko API must provide a valid SOL price for calculations
Each validation failure triggers an appropriate error message to guide the user. This comprehensive validation system ensures that all sell orders are valid and can be executed safely within the paper trading environment.
Upon successful validation, the system calculates the token amount to sell based on the specified percentage and current position size. Using real-time price data from BitQuery and CoinGecko APIs, it determines the SOL value of the sale, deducts the priority fee, and updates the position in the database. The transaction is recorded in the trade history, the user's paper SOL balance is increased by the net sell amount (after fees), and all portfolio metrics including realized/unrealized profits and ROI are recalculated. A success message confirms the completion of the sale, showing the priority fee deducted.
The open positions feature displays all active trading positions where the remaining value is greater than 0 SOL in the user's portfolio. Each position shows essential metrics including the token name, contract address, current market cap, initial investment amount, remaining position value, sold amount, unrealized and realized profit/loss, and ROI percentage. The user can refresh the open positions to update these metrics using real-time price data from BitQuery API, allowing users to monitor their position performance. Users can view their entire portfolio at a glance and select positions for selling through the trade interface. When a position is fully sold (remaining value becomes 0), it automatically moves from the open positions to the closed positions section.
The refresh functionality allows users to update their open position data in real-time. When a user clicks the refresh button (displayed as a "↻" symbol), the system fetches current market data for all open positions simultaneously using the BitQuery API. This batch processing approach is more efficient than updating positions one by one.
The refresh process recalculates several key metrics for each position:
Current market cap based on latest token price and supply
Unrealized profit/loss using the new market data
Remaining position value
Updated ROI percentages
The system maintains the position's historical data like initial investment, average market cap, and realized profits while updating only the dynamic values that depend on current market conditions.
Before data is refreshed, the system performs several validation checks to ensure data can be refreshed:
Open Positions Check The system first verifies that there are open positions to refresh. If no positions with remaining value greater than 0 are found in the database, the system returns an appropriate message indicating there are no open positions to refresh.
Position Data Validation Before updating positions, the system validates:
Initial investment amounts
Remaining token amounts
Sold amounts
Previous realized profits
This ensures that all calculations for unrealized profits and ROI are based on accurate historical data.
Token Data Validation For each open position, the system validates:
Current market cap data is available
Token price information is accessible
Contract addresses are still valid
Token supply data can be retrieved
The system uses a batch API call to efficiently fetch data for multiple tokens simultaneously, reducing API usage and improving performance.
API Response Validation
One critical API validations is performed:
BitQuery API must return valid token data including price, supply, and market cap
Each validation failure triggers an appropriate error message, and the positions remain unchanged until valid data can be obtained. This comprehensive validation system ensures that position updates maintain data integrity while providing users with current market values for their holdings.
An important consideration is that the current batch processing approach means if one position fails to update (due to API errors or invalid data), the entire refresh operation fails and no positions are updated. This is because all positions are deleted and re-inserted as a single transaction. The rationale for the current implementation is because of:
API Efficiency
The current batch processing approach was chosen primarily for API efficiency. By making a single API call for all tokens rather than individual calls for each position, we:
Reduce the total number of API requests
Minimize potential API rate limiting issues
Decrease the overall refresh time
Lower API usage costs
Data Consistency
The batch approach ensures data consistency across the portfolio. When all positions are updated simultaneously:
All positions reflect market prices from the same moment in time
Portfolio calculations (total value, ROI) are based on synchronized data
There's no risk of partial updates creating temporary inconsistencies
This feature is crucial for maintaining accurate portfolio tracking as token prices can change rapidly in the cryptocurrency market.
The Portfolio tab serves as a comprehensive dashboard for tracking and analyzing trading performance. It provides users with a real-time view of their paper trading activities by aggregating data from both open and closed positions stored in the DuckDB database. The interface is divided into three main sections: Portfolio Summary, Opened Positions, and Closed Positions, each offering different insights into trading performance. The system continuously calculates and updates key metrics using data from the positions table, ensuring users have current information about their trading activities.
The Portfolio Summary section provides users with a concise overview of their overall trading performance through key financial metrics displayed in a three-column layout. The left column shows the total amount invested and current portfolio value in SOL. The middle column displays both realized and unrealized profit/loss values, with percentage changes indicating performance relative to the initial investment. The right column presents the total profit/loss (combining both realized and unrealized) and the overall portfolio ROI percentage. These metrics are automatically calculated from the positions table in the database, providing users with real-time insights into their trading performance. The summary serves as a quick snapshot of portfolio health and trading success, allowing users to gauge their performance at a glance.
Total Invested The cumulative amount of SOL used to open positions, representing the total capital committed to trading
Total Current Value The combined value of all remaining open positions plus the proceeds from closed positions (sold amount)
Realized P/L The actual profit or loss from completed trades (closed positions), shown in SOL with a percentage return relative to the investment
Unrealized P/L The potential profit or loss from current open positions based on current market prices, displayed in SOL with a percentage return
Total P/L The sum of realized and unrealized profit/loss, showing the total trading performance in SOL
Overall ROI
The percentage return on investment calculated as ((Total Current Value - Total Invested) / Total Invested) × 100, representing the portfolio's total return
The closed positions section displays all completed trades where the remaining value equals 0 SOL, indicating positions that have been fully exited. It shows the same comprehensive metrics as open positions: token name, contract address, market cap at closing, initial investment amount, final sold amount, and the realized profit/loss with final ROI percentage. Due to the potentially large number of closed positions, the data is presented in a paginated format with 20 entries per page for better navigation and performance. This historical view of completed trades provides valuable insights into past trading performance and helps users track their trading history. Unlike open positions which can be refreshed for current market data, closed position metrics remain static as they represent finalized trades.
The Trade History section provides a chronological record of all trading activities, including both buy and sell transactions. Each trade entry displays essential transaction details such as date, time, token information (symbol, name, contract address), action type (buy/sell), market cap at time of trade, token price, token amount, and total SOL value of the transaction. The data is presented in a paginated format with 20 entries per page for better performance and navigation.. A key feature is the ability to download the complete trade history as a CSV file for external analysis or record-keeping.
The Settings page provides essential configuration options for the paper trading system. Users can manage their trading parameters and system settings through a simple interface. The key features include:
Balance Management Users can view and edit their paper trading balance in SOL, which is used for all trading activities.
API Configuration
BitQuery API key management for market data access
Priority Fee Settings
Configurable buy and sell priority fees
Fees are deducted from trade amounts to simulate network costs
Database Controls
Create new database for fresh start
Reset database to clear all trading history
Delete database for complete removal
All settings are stored in a YAML configuration file and persist between sessions. The settings directly impact trading functionality, position calculations, and system behavior throughout the application.
The YAML configuration file will automatically be created when the app is first launched or if it does not exists.
The database settings section provides essential controls for managing the DuckDB database (trades.ddb) that stores all trading data. This section offers three key operations:
Create Database
Available when no database exists (trades.ddb not found)
Creates new database with two tables (transactions and positions)
Essential for first-time setup or after complete deletion
Reset Database
Delete and recreates trades.ddb
Removes all transaction history and positions data
Requires confirmation to prevent accidental resets
Delete Database
Completely removes the database file (trades.ddb) without recreation
Removes all transaction history and positions data
Requires confirmation to prevent accidental deletion
POC v1 offers three flexible installation methods to accommodate different user preferences and technical expertise. The recommended method is the standalone executable (.exe) installation, which provides a simple click-to-run solution without requiring any technical setup or dependencies. For users familiar with containerization, two Docker options are available: a simple version for quick deployment and an advanced version for users who want more control over the configuration. Finally, for developers or users who prefer direct access to the source code, the application can be cloned from the GitHub repository, allowing for custom modifications and direct interaction with the codebase. Each installation method maintains the same core functionality while catering to different user needs and technical requirements.
Similar to what was described earlier, without the . However, the open positions here will still be updated if it was refreshed in the 'Trade' tab.
