@catalyst-team/poly-sdk 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (277) hide show
  1. package/README.md +665 -807
  2. package/README.zh-CN.md +645 -342
  3. package/dist/__tests__/integration/arbitrage-service.integration.test.d.ts +12 -0
  4. package/dist/__tests__/integration/arbitrage-service.integration.test.d.ts.map +1 -0
  5. package/dist/__tests__/integration/arbitrage-service.integration.test.js +267 -0
  6. package/dist/__tests__/integration/arbitrage-service.integration.test.js.map +1 -0
  7. package/dist/__tests__/integration/data-api.integration.test.js +6 -3
  8. package/dist/__tests__/integration/data-api.integration.test.js.map +1 -1
  9. package/dist/__tests__/integration/market-service.integration.test.d.ts +10 -0
  10. package/dist/__tests__/integration/market-service.integration.test.d.ts.map +1 -0
  11. package/dist/__tests__/integration/market-service.integration.test.js +173 -0
  12. package/dist/__tests__/integration/market-service.integration.test.js.map +1 -0
  13. package/dist/__tests__/integration/realtime-service-v2.integration.test.d.ts +10 -0
  14. package/dist/__tests__/integration/realtime-service-v2.integration.test.d.ts.map +1 -0
  15. package/dist/__tests__/integration/realtime-service-v2.integration.test.js +307 -0
  16. package/dist/__tests__/integration/realtime-service-v2.integration.test.js.map +1 -0
  17. package/dist/__tests__/integration/trading-service.integration.test.d.ts +10 -0
  18. package/dist/__tests__/integration/trading-service.integration.test.d.ts.map +1 -0
  19. package/dist/__tests__/integration/trading-service.integration.test.js +58 -0
  20. package/dist/__tests__/integration/trading-service.integration.test.js.map +1 -0
  21. package/dist/clients/clob-api.d.ts +73 -0
  22. package/dist/clients/clob-api.d.ts.map +1 -1
  23. package/dist/clients/clob-api.js +60 -0
  24. package/dist/clients/clob-api.js.map +1 -1
  25. package/dist/clients/ctf-client.d.ts +6 -4
  26. package/dist/clients/ctf-client.d.ts.map +1 -1
  27. package/dist/clients/ctf-client.js.map +1 -1
  28. package/dist/clients/data-api.d.ts +333 -15
  29. package/dist/clients/data-api.d.ts.map +1 -1
  30. package/dist/clients/data-api.js +398 -26
  31. package/dist/clients/data-api.js.map +1 -1
  32. package/dist/clients/gamma-api.d.ts +5 -0
  33. package/dist/clients/gamma-api.d.ts.map +1 -1
  34. package/dist/clients/gamma-api.js +2 -0
  35. package/dist/clients/gamma-api.js.map +1 -1
  36. package/dist/clients/subgraph.d.ts +196 -0
  37. package/dist/clients/subgraph.d.ts.map +1 -0
  38. package/dist/clients/subgraph.js +332 -0
  39. package/dist/clients/subgraph.js.map +1 -0
  40. package/dist/clients/websocket-manager.d.ts +3 -0
  41. package/dist/clients/websocket-manager.d.ts.map +1 -1
  42. package/dist/clients/websocket-manager.js +10 -3
  43. package/dist/clients/websocket-manager.js.map +1 -1
  44. package/dist/core/cache.d.ts +3 -0
  45. package/dist/core/cache.d.ts.map +1 -1
  46. package/dist/core/cache.js +5 -0
  47. package/dist/core/cache.js.map +1 -1
  48. package/dist/core/errors.d.ts +2 -1
  49. package/dist/core/errors.d.ts.map +1 -1
  50. package/dist/core/errors.js +2 -0
  51. package/dist/core/errors.js.map +1 -1
  52. package/dist/core/rate-limiter.d.ts +3 -1
  53. package/dist/core/rate-limiter.d.ts.map +1 -1
  54. package/dist/core/rate-limiter.js +12 -0
  55. package/dist/core/rate-limiter.js.map +1 -1
  56. package/dist/core/types.d.ts +205 -13
  57. package/dist/core/types.d.ts.map +1 -1
  58. package/dist/core/types.js +30 -0
  59. package/dist/core/types.js.map +1 -1
  60. package/dist/core/types.test.d.ts +7 -0
  61. package/dist/core/types.test.d.ts.map +1 -0
  62. package/dist/core/types.test.js +122 -0
  63. package/dist/core/types.test.js.map +1 -0
  64. package/dist/index.d.ts +84 -18
  65. package/dist/index.d.ts.map +1 -1
  66. package/dist/index.js +139 -132
  67. package/dist/index.js.map +1 -1
  68. package/dist/scripts/dip-arb/auto-trade.d.ts +20 -0
  69. package/dist/scripts/dip-arb/auto-trade.d.ts.map +1 -0
  70. package/dist/scripts/dip-arb/auto-trade.js +373 -0
  71. package/dist/scripts/dip-arb/auto-trade.js.map +1 -0
  72. package/dist/scripts/dip-arb/example-basic.d.ts +30 -0
  73. package/dist/scripts/dip-arb/example-basic.d.ts.map +1 -0
  74. package/dist/scripts/dip-arb/example-basic.js +222 -0
  75. package/dist/scripts/dip-arb/example-basic.js.map +1 -0
  76. package/dist/scripts/dip-arb/redeem-positions.d.ts +11 -0
  77. package/dist/scripts/dip-arb/redeem-positions.d.ts.map +1 -0
  78. package/dist/scripts/dip-arb/redeem-positions.js +201 -0
  79. package/dist/scripts/dip-arb/redeem-positions.js.map +1 -0
  80. package/dist/scripts/dip-arb/scan-markets.d.ts +6 -0
  81. package/dist/scripts/dip-arb/scan-markets.d.ts.map +1 -0
  82. package/dist/scripts/dip-arb/scan-markets.js +73 -0
  83. package/dist/scripts/dip-arb/scan-markets.js.map +1 -0
  84. package/dist/services/arbitrage-service.d.ts +3 -2
  85. package/dist/services/arbitrage-service.d.ts.map +1 -1
  86. package/dist/services/arbitrage-service.js +71 -43
  87. package/dist/services/arbitrage-service.js.map +1 -1
  88. package/dist/services/binance-service.d.ts +154 -0
  89. package/dist/services/binance-service.d.ts.map +1 -0
  90. package/dist/services/binance-service.js +266 -0
  91. package/dist/services/binance-service.js.map +1 -0
  92. package/dist/services/dip-arb-service.d.ts +209 -0
  93. package/dist/services/dip-arb-service.d.ts.map +1 -0
  94. package/dist/services/dip-arb-service.js +1602 -0
  95. package/dist/services/dip-arb-service.js.map +1 -0
  96. package/dist/services/dip-arb-types.d.ts +553 -0
  97. package/dist/services/dip-arb-types.d.ts.map +1 -0
  98. package/dist/services/dip-arb-types.js +164 -0
  99. package/dist/services/dip-arb-types.js.map +1 -0
  100. package/dist/services/market-service.d.ts +267 -8
  101. package/dist/services/market-service.d.ts.map +1 -1
  102. package/dist/services/market-service.js +771 -42
  103. package/dist/services/market-service.js.map +1 -1
  104. package/dist/services/onchain-service.d.ts +309 -0
  105. package/dist/services/onchain-service.d.ts.map +1 -0
  106. package/dist/services/onchain-service.js +417 -0
  107. package/dist/services/onchain-service.js.map +1 -0
  108. package/dist/services/realtime-service-v2.d.ts +362 -0
  109. package/dist/services/realtime-service-v2.d.ts.map +1 -0
  110. package/dist/services/realtime-service-v2.js +858 -0
  111. package/dist/services/realtime-service-v2.js.map +1 -0
  112. package/dist/services/realtime-service.d.ts +17 -17
  113. package/dist/services/realtime-service.d.ts.map +1 -1
  114. package/dist/services/realtime-service.js +91 -59
  115. package/dist/services/realtime-service.js.map +1 -1
  116. package/dist/services/smart-money-service.d.ts +352 -0
  117. package/dist/services/smart-money-service.d.ts.map +1 -0
  118. package/dist/services/smart-money-service.js +582 -0
  119. package/dist/services/smart-money-service.js.map +1 -0
  120. package/dist/services/trading-service.d.ts +177 -0
  121. package/dist/services/trading-service.d.ts.map +1 -0
  122. package/dist/services/trading-service.js +422 -0
  123. package/dist/services/trading-service.js.map +1 -0
  124. package/dist/services/wallet-service.d.ts +225 -3
  125. package/dist/services/wallet-service.d.ts.map +1 -1
  126. package/dist/services/wallet-service.js +511 -3
  127. package/dist/services/wallet-service.js.map +1 -1
  128. package/dist/src/__tests__/integration/arbitrage-service.integration.test.d.ts +12 -0
  129. package/dist/src/__tests__/integration/arbitrage-service.integration.test.d.ts.map +1 -0
  130. package/dist/src/__tests__/integration/arbitrage-service.integration.test.js +267 -0
  131. package/dist/src/__tests__/integration/arbitrage-service.integration.test.js.map +1 -0
  132. package/dist/src/__tests__/integration/bridge-client.integration.test.d.ts +11 -0
  133. package/dist/src/__tests__/integration/bridge-client.integration.test.d.ts.map +1 -0
  134. package/dist/src/__tests__/integration/bridge-client.integration.test.js +260 -0
  135. package/dist/src/__tests__/integration/bridge-client.integration.test.js.map +1 -0
  136. package/dist/src/__tests__/integration/ctf-client.integration.test.d.ts +17 -0
  137. package/dist/src/__tests__/integration/ctf-client.integration.test.d.ts.map +1 -0
  138. package/dist/src/__tests__/integration/ctf-client.integration.test.js +234 -0
  139. package/dist/src/__tests__/integration/ctf-client.integration.test.js.map +1 -0
  140. package/dist/src/__tests__/integration/data-api.integration.test.d.ts +9 -0
  141. package/dist/src/__tests__/integration/data-api.integration.test.d.ts.map +1 -0
  142. package/dist/src/__tests__/integration/data-api.integration.test.js +164 -0
  143. package/dist/src/__tests__/integration/data-api.integration.test.js.map +1 -0
  144. package/dist/src/__tests__/integration/gamma-api.integration.test.d.ts +9 -0
  145. package/dist/src/__tests__/integration/gamma-api.integration.test.d.ts.map +1 -0
  146. package/dist/src/__tests__/integration/gamma-api.integration.test.js +170 -0
  147. package/dist/src/__tests__/integration/gamma-api.integration.test.js.map +1 -0
  148. package/dist/src/__tests__/integration/market-service.integration.test.d.ts +10 -0
  149. package/dist/src/__tests__/integration/market-service.integration.test.d.ts.map +1 -0
  150. package/dist/src/__tests__/integration/market-service.integration.test.js +180 -0
  151. package/dist/src/__tests__/integration/market-service.integration.test.js.map +1 -0
  152. package/dist/src/__tests__/integration/realtime-service-v2.integration.test.d.ts +10 -0
  153. package/dist/src/__tests__/integration/realtime-service-v2.integration.test.d.ts.map +1 -0
  154. package/dist/src/__tests__/integration/realtime-service-v2.integration.test.js +307 -0
  155. package/dist/src/__tests__/integration/realtime-service-v2.integration.test.js.map +1 -0
  156. package/dist/src/__tests__/integration/trading-service.integration.test.d.ts +10 -0
  157. package/dist/src/__tests__/integration/trading-service.integration.test.d.ts.map +1 -0
  158. package/dist/src/__tests__/integration/trading-service.integration.test.js +58 -0
  159. package/dist/src/__tests__/integration/trading-service.integration.test.js.map +1 -0
  160. package/dist/src/__tests__/test-utils.d.ts +92 -0
  161. package/dist/src/__tests__/test-utils.d.ts.map +1 -0
  162. package/dist/src/__tests__/test-utils.js +143 -0
  163. package/dist/src/__tests__/test-utils.js.map +1 -0
  164. package/dist/src/clients/bridge-client.d.ts +388 -0
  165. package/dist/src/clients/bridge-client.d.ts.map +1 -0
  166. package/dist/src/clients/bridge-client.js +587 -0
  167. package/dist/src/clients/bridge-client.js.map +1 -0
  168. package/dist/src/clients/ctf-client.d.ts +475 -0
  169. package/dist/src/clients/ctf-client.d.ts.map +1 -0
  170. package/dist/src/clients/ctf-client.js +915 -0
  171. package/dist/src/clients/ctf-client.js.map +1 -0
  172. package/dist/src/clients/data-api.d.ts +452 -0
  173. package/dist/src/clients/data-api.d.ts.map +1 -0
  174. package/dist/src/clients/data-api.js +637 -0
  175. package/dist/src/clients/data-api.js.map +1 -0
  176. package/dist/src/clients/gamma-api.d.ts +421 -0
  177. package/dist/src/clients/gamma-api.d.ts.map +1 -0
  178. package/dist/src/clients/gamma-api.js +359 -0
  179. package/dist/src/clients/gamma-api.js.map +1 -0
  180. package/dist/src/clients/subgraph.d.ts +196 -0
  181. package/dist/src/clients/subgraph.d.ts.map +1 -0
  182. package/dist/src/clients/subgraph.js +332 -0
  183. package/dist/src/clients/subgraph.js.map +1 -0
  184. package/dist/src/core/cache-adapter-bridge.d.ts +36 -0
  185. package/dist/src/core/cache-adapter-bridge.d.ts.map +1 -0
  186. package/dist/src/core/cache-adapter-bridge.js +81 -0
  187. package/dist/src/core/cache-adapter-bridge.js.map +1 -0
  188. package/dist/src/core/cache.d.ts +43 -0
  189. package/dist/src/core/cache.d.ts.map +1 -0
  190. package/dist/src/core/cache.js +76 -0
  191. package/dist/src/core/cache.js.map +1 -0
  192. package/dist/src/core/errors.d.ts +39 -0
  193. package/dist/src/core/errors.d.ts.map +1 -0
  194. package/dist/src/core/errors.js +86 -0
  195. package/dist/src/core/errors.js.map +1 -0
  196. package/dist/src/core/rate-limiter.d.ts +33 -0
  197. package/dist/src/core/rate-limiter.d.ts.map +1 -0
  198. package/dist/src/core/rate-limiter.js +82 -0
  199. package/dist/src/core/rate-limiter.js.map +1 -0
  200. package/dist/src/core/types.d.ts +506 -0
  201. package/dist/src/core/types.d.ts.map +1 -0
  202. package/dist/src/core/types.js +49 -0
  203. package/dist/src/core/types.js.map +1 -0
  204. package/dist/src/core/types.test.d.ts +7 -0
  205. package/dist/src/core/types.test.d.ts.map +1 -0
  206. package/dist/src/core/types.test.js +122 -0
  207. package/dist/src/core/types.test.js.map +1 -0
  208. package/dist/src/core/unified-cache.d.ts +63 -0
  209. package/dist/src/core/unified-cache.d.ts.map +1 -0
  210. package/dist/src/core/unified-cache.js +114 -0
  211. package/dist/src/core/unified-cache.js.map +1 -0
  212. package/dist/src/index.d.ts +159 -0
  213. package/dist/src/index.d.ts.map +1 -0
  214. package/dist/src/index.js +262 -0
  215. package/dist/src/index.js.map +1 -0
  216. package/dist/src/services/arbitrage-service.d.ts +409 -0
  217. package/dist/src/services/arbitrage-service.d.ts.map +1 -0
  218. package/dist/src/services/arbitrage-service.js +1450 -0
  219. package/dist/src/services/arbitrage-service.js.map +1 -0
  220. package/dist/src/services/authorization-service.d.ts +97 -0
  221. package/dist/src/services/authorization-service.d.ts.map +1 -0
  222. package/dist/src/services/authorization-service.js +279 -0
  223. package/dist/src/services/authorization-service.js.map +1 -0
  224. package/dist/src/services/binance-service.d.ts +154 -0
  225. package/dist/src/services/binance-service.d.ts.map +1 -0
  226. package/dist/src/services/binance-service.js +266 -0
  227. package/dist/src/services/binance-service.js.map +1 -0
  228. package/dist/src/services/dip-arb-service.d.ts +245 -0
  229. package/dist/src/services/dip-arb-service.d.ts.map +1 -0
  230. package/dist/src/services/dip-arb-service.js +1865 -0
  231. package/dist/src/services/dip-arb-service.js.map +1 -0
  232. package/dist/src/services/dip-arb-types.d.ts +553 -0
  233. package/dist/src/services/dip-arb-types.d.ts.map +1 -0
  234. package/dist/src/services/dip-arb-types.js +164 -0
  235. package/dist/src/services/dip-arb-types.js.map +1 -0
  236. package/dist/src/services/market-service.d.ts +370 -0
  237. package/dist/src/services/market-service.d.ts.map +1 -0
  238. package/dist/src/services/market-service.js +1200 -0
  239. package/dist/src/services/market-service.js.map +1 -0
  240. package/dist/src/services/onchain-service.d.ts +309 -0
  241. package/dist/src/services/onchain-service.d.ts.map +1 -0
  242. package/dist/src/services/onchain-service.js +417 -0
  243. package/dist/src/services/onchain-service.js.map +1 -0
  244. package/dist/src/services/realtime-service-v2.d.ts +367 -0
  245. package/dist/src/services/realtime-service-v2.d.ts.map +1 -0
  246. package/dist/src/services/realtime-service-v2.js +876 -0
  247. package/dist/src/services/realtime-service-v2.js.map +1 -0
  248. package/dist/src/services/smart-money-service.d.ts +352 -0
  249. package/dist/src/services/smart-money-service.d.ts.map +1 -0
  250. package/dist/src/services/smart-money-service.js +582 -0
  251. package/dist/src/services/smart-money-service.js.map +1 -0
  252. package/dist/src/services/swap-service.d.ts +217 -0
  253. package/dist/src/services/swap-service.d.ts.map +1 -0
  254. package/dist/src/services/swap-service.js +695 -0
  255. package/dist/src/services/swap-service.js.map +1 -0
  256. package/dist/src/services/trading-service.d.ts +177 -0
  257. package/dist/src/services/trading-service.d.ts.map +1 -0
  258. package/dist/src/services/trading-service.js +422 -0
  259. package/dist/src/services/trading-service.js.map +1 -0
  260. package/dist/src/services/wallet-service.d.ts +316 -0
  261. package/dist/src/services/wallet-service.d.ts.map +1 -0
  262. package/dist/src/services/wallet-service.js +681 -0
  263. package/dist/src/services/wallet-service.js.map +1 -0
  264. package/dist/src/utils/price-utils.d.ts +153 -0
  265. package/dist/src/utils/price-utils.d.ts.map +1 -0
  266. package/dist/src/utils/price-utils.js +236 -0
  267. package/dist/src/utils/price-utils.js.map +1 -0
  268. package/dist/src/utils/price-utils.test.d.ts +5 -0
  269. package/dist/src/utils/price-utils.test.d.ts.map +1 -0
  270. package/dist/src/utils/price-utils.test.js +192 -0
  271. package/dist/src/utils/price-utils.test.js.map +1 -0
  272. package/dist/utils/price-utils.test.d.ts +5 -0
  273. package/dist/utils/price-utils.test.d.ts.map +1 -0
  274. package/dist/utils/price-utils.test.js +192 -0
  275. package/dist/utils/price-utils.test.js.map +1 -0
  276. package/package.json +6 -5
  277. package/README.en.md +0 -502
@@ -6,9 +6,88 @@
6
6
  * - Position tracking
7
7
  * - Activity monitoring
8
8
  * - Sell detection for follow wallet strategy
9
+ * - Time-based leaderboard and wallet stats
9
10
  */
10
- import { DataApiClient, Position, Activity, LeaderboardEntry, LeaderboardPage } from '../clients/data-api.js';
11
+ import { DataApiClient, Position, Activity, LeaderboardEntry, LeaderboardPage, LeaderboardTimePeriod, LeaderboardOrderBy, LeaderboardCategory } from '../clients/data-api.js';
12
+ import { SubgraphClient } from '../clients/subgraph.js';
11
13
  import type { UnifiedCache } from '../core/unified-cache.js';
14
+ /** Time period (lowercase for SDK, maps to API's uppercase) */
15
+ export type TimePeriod = 'day' | 'week' | 'month' | 'all';
16
+ /** Sort criteria for period leaderboard (official API supports PNL and VOL) */
17
+ export type LeaderboardSortBy = 'volume' | 'pnl';
18
+ export type { LeaderboardTimePeriod, LeaderboardOrderBy, LeaderboardCategory };
19
+ /**
20
+ * Parsed trade from OrderFilledEvent
21
+ */
22
+ export interface ParsedTrade {
23
+ timestamp: number;
24
+ user: string;
25
+ role: 'maker' | 'taker';
26
+ side: 'BUY' | 'SELL';
27
+ tokenId: string;
28
+ tokenAmount: number;
29
+ usdcAmount: number;
30
+ price: number;
31
+ }
32
+ /**
33
+ * Position tracking for PnL calculation
34
+ */
35
+ export interface TokenPosition {
36
+ tokenId: string;
37
+ amount: number;
38
+ avgCost: number;
39
+ totalCost: number;
40
+ realizedPnl: number;
41
+ }
42
+ /**
43
+ * User stats with PnL
44
+ */
45
+ export interface UserPeriodStats {
46
+ address: string;
47
+ volume: number;
48
+ tradeCount: number;
49
+ buyCount: number;
50
+ sellCount: number;
51
+ buyVolume: number;
52
+ sellVolume: number;
53
+ realizedPnl: number;
54
+ unrealizedPnl: number;
55
+ positions: Map<string, TokenPosition>;
56
+ }
57
+ export interface PeriodLeaderboardEntry {
58
+ address: string;
59
+ rank: number;
60
+ volume: number;
61
+ pnl: number;
62
+ totalPnl: number;
63
+ realizedPnl: number;
64
+ unrealizedPnl: number;
65
+ tradeCount: number;
66
+ buyCount: number;
67
+ sellCount: number;
68
+ buyVolume: number;
69
+ sellVolume: number;
70
+ makerVolume: number;
71
+ takerVolume: number;
72
+ userName?: string;
73
+ profileImage?: string;
74
+ }
75
+ export interface WalletPeriodStats {
76
+ address: string;
77
+ period: TimePeriod;
78
+ startTime: number;
79
+ endTime: number;
80
+ volume: number;
81
+ tradeCount: number;
82
+ makerVolume: number;
83
+ takerVolume: number;
84
+ makerCount: number;
85
+ takerCount: number;
86
+ splitCount: number;
87
+ mergeCount: number;
88
+ redemptionCount: number;
89
+ redemptionPayout: number;
90
+ }
12
91
  export interface WalletProfile {
13
92
  address: string;
14
93
  totalPnL: number;
@@ -20,6 +99,26 @@ export interface WalletProfile {
20
99
  smartScore: number;
21
100
  lastActiveAt: Date;
22
101
  }
102
+ export interface WalletActivityOptions {
103
+ /** Maximum number of activities to return */
104
+ limit?: number;
105
+ /** Pagination offset */
106
+ offset?: number;
107
+ /** Start timestamp (Unix seconds) - filter activities after this time */
108
+ start?: number;
109
+ /** End timestamp (Unix seconds) - filter activities before this time */
110
+ end?: number;
111
+ /** Filter by activity type */
112
+ type?: 'TRADE' | 'SPLIT' | 'MERGE' | 'REDEEM' | 'REWARD' | 'CONVERSION';
113
+ /** Filter by trade side */
114
+ side?: 'BUY' | 'SELL';
115
+ /** Filter by market conditionId */
116
+ market?: string;
117
+ /** Fetch all activities with auto-pagination (up to maxItems) */
118
+ fetchAll?: boolean;
119
+ /** Maximum items when fetchAll=true (default 10000) */
120
+ maxItems?: number;
121
+ }
23
122
  export interface WalletActivitySummary {
24
123
  address: string;
25
124
  activities: Activity[];
@@ -30,6 +129,11 @@ export interface WalletActivitySummary {
30
129
  sellVolume: number;
31
130
  activeMarkets: string[];
32
131
  };
132
+ /** Time range of returned activities */
133
+ timeRange?: {
134
+ earliest: Date;
135
+ latest: Date;
136
+ };
33
137
  }
34
138
  export interface SellActivityResult {
35
139
  totalSellAmount: number;
@@ -39,8 +143,13 @@ export interface SellActivityResult {
39
143
  }
40
144
  export declare class WalletService {
41
145
  private dataApi;
146
+ private subgraph;
42
147
  private cache;
43
- constructor(dataApi: DataApiClient, cache: UnifiedCache);
148
+ constructor(dataApi: DataApiClient, subgraph: SubgraphClient, cache: UnifiedCache);
149
+ /**
150
+ * Get start timestamp for a time period
151
+ */
152
+ private getPeriodStartTime;
44
153
  /**
45
154
  * Get comprehensive wallet profile with PnL analysis
46
155
  */
@@ -55,8 +164,24 @@ export declare class WalletService {
55
164
  getPositionsForMarket(address: string, conditionId: string): Promise<Position[]>;
56
165
  /**
57
166
  * Get wallet activity with summary
167
+ *
168
+ * @param address - Wallet address
169
+ * @param options - Activity query options (limit, start, end, type, side, market, fetchAll)
170
+ *
171
+ * @example
172
+ * ```typescript
173
+ * // Get recent 100 activities
174
+ * const activity = await walletService.getWalletActivity(address);
175
+ *
176
+ * // Get activities from past week
177
+ * const oneWeekAgo = Math.floor(Date.now() / 1000) - 7 * 24 * 60 * 60;
178
+ * const weekActivity = await walletService.getWalletActivity(address, { start: oneWeekAgo });
179
+ *
180
+ * // Get all activities (auto-pagination, up to API limit)
181
+ * const allActivity = await walletService.getWalletActivity(address, { fetchAll: true });
182
+ * ```
58
183
  */
59
- getWalletActivity(address: string, limit?: number): Promise<WalletActivitySummary>;
184
+ getWalletActivity(address: string, options?: WalletActivityOptions | number): Promise<WalletActivitySummary>;
60
185
  /**
61
186
  * Get leaderboard
62
187
  */
@@ -65,6 +190,103 @@ export declare class WalletService {
65
190
  * Get top traders from leaderboard
66
191
  */
67
192
  getTopTraders(limit?: number): Promise<LeaderboardEntry[]>;
193
+ /**
194
+ * Get leaderboard by time period using official Polymarket API
195
+ *
196
+ * Uses the official Data API which supports time period filtering.
197
+ * This is the recommended method as it uses server-side calculations.
198
+ *
199
+ * @param period - Time period: 'day', 'week', 'month', or 'all'
200
+ * @param limit - Maximum entries to return (default: 50, max: 50)
201
+ * @param sortBy - Sort criteria: 'volume' or 'pnl' (default: 'pnl')
202
+ * @param category - Market category filter (default: 'OVERALL')
203
+ *
204
+ * @example
205
+ * ```typescript
206
+ * // Get top traders of the week by PnL
207
+ * const weeklyByPnl = await walletService.getLeaderboardByPeriod('week', 20, 'pnl');
208
+ *
209
+ * // Get top traders by volume
210
+ * const weeklyByVolume = await walletService.getLeaderboardByPeriod('week', 20, 'volume');
211
+ *
212
+ * // Get politics category leaderboard
213
+ * const politics = await walletService.getLeaderboardByPeriod('week', 20, 'pnl', 'POLITICS');
214
+ * ```
215
+ */
216
+ getLeaderboardByPeriod(period: TimePeriod, limit?: number, sortBy?: LeaderboardSortBy, category?: LeaderboardCategory, offset?: number): Promise<PeriodLeaderboardEntry[]>;
217
+ /**
218
+ * Get a specific user's PnL and ranking for a time period
219
+ *
220
+ * Uses the official Data API's user filter to get a single user's stats.
221
+ *
222
+ * @param address - User's wallet address
223
+ * @param period - Time period: 'day', 'week', 'month', or 'all'
224
+ * @param category - Market category filter (default: 'OVERALL')
225
+ *
226
+ * @example
227
+ * ```typescript
228
+ * // Get user's weekly PnL
229
+ * const stats = await walletService.getUserPeriodPnl(address, 'week');
230
+ * console.log(`Rank: #${stats.rank}, PnL: $${stats.pnl}`);
231
+ *
232
+ * // Get user's monthly PnL in politics category
233
+ * const politicsStats = await walletService.getUserPeriodPnl(address, 'month', 'POLITICS');
234
+ * ```
235
+ */
236
+ getUserPeriodPnl(address: string, period: TimePeriod, category?: LeaderboardCategory): Promise<PeriodLeaderboardEntry | null>;
237
+ /**
238
+ * Get wallet stats for a specific time period
239
+ *
240
+ * Combines data from Orderbook Subgraph (trades) and Activity Subgraph (splits/merges/redemptions)
241
+ *
242
+ * @param address - Wallet address
243
+ * @param period - Time period: 'day', 'week', 'month', or 'all'
244
+ *
245
+ * @example
246
+ * ```typescript
247
+ * // Get wallet's monthly stats
248
+ * const stats = await walletService.getWalletStatsByPeriod(address, 'month');
249
+ * console.log(`Monthly volume: $${stats.volume}`);
250
+ * ```
251
+ */
252
+ getWalletStatsByPeriod(address: string, period: TimePeriod): Promise<WalletPeriodStats>;
253
+ /**
254
+ * Fetch all order filled events in a time period with pagination
255
+ */
256
+ private fetchAllFillsInPeriod;
257
+ /**
258
+ * Parse OrderFilledEvent into user trades
259
+ *
260
+ * OrderFilledEvent 结构:
261
+ * - makerAssetId = "0" (USDC): Maker 卖 USDC = BUY outcome token
262
+ * - makerAssetId = 长数字: Maker 卖 outcome token = SELL
263
+ */
264
+ private parseOrderFilledEvent;
265
+ /**
266
+ * Update position with a trade and calculate realized PnL
267
+ *
268
+ * 买入: 增加持仓,更新平均成本
269
+ * 卖出: 减少持仓,计算已实现盈亏 = 卖出收入 - 成本基础
270
+ */
271
+ private updatePositionWithTrade;
272
+ /**
273
+ * Calculate unrealized PnL for a position
274
+ *
275
+ * 未实现盈亏 = 当前市值 - 总成本
276
+ * 假设当前价格约等于最后交易价格 (简化处理)
277
+ */
278
+ private calculateUnrealizedPnl;
279
+ /**
280
+ * Aggregate user statistics with PnL calculation from order filled events
281
+ *
282
+ * 核心计算流程:
283
+ * 1. 解析 OrderFilledEvent 为标准化的 ParsedTrade
284
+ * 2. 按时间顺序处理每笔交易
285
+ * 3. 追踪每个用户每个 token 的持仓和平均成本
286
+ * 4. 卖出时计算已实现盈亏
287
+ * 5. 期末计算未实现盈亏
288
+ */
289
+ private aggregateUserStatsWithPnl;
68
290
  /**
69
291
  * Discover active wallets from recent trades
70
292
  */
@@ -1 +1 @@
1
- {"version":3,"file":"wallet-service.d.ts","sourceRoot":"","sources":["../../src/services/wallet-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,QAAQ,EAAE,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,qBAAa,aAAa;IAEtB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,KAAK;gBADL,OAAO,EAAE,aAAa,EACtB,KAAK,EAAE,YAAY;IAK7B;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA8B/D;;OAEG;IACG,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI9D;;OAEG;IACG,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAKtF;;OAEG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAqBrF;;OAEG;IACG,cAAc,CAAC,IAAI,SAAI,EAAE,QAAQ,SAAK,GAAG,OAAO,CAAC,eAAe,CAAC;IAIvE;;OAEG;IACG,aAAa,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAK5D;;OAEG;IACG,qBAAqB,CAAC,KAAK,SAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAoBjG;;OAEG;IACG,kBAAkB,CACtB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,kBAAkB,CAAC;IAoB9B;;OAEG;IACG,mBAAmB,CACvB,SAAS,EAAE,MAAM,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC;QACT,oBAAoB,EAAE,MAAM,CAAC;QAC7B,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,OAAO,CAAC;QACpB,WAAW,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAC7D,CAAC;IAsBF,OAAO,CAAC,mBAAmB;IA2B3B,OAAO,CAAC,iBAAiB;CAK1B"}
1
+ {"version":3,"file":"wallet-service.d.ts","sourceRoot":"","sources":["../../src/services/wallet-service.ts"],"names":[],"mappings":"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"}