Deriverse uses Supabase for persistent storage of wallet data, trade history, and user annotations. These services provide type-safe interfaces for interacting with the database.
SupabaseWalletService
Manages user wallet data including connection information and sync status.
saveWallet
Save or update a wallet in the database using upsert logic.
async saveWallet(params: SaveWalletParams): Promise<UserWallet>
Wallet connection parametersWallet address (blockchain address)
Network identifier (e.g., ‘solana-mainnet’)
Wallet provider name (defaults to ‘manual’)
method
'manual' | 'wallet_connect'
Connection method (defaults to ‘manual’)
The saved wallet recordBlockchain wallet address
ISO timestamp of last sync
ISO timestamp of creation
ISO timestamp of last update
getWallet
Retrieve a wallet by its address.
async getWallet(address: string): Promise<UserWallet | null>
Returns the wallet record or null if not found
updateSyncTime
Update the last_synced_at timestamp for a wallet.
async updateSyncTime(address: string): Promise<void>
getRecentWallets
Get recently synced wallets for displaying in UI.
async getRecentWallets(limit: number = 5): Promise<UserWallet[]>
Maximum number of wallets to return
Array of wallets ordered by most recently synced
isDataStale
Check if wallet data needs refreshing based on time threshold.
isDataStale(wallet: UserWallet, hoursThreshold: number = 24): boolean
Hours before data is considered stale
Returns true if data is older than threshold or never synced
getTimeSinceSync
Get human-readable string for time since last sync.
getTimeSinceSync(wallet: UserWallet): string
Human-readable time (e.g., “5 minutes ago”, “2 hours ago”, “Never synced”)
SupabaseTradeService
Manages trade data persistence and analytics.
saveTrades
Save multiple trades to the database using upsert logic.
async saveTrades(walletAddress: string, trades: Trade[]): Promise<SaveTradesResult>
Wallet address that owns these trades
Array of Trade objects to save
Operation result summaryNumber of trades saved (upserted)
Number of trades updated (always 0 for Supabase upsert)
Number of errors encountered
getTrades
Retrieve all trades for a wallet.
async getTrades(walletAddress: string, limit?: number): Promise<Trade[]>
Optional limit on number of trades returned
Array of trades ordered by closed_at descending (most recent first)
getTradeCount
Get total number of trades for a wallet.
async getTradeCount(walletAddress: string): Promise<number>
deleteTrades
Delete all trades for a wallet.
async deleteTrades(walletAddress: string): Promise<number>
Wallet address to delete trades for
getAnalytics
Get aggregated analytics summary for a wallet.
async getAnalytics(walletAddress: string): Promise<AnalyticsSummary>
Wallet address to analyze
Analytics summary objectCumulative profit and loss
Win rate percentage (0-100)
SupabaseAnnotationService
Manages user annotations and notes for trades.
getAnnotation
Fetch annotation for a specific trade.
async getAnnotation(tradeId: string): Promise<TradeAnnotation | null>
Trade ID to fetch annotation for
Returns annotation or null if not found
saveAnnotation
Save or update annotation for a trade.
async saveAnnotation(annotation: TradeAnnotation, walletAddress?: string): Promise<TradeAnnotation>
Annotation object to saveTrade ID this annotation belongs to
User notes about the trade
Tags for categorizing the trade
Lessons learned from the trade
Optional wallet address for additional validation
The saved annotation with timestamps getAnnotationsForWallet
Get all annotations for a wallet’s trades.
async getAnnotationsForWallet(walletAddress: string): Promise<Record<string, TradeAnnotation>>
Wallet address to fetch annotations for
result
Record<string, TradeAnnotation>
Dictionary mapping trade IDs to their annotations
Example Usage
import { SupabaseWalletService } from '@/services/SupabaseWalletService';
import { SupabaseTradeService } from '@/services/SupabaseTradeService';
import { SupabaseAnnotationService } from '@/services/SupabaseAnnotationService';
// Initialize services
const walletService = new SupabaseWalletService();
const tradeService = new SupabaseTradeService();
const annotationService = new SupabaseAnnotationService();
// Save a wallet
const wallet = await walletService.saveWallet({
address: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU',
network: 'solana-mainnet',
provider: 'phantom',
method: 'wallet_connect'
});
// Get analytics
const analytics = await tradeService.getAnalytics(wallet.wallet_address);
console.log(`Win rate: ${analytics.winRate}%`);
// Save annotation
const annotation = await annotationService.saveAnnotation({
tradeId: 'trade-123',
notes: 'Good entry, should have taken profit earlier',
tags: ['btc', 'long'],
lessonsLearned: 'Set tighter stop losses on volatile markets'
}, wallet.wallet_address);
