Skip to main content

​
Overview

Deriverse uses strongly-typed TypeScript interfaces to represent trading data, annotations, and analytics. All type definitions are located in src/lib/types.ts.

​
Core Types

​
Trade

The primary interface representing a completed trade transaction. 
export interface Trade {
    id: string;
    symbol: string;
    quoteCurrency: string;
    side: 'buy' | 'sell' | 'long' | 'short';
    orderType: OrderType;
    quantity: number;
    price: number;
    notional: number;
    pnl: number;
    fee: number;
    feeCurrency: string;
    openedAt: Date;
    closedAt: Date;
    durationSeconds: number;
    isWin: boolean;
    txSignature: string;
    feeBreakdown?: FeeComposition[];
    isMaker?: boolean;
    leverage?: number;
    liquidationPrice?: number;
    marginUsed?: number;
}

​
Properties

​
id
string
required
Unique identifier for the trade
​
symbol
string
required
Trading pair symbol (e.g., SOL-USDC, BTC-PERP)
​
quoteCurrency
string
required
Quote currency for the trade (typically USDC)
​
side
'buy' | 'sell' | 'long' | 'short'
required
Trade direction:
  • buy / sell: Spot market trades
  • long / short: Perpetual futures positions
​
orderType
OrderType
required
Order execution type: 'limit', 'market', 'stop_limit', or 'stop_market'
​
quantity
number
required
Amount of the base asset traded
​
price
number
required
Execution price per unit
​
notional
number
required
Total trade value (price × quantity)
​
pnl
number
required
Profit and loss for the trade (positive for profit, negative for loss)
​
fee
number
required
Total fees paid for the trade
​
feeCurrency
string
required
Currency in which fees are denominated
​
openedAt
Date
required
Timestamp when the position was opened
​
closedAt
Date
required
Timestamp when the position was closed
​
durationSeconds
number
required
How long the position was held (in seconds)
​
isWin
boolean
required
Whether the trade was profitable (true) or not (false)
​
txSignature
string
required
Blockchain transaction signature
​
feeBreakdown
FeeComposition[]
Detailed breakdown of fee components (protocol, network, etc.)
​
isMaker
boolean
true if this was a maker order, false for taker
​
leverage
number
Leverage multiplier (perpetual futures only)
​
liquidationPrice
number
Price at which the position would be liquidated (perpetual futures only)
​
marginUsed
number
Amount of margin allocated to the position (perpetual futures only)

​
OrderType

Type alias for supported order types. 
export type OrderType = 'limit' | 'market' | 'stop_limit' | 'stop_market';

​
Annotation Types

​
TradeAnnotation

User-created notes and metadata for journaling trades. 
export interface TradeAnnotation {
    id?: string;
    tradeId: string;
    notes: string;
    tags: string[];
    lessonsLearned: string;
    createdAt?: Date;
    updatedAt?: Date;
}
​
id
string
Unique identifier for the annotation
​
tradeId
string
required
References the associated trade’s id
​
notes
string
required
User’s notes about the trade
​
tags
string[]
required
Categorical tags for filtering and organization
​
lessonsLearned
string
required
Key takeaways from the trade for future reference
​
createdAt
Date
When the annotation was first created
​
updatedAt
Date
When the annotation was last modified

​
Analytics Types

​
FeeComposition

Breakdown of different fee components. 
export interface FeeComposition {
    type: string;
    amount: number;
    percent: number;
}
​
type
string
required
Fee category (e.g., 'Protocol (Maker)', 'Protocol (Taker)', 'Network')
​
amount
number
required
Absolute fee amount
​
percent
number
required
Percentage of total fees

​
AnalyticsSummary

Aggregated fee analytics data. 
export interface AnalyticsSummary {
    feeComposition: FeeComposition[];
    cumulativeFees: number;
}
​
feeComposition
FeeComposition[]
required
Breakdown of fee types and amounts
​
cumulativeFees
number
required
Total fees paid across all trades

​
DailyPnL

Daily profit/loss aggregation. 
export interface DailyPnL {
    date: string;
    pnl: number;
    trades: number;
    wins: number;
    losses: number;
}
​
date
string
required
Date in YYYY-MM-DD format
​
pnl
number
required
Total profit/loss for that day
​
trades
number
required
Number of trades executed that day
​
wins
number
required
Number of winning trades
​
losses
number
required
Number of losing trades

​
SessionBucket

Performance metrics grouped by session (time of day). 
export interface SessionBucket {
    session: 'morning' | 'afternoon' | 'evening' | 'night';
    pnl: number;
    trades: number;
    winRate: number;
}
​
session
'morning' | 'afternoon' | 'evening' | 'night'
required
Time session:
  • morning: 6:00 AM - 12:00 PM
  • afternoon: 12:00 PM - 6:00 PM
  • evening: 6:00 PM - 10:00 PM
  • night: 10:00 PM - 6:00 AM
​
pnl
number
required
Total PnL for this session
​
trades
number
required
Number of trades in this session
​
winRate
number
required
Win rate as a decimal (0.0 to 1.0)

​
TimeOfDayBucket

Hourly performance metrics. 
export interface TimeOfDayBucket {
    hour: number;
    pnl: number;
    trades: number;
    winRate: number;
}
​
hour
number
required
Hour of day (0-23)
​
pnl
number
required
Total PnL for this hour across all days
​
trades
number
required
Number of trades executed in this hour
​
winRate
number
required
Win rate as a decimal (0.0 to 1.0)

​
Usage Examples

​
Filtering Trades by Type

import { Trade } from './types';

// Filter spot trades
const spotTrades = trades.filter((t: Trade) => 
  t.side === 'buy' || t.side === 'sell'
);

// Filter perpetual trades
const perpTrades = trades.filter((t: Trade) => 
  t.side === 'long' || t.side === 'short'
);

// Filter winning trades
const winningTrades = trades.filter((t: Trade) => t.isWin);

​
Creating Trade Annotations

import { TradeAnnotation } from './types';

const annotation: TradeAnnotation = {
  tradeId: 'trade-123',
  notes: 'Entry was clean, exit could have been better timed',
  tags: ['breakout', 'SOL'],
  lessonsLearned: 'Set tighter trailing stops for volatile moves',
  createdAt: new Date()
};

​
Working with Fee Data

import { Trade, FeeComposition } from './types';

// Calculate total protocol fees
const protocolFees = trades.reduce((sum, trade: Trade) => {
  const protocolFee = trade.feeBreakdown?.find(
    (f: FeeComposition) => f.type.includes('Protocol')
  );
  return sum + (protocolFee?.amount || 0);
}, 0);

Build docs developers (and LLMs) love

Get started for freeTalk to us