precolator-sdk 1.0.0

Rust async client SDK for the Precolator perpetual futures trading platform — markets, portfolio, leaderboard, and trading statistics.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

//! Strongly-typed response models for every Precolator API endpoint.

use serde::{Deserialize, Serialize};

// ─── Generic API wrapper ────────────────────────────────────────────────────

/// Standard JSON envelope returned by every endpoint.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApiResponse<T> {
    pub data: T,
    pub timestamp: String,
    pub status: String,
}

/// Error body returned on non-2xx responses.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApiError {
    pub error: String,
    pub status: u16,
    pub message: String,
}

// ─── Health ─────────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HealthStatus {
    pub status: String,
    pub uptime: Option<f64>,
    pub version: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DetailedHealth {
    pub status: String,
    pub uptime: Option<f64>,
    pub version: Option<String>,
    pub solana_rpc: Option<String>,
    pub database: Option<String>,
}

// ─── Markets ────────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Market {
    pub id: String,
    pub name: String,
    pub base_token: String,
    pub quote_token: String,
    pub price: f64,
    pub volume_24h: Option<f64>,
    pub open_interest: Option<f64>,
    pub max_leverage: Option<u8>,
    pub status: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MarketStats {
    pub market_id: String,
    pub volume_24h: f64,
    pub trades_24h: u64,
    pub high_24h: f64,
    pub low_24h: f64,
    pub price_change_24h: f64,
    pub open_interest: f64,
}

// ─── Trades ─────────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Trade {
    pub trade_id: String,
    pub market_id: String,
    pub trader: String,
    pub side: String,
    pub size: f64,
    pub price: f64,
    pub leverage: Option<u8>,
    pub pnl: Option<f64>,
    pub fee: Option<f64>,
    pub timestamp: String,
}

// ─── Portfolio ──────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Portfolio {
    pub wallet: String,
    pub total_balance: f64,
    pub unrealized_pnl: f64,
    pub realized_pnl: f64,
    pub positions: Vec<PortfolioPosition>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PortfolioPosition {
    pub market_id: String,
    pub side: String,
    pub size: f64,
    pub entry_price: f64,
    pub current_price: f64,
    pub pnl: f64,
    pub leverage: u8,
    pub liquidation_price: f64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PortfolioHistory {
    pub wallet: String,
    pub entries: Vec<HistoryEntry>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HistoryEntry {
    pub timestamp: String,
    pub balance: f64,
    pub pnl: f64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PortfolioStats {
    pub wallet: String,
    pub total_trades: u64,
    pub win_rate: f64,
    pub avg_pnl: f64,
    pub best_trade: f64,
    pub worst_trade: f64,
    pub total_volume: f64,
}

// ─── Leaderboard ────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LeaderboardEntry {
    pub rank: u32,
    pub wallet: String,
    pub pnl: f64,
    pub win_rate: f64,
    pub total_trades: u64,
    pub volume: f64,
}

// ─── Tokens ─────────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Token {
    pub symbol: String,
    pub name: String,
    pub mint: Option<String>,
    pub decimals: Option<u8>,
    pub price: Option<f64>,
    pub market_cap: Option<f64>,
}

// ─── Statistics ─────────────────────────────────────────────────────────────

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PlatformStats {
    pub total_volume: f64,
    pub total_trades: u64,
    pub total_users: u64,
    pub open_interest: f64,
    pub total_fees: f64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MarketOverview {
    pub markets: Vec<MarketStats>,
    pub total_markets: u32,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExchangeMetrics {
    pub volume_24h: f64,
    pub trades_24h: u64,
    pub active_users_24h: u64,
    pub liquidations_24h: u64,
    pub fees_24h: f64,
}