@catalyst-team/poly-sdk 0.1.0 → 0.2.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 (201) hide show
  1. package/LICENSE +21 -0
  2. package/README.en.md +538 -0
  3. package/README.md +357 -78
  4. package/docs/00-design.md +1 -1
  5. package/docs/02-API.md +21 -21
  6. package/docs/arb/test-plan.md +387 -0
  7. package/docs/arb/test-results.md +336 -0
  8. package/docs/arbitrage.md +754 -0
  9. package/docs/reports/smart-money-analysis-2025-12-23-cn.md +840 -0
  10. package/examples/13-arbitrage-service.ts +211 -0
  11. package/examples/README.md +1 -1
  12. package/package.json +19 -19
  13. package/scripts/arb/faze-bo3-arb.ts +385 -0
  14. package/scripts/arb/settle-position.ts +190 -0
  15. package/scripts/arb/token-rebalancer.ts +420 -0
  16. package/scripts/arb-tests/01-unit-tests.ts +495 -0
  17. package/scripts/arb-tests/02-integration-tests.ts +412 -0
  18. package/scripts/arb-tests/03-e2e-tests.ts +503 -0
  19. package/scripts/arb-tests/README.md +109 -0
  20. package/scripts/verify/verify-all-apis.ts +1 -1
  21. package/src/clients/clob-api.ts +1 -1
  22. package/src/clients/gamma-api.ts +1 -1
  23. package/src/core/cache-adapter-bridge.ts +1 -1
  24. package/src/core/types.ts +3 -3
  25. package/src/core/unified-cache.ts +1 -1
  26. package/src/index.ts +25 -19
  27. package/src/services/arbitrage-service.ts +1807 -0
  28. package/.env +0 -0
  29. package/dist/__tests__/clob-api.test.d.ts +0 -5
  30. package/dist/__tests__/clob-api.test.d.ts.map +0 -1
  31. package/dist/__tests__/clob-api.test.js +0 -240
  32. package/dist/__tests__/clob-api.test.js.map +0 -1
  33. package/dist/__tests__/integration/bridge-client.integration.test.d.ts +0 -11
  34. package/dist/__tests__/integration/bridge-client.integration.test.d.ts.map +0 -1
  35. package/dist/__tests__/integration/bridge-client.integration.test.js +0 -260
  36. package/dist/__tests__/integration/bridge-client.integration.test.js.map +0 -1
  37. package/dist/__tests__/integration/clob-api.integration.test.d.ts +0 -13
  38. package/dist/__tests__/integration/clob-api.integration.test.d.ts.map +0 -1
  39. package/dist/__tests__/integration/clob-api.integration.test.js +0 -170
  40. package/dist/__tests__/integration/clob-api.integration.test.js.map +0 -1
  41. package/dist/__tests__/integration/ctf-client.integration.test.d.ts +0 -17
  42. package/dist/__tests__/integration/ctf-client.integration.test.d.ts.map +0 -1
  43. package/dist/__tests__/integration/ctf-client.integration.test.js +0 -234
  44. package/dist/__tests__/integration/ctf-client.integration.test.js.map +0 -1
  45. package/dist/__tests__/integration/data-api.integration.test.d.ts +0 -9
  46. package/dist/__tests__/integration/data-api.integration.test.d.ts.map +0 -1
  47. package/dist/__tests__/integration/data-api.integration.test.js +0 -161
  48. package/dist/__tests__/integration/data-api.integration.test.js.map +0 -1
  49. package/dist/__tests__/integration/gamma-api.integration.test.d.ts +0 -9
  50. package/dist/__tests__/integration/gamma-api.integration.test.d.ts.map +0 -1
  51. package/dist/__tests__/integration/gamma-api.integration.test.js +0 -170
  52. package/dist/__tests__/integration/gamma-api.integration.test.js.map +0 -1
  53. package/dist/__tests__/test-utils.d.ts +0 -92
  54. package/dist/__tests__/test-utils.d.ts.map +0 -1
  55. package/dist/__tests__/test-utils.js +0 -143
  56. package/dist/__tests__/test-utils.js.map +0 -1
  57. package/dist/clients/bridge-client.d.ts +0 -388
  58. package/dist/clients/bridge-client.d.ts.map +0 -1
  59. package/dist/clients/bridge-client.js +0 -587
  60. package/dist/clients/bridge-client.js.map +0 -1
  61. package/dist/clients/clob-api.d.ts +0 -318
  62. package/dist/clients/clob-api.d.ts.map +0 -1
  63. package/dist/clients/clob-api.js +0 -388
  64. package/dist/clients/clob-api.js.map +0 -1
  65. package/dist/clients/ctf-client.d.ts +0 -473
  66. package/dist/clients/ctf-client.d.ts.map +0 -1
  67. package/dist/clients/ctf-client.js +0 -915
  68. package/dist/clients/ctf-client.js.map +0 -1
  69. package/dist/clients/data-api.d.ts +0 -134
  70. package/dist/clients/data-api.d.ts.map +0 -1
  71. package/dist/clients/data-api.js +0 -265
  72. package/dist/clients/data-api.js.map +0 -1
  73. package/dist/clients/gamma-api.d.ts +0 -401
  74. package/dist/clients/gamma-api.d.ts.map +0 -1
  75. package/dist/clients/gamma-api.js +0 -352
  76. package/dist/clients/gamma-api.js.map +0 -1
  77. package/dist/clients/trading-client.d.ts +0 -252
  78. package/dist/clients/trading-client.d.ts.map +0 -1
  79. package/dist/clients/trading-client.js +0 -543
  80. package/dist/clients/trading-client.js.map +0 -1
  81. package/dist/clients/websocket-manager.d.ts +0 -100
  82. package/dist/clients/websocket-manager.d.ts.map +0 -1
  83. package/dist/clients/websocket-manager.js +0 -193
  84. package/dist/clients/websocket-manager.js.map +0 -1
  85. package/dist/core/cache-adapter-bridge.d.ts +0 -36
  86. package/dist/core/cache-adapter-bridge.d.ts.map +0 -1
  87. package/dist/core/cache-adapter-bridge.js +0 -81
  88. package/dist/core/cache-adapter-bridge.js.map +0 -1
  89. package/dist/core/cache.d.ts +0 -40
  90. package/dist/core/cache.d.ts.map +0 -1
  91. package/dist/core/cache.js +0 -71
  92. package/dist/core/cache.js.map +0 -1
  93. package/dist/core/errors.d.ts +0 -38
  94. package/dist/core/errors.d.ts.map +0 -1
  95. package/dist/core/errors.js +0 -84
  96. package/dist/core/errors.js.map +0 -1
  97. package/dist/core/rate-limiter.d.ts +0 -31
  98. package/dist/core/rate-limiter.d.ts.map +0 -1
  99. package/dist/core/rate-limiter.js +0 -70
  100. package/dist/core/rate-limiter.js.map +0 -1
  101. package/dist/core/types.d.ts +0 -314
  102. package/dist/core/types.d.ts.map +0 -1
  103. package/dist/core/types.js +0 -19
  104. package/dist/core/types.js.map +0 -1
  105. package/dist/core/unified-cache.d.ts +0 -63
  106. package/dist/core/unified-cache.d.ts.map +0 -1
  107. package/dist/core/unified-cache.js +0 -114
  108. package/dist/core/unified-cache.js.map +0 -1
  109. package/dist/index.d.ts +0 -94
  110. package/dist/index.d.ts.map +0 -1
  111. package/dist/index.js +0 -258
  112. package/dist/index.js.map +0 -1
  113. package/dist/mcp/errors.d.ts +0 -33
  114. package/dist/mcp/errors.d.ts.map +0 -1
  115. package/dist/mcp/errors.js +0 -86
  116. package/dist/mcp/errors.js.map +0 -1
  117. package/dist/mcp/index.d.ts +0 -62
  118. package/dist/mcp/index.d.ts.map +0 -1
  119. package/dist/mcp/index.js +0 -173
  120. package/dist/mcp/index.js.map +0 -1
  121. package/dist/mcp/server.d.ts +0 -17
  122. package/dist/mcp/server.d.ts.map +0 -1
  123. package/dist/mcp/server.js +0 -155
  124. package/dist/mcp/server.js.map +0 -1
  125. package/dist/mcp/tools/guide.d.ts +0 -12
  126. package/dist/mcp/tools/guide.d.ts.map +0 -1
  127. package/dist/mcp/tools/guide.js +0 -801
  128. package/dist/mcp/tools/guide.js.map +0 -1
  129. package/dist/mcp/tools/index.d.ts +0 -11
  130. package/dist/mcp/tools/index.d.ts.map +0 -1
  131. package/dist/mcp/tools/index.js +0 -27
  132. package/dist/mcp/tools/index.js.map +0 -1
  133. package/dist/mcp/tools/market.d.ts +0 -11
  134. package/dist/mcp/tools/market.d.ts.map +0 -1
  135. package/dist/mcp/tools/market.js +0 -314
  136. package/dist/mcp/tools/market.js.map +0 -1
  137. package/dist/mcp/tools/order.d.ts +0 -10
  138. package/dist/mcp/tools/order.d.ts.map +0 -1
  139. package/dist/mcp/tools/order.js +0 -258
  140. package/dist/mcp/tools/order.js.map +0 -1
  141. package/dist/mcp/tools/trade.d.ts +0 -38
  142. package/dist/mcp/tools/trade.d.ts.map +0 -1
  143. package/dist/mcp/tools/trade.js +0 -314
  144. package/dist/mcp/tools/trade.js.map +0 -1
  145. package/dist/mcp/tools/trader.d.ts +0 -11
  146. package/dist/mcp/tools/trader.d.ts.map +0 -1
  147. package/dist/mcp/tools/trader.js +0 -277
  148. package/dist/mcp/tools/trader.js.map +0 -1
  149. package/dist/mcp/tools/wallet.d.ts +0 -274
  150. package/dist/mcp/tools/wallet.d.ts.map +0 -1
  151. package/dist/mcp/tools/wallet.js +0 -579
  152. package/dist/mcp/tools/wallet.js.map +0 -1
  153. package/dist/mcp/types.d.ts +0 -413
  154. package/dist/mcp/types.d.ts.map +0 -1
  155. package/dist/mcp/types.js +0 -5
  156. package/dist/mcp/types.js.map +0 -1
  157. package/dist/services/authorization-service.d.ts +0 -97
  158. package/dist/services/authorization-service.d.ts.map +0 -1
  159. package/dist/services/authorization-service.js +0 -279
  160. package/dist/services/authorization-service.js.map +0 -1
  161. package/dist/services/market-service.d.ts +0 -108
  162. package/dist/services/market-service.d.ts.map +0 -1
  163. package/dist/services/market-service.js +0 -458
  164. package/dist/services/market-service.js.map +0 -1
  165. package/dist/services/realtime-service.d.ts +0 -82
  166. package/dist/services/realtime-service.d.ts.map +0 -1
  167. package/dist/services/realtime-service.js +0 -150
  168. package/dist/services/realtime-service.js.map +0 -1
  169. package/dist/services/swap-service.d.ts +0 -217
  170. package/dist/services/swap-service.d.ts.map +0 -1
  171. package/dist/services/swap-service.js +0 -695
  172. package/dist/services/swap-service.js.map +0 -1
  173. package/dist/services/wallet-service.d.ts +0 -94
  174. package/dist/services/wallet-service.d.ts.map +0 -1
  175. package/dist/services/wallet-service.js +0 -173
  176. package/dist/services/wallet-service.js.map +0 -1
  177. package/dist/utils/price-utils.d.ts +0 -153
  178. package/dist/utils/price-utils.d.ts.map +0 -1
  179. package/dist/utils/price-utils.js +0 -236
  180. package/dist/utils/price-utils.js.map +0 -1
  181. package/docs/01-mcp.md +0 -2041
  182. package/docs/e2e/01-trader-tools.md +0 -159
  183. package/docs/e2e/02-market-tools.md +0 -180
  184. package/docs/e2e/03-order-tools.md +0 -166
  185. package/docs/e2e/04-wallet-tools.md +0 -224
  186. package/docs/e2e/05-trading-tools.md +0 -327
  187. package/docs/e2e/06-integration-scenarios.md +0 -481
  188. package/docs/e2e/coordinator.md +0 -376
  189. package/scripts/truth.md +0 -440
  190. package/src/mcp/README.md +0 -380
  191. package/src/mcp/errors.ts +0 -124
  192. package/src/mcp/index.ts +0 -309
  193. package/src/mcp/server.ts +0 -183
  194. package/src/mcp/tools/guide.ts +0 -821
  195. package/src/mcp/tools/index.ts +0 -73
  196. package/src/mcp/tools/market.ts +0 -363
  197. package/src/mcp/tools/order.ts +0 -326
  198. package/src/mcp/tools/trade.ts +0 -417
  199. package/src/mcp/tools/trader.ts +0 -322
  200. package/src/mcp/tools/wallet.ts +0 -683
  201. package/src/mcp/types.ts +0 -472
package/src/mcp/types.ts DELETED
@@ -1,472 +0,0 @@
1
- /**
2
- * MCP Tool Types for Polymarket
3
- */
4
-
5
- // Tool Input Types
6
- export interface GetTraderPositionsInput {
7
- address: string;
8
- }
9
-
10
- export interface GetTraderTradesInput {
11
- address: string;
12
- limit?: number;
13
- side?: 'BUY' | 'SELL';
14
- }
15
-
16
- export interface GetTraderProfileInput {
17
- address: string;
18
- }
19
-
20
- export interface GetLeaderboardInput {
21
- limit?: number;
22
- offset?: number;
23
- }
24
-
25
- export interface GetMarketInput {
26
- identifier: string;
27
- }
28
-
29
- export interface SearchMarketsInput {
30
- query: string;
31
- active?: boolean;
32
- limit?: number;
33
- }
34
-
35
- export interface GetTrendingMarketsInput {
36
- limit?: number;
37
- sortBy?: 'volume' | 'liquidity' | 'newest';
38
- }
39
-
40
- export interface GetMarketTradesInput {
41
- conditionId: string;
42
- limit?: number;
43
- }
44
-
45
- export interface GetOrderbookInput {
46
- conditionId: string;
47
- outcome: 'Yes' | 'No';
48
- depth?: number;
49
- }
50
-
51
- export interface GetBestPricesInput {
52
- conditionId: string;
53
- }
54
-
55
- export interface EstimateExecutionInput {
56
- conditionId: string;
57
- outcome: 'Yes' | 'No';
58
- side: 'BUY' | 'SELL';
59
- amount: number;
60
- }
61
-
62
- export interface PlaceLimitOrderInput {
63
- conditionId: string;
64
- outcome: 'Yes' | 'No';
65
- side: 'BUY' | 'SELL';
66
- price: number;
67
- size: number;
68
- orderType?: 'GTC' | 'GTD';
69
- }
70
-
71
- export interface PlaceMarketOrderInput {
72
- conditionId: string;
73
- outcome: 'Yes' | 'No';
74
- side: 'BUY' | 'SELL';
75
- amount: number;
76
- maxSlippage?: number;
77
- }
78
-
79
- export interface CancelOrderInput {
80
- orderId: string;
81
- }
82
-
83
- export interface GetMyOrdersInput {
84
- status?: 'LIVE' | 'FILLED' | 'CANCELLED';
85
- }
86
-
87
- // Tool Output Types
88
- export interface TraderInfo {
89
- address: string;
90
- displayName: string | null;
91
- }
92
-
93
- export interface MarketInfo {
94
- conditionId: string;
95
- title: string;
96
- slug?: string;
97
- }
98
-
99
- export interface PositionHolding {
100
- outcome: string;
101
- size: number;
102
- avgPrice: number;
103
- curPrice?: number;
104
- }
105
-
106
- export interface PositionPnL {
107
- unrealized?: number;
108
- unrealizedPercent?: number;
109
- realized?: number;
110
- }
111
-
112
- export interface PositionStatus {
113
- redeemable?: boolean;
114
- endDate?: string;
115
- }
116
-
117
- export interface PositionOutput {
118
- market: MarketInfo;
119
- holding: PositionHolding;
120
- pnl: PositionPnL;
121
- status: PositionStatus;
122
- }
123
-
124
- export interface GetTraderPositionsOutput {
125
- trader: TraderInfo;
126
- positions: PositionOutput[];
127
- summary: {
128
- totalPositions: number;
129
- totalUnrealizedPnl: number;
130
- totalRealizedPnl: number;
131
- winningPositions: number;
132
- losingPositions: number;
133
- };
134
- }
135
-
136
- export interface TradeExecution {
137
- size: number;
138
- price: number;
139
- usdcValue: number;
140
- }
141
-
142
- export interface TradeOutput {
143
- type: string;
144
- side: 'BUY' | 'SELL';
145
- market: MarketInfo;
146
- outcome: string;
147
- execution: TradeExecution;
148
- timestamp: string;
149
- txHash: string;
150
- }
151
-
152
- export interface GetTraderTradesOutput {
153
- trader: TraderInfo;
154
- trades: TradeOutput[];
155
- summary: {
156
- totalTrades: number;
157
- buyCount: number;
158
- sellCount: number;
159
- buyVolume: number;
160
- sellVolume: number;
161
- };
162
- }
163
-
164
- export interface GetTraderProfileOutput {
165
- trader: {
166
- address: string;
167
- displayName: string | null;
168
- xUsername: string | null;
169
- verified: boolean;
170
- profileImage: string | null;
171
- };
172
- ranking: {
173
- rank: number | null;
174
- totalTraders: number;
175
- };
176
- performance: {
177
- officialPnl: number | null;
178
- totalVolume: number;
179
- unrealizedPnl: number;
180
- realizedPnl: number;
181
- };
182
- stats: {
183
- positionCount: number;
184
- winRate: number;
185
- avgPercentPnl: number;
186
- smartScore: number;
187
- };
188
- activity: {
189
- lastTradeAt: string | null;
190
- isActive: boolean;
191
- };
192
- /** Explanation when PnL values differ between sources */
193
- notes?: string;
194
- }
195
-
196
- export interface LeaderboardTrader {
197
- rank: number;
198
- address: string;
199
- displayName: string | null;
200
- pnl: number;
201
- volume: number;
202
- verified: boolean;
203
- }
204
-
205
- export interface GetLeaderboardOutput {
206
- traders: LeaderboardTrader[];
207
- pagination: {
208
- total: number;
209
- offset: number;
210
- limit: number;
211
- };
212
- }
213
-
214
- export interface TokenInfo {
215
- tokenId: string;
216
- price: number;
217
- }
218
-
219
- export interface GetMarketOutput {
220
- market: {
221
- conditionId: string;
222
- question: string;
223
- slug: string;
224
- description?: string;
225
- };
226
- prices: {
227
- yes: number;
228
- no: number;
229
- spread?: number;
230
- };
231
- tokens: {
232
- yes: TokenInfo;
233
- no: TokenInfo;
234
- };
235
- stats: {
236
- volume: number;
237
- liquidity: number;
238
- };
239
- status: {
240
- active: boolean;
241
- closed: boolean;
242
- acceptingOrders: boolean;
243
- endDate?: string;
244
- };
245
- trading: {
246
- minTickSize?: number;
247
- minOrderSize?: number;
248
- };
249
- }
250
-
251
- export interface SearchMarketResult {
252
- conditionId: string;
253
- question: string;
254
- slug: string;
255
- prices: { yes: number; no: number };
256
- volume: number;
257
- volume24h?: number;
258
- endDate?: string;
259
- }
260
-
261
- export interface SearchMarketsOutput {
262
- markets: SearchMarketResult[];
263
- total: number;
264
- }
265
-
266
- export interface TrendingMarket {
267
- conditionId: string;
268
- question: string;
269
- slug: string;
270
- volume24h?: number;
271
- priceChange24h?: number;
272
- prices: { yes: number; no: number };
273
- status?: {
274
- active: boolean;
275
- closed: boolean;
276
- endDate?: string;
277
- };
278
- }
279
-
280
- export interface GetTrendingMarketsOutput {
281
- markets: TrendingMarket[];
282
- }
283
-
284
- export interface MarketTradeOutput {
285
- trader: string;
286
- traderName?: string;
287
- side: 'BUY' | 'SELL';
288
- outcome: string;
289
- size: number;
290
- price: number;
291
- timestamp: string;
292
- }
293
-
294
- export interface GetMarketTradesOutput {
295
- market: MarketInfo;
296
- trades: MarketTradeOutput[];
297
- summary: {
298
- buyVolume24h: number;
299
- sellVolume24h: number;
300
- netFlow: number;
301
- };
302
- }
303
-
304
- export interface OrderbookLevel {
305
- price: number;
306
- size: number;
307
- total: number;
308
- }
309
-
310
- export interface GetOrderbookOutput {
311
- market: MarketInfo;
312
- outcome: string;
313
- tokenId: string;
314
- orderbook: {
315
- bids: OrderbookLevel[];
316
- asks: OrderbookLevel[];
317
- };
318
- summary: {
319
- bestBid: number;
320
- bestAsk: number;
321
- spread: number;
322
- spreadPercent: number;
323
- bidDepth: number;
324
- askDepth: number;
325
- };
326
- }
327
-
328
- export interface PriceInfo {
329
- bestBid: number;
330
- bestAsk: number;
331
- midPrice: number;
332
- spread: number;
333
- }
334
-
335
- export interface GetBestPricesOutput {
336
- market: string;
337
- yes: PriceInfo;
338
- no: PriceInfo;
339
- }
340
-
341
- export interface EstimateExecutionOutput {
342
- market: string;
343
- order: {
344
- side: 'BUY' | 'SELL';
345
- outcome: string;
346
- usdcAmount: number;
347
- };
348
- estimate: {
349
- avgPrice: number;
350
- sharesReceived: number;
351
- priceImpact: number;
352
- worstPrice: number;
353
- };
354
- warning: string | null;
355
- }
356
-
357
- // ===== Wallet Tool Types =====
358
-
359
- // Deposit Input/Output
360
- export interface GetSupportedAssetsInput {
361
- chainId?: number;
362
- }
363
-
364
- export interface SupportedAsset {
365
- chainId: number;
366
- chainName: string;
367
- tokenSymbol: string;
368
- tokenName: string;
369
- tokenAddress: string;
370
- decimals: number;
371
- minDeposit: string;
372
- minDepositUsd: number;
373
- }
374
-
375
- export interface GetSupportedAssetsOutput {
376
- assets: SupportedAsset[];
377
- summary: {
378
- totalChains: number;
379
- totalAssets: number;
380
- chains: string[];
381
- };
382
- }
383
-
384
- export interface GetDepositAddressesInput {
385
- // Uses wallet from SDK
386
- }
387
-
388
- export interface GetDepositAddressesOutput {
389
- wallet: string;
390
- addresses: {
391
- evm: string;
392
- solana: string;
393
- bitcoin: string;
394
- };
395
- evmChains: string[];
396
- instructions: string;
397
- }
398
-
399
- // Allowance Input/Output
400
- export interface CheckAllowancesInput {
401
- // Uses wallet from SDK
402
- }
403
-
404
- export interface AllowanceStatus {
405
- contract: string;
406
- address: string;
407
- approved: boolean;
408
- allowance?: string;
409
- }
410
-
411
- export interface CheckAllowancesOutput {
412
- wallet: string;
413
- erc20: {
414
- usdc: {
415
- balance: string;
416
- allowances: AllowanceStatus[];
417
- };
418
- };
419
- erc1155: {
420
- conditionalTokens: {
421
- approvals: AllowanceStatus[];
422
- };
423
- };
424
- tradingReady: boolean;
425
- issues: string[];
426
- }
427
-
428
- export interface ApproveTradingInput {
429
- // Uses wallet from SDK
430
- }
431
-
432
- export interface ApprovalResult {
433
- contract: string;
434
- txHash?: string;
435
- success: boolean;
436
- error?: string;
437
- }
438
-
439
- export interface ApproveTradingOutput {
440
- wallet: string;
441
- erc20Approvals: ApprovalResult[];
442
- erc1155Approvals: ApprovalResult[];
443
- allApproved: boolean;
444
- summary: string;
445
- }
446
-
447
- // Error Types
448
- export interface McpErrorResponse {
449
- error: {
450
- code: string;
451
- message: string;
452
- details?: Record<string, unknown>;
453
- };
454
- }
455
-
456
- export type McpToolResult<T> = T | McpErrorResponse;
457
-
458
- // Tool Definition Type
459
- export interface ToolDefinition {
460
- name: string;
461
- description: string;
462
- inputSchema: {
463
- type: 'object';
464
- properties: Record<string, {
465
- type: string;
466
- description?: string;
467
- enum?: string[];
468
- default?: unknown;
469
- }>;
470
- required?: string[];
471
- };
472
- }