@catalyst-team/poly-sdk 0.1.0 → 0.1.1

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 (194) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +354 -78
  3. package/docs/00-design.md +1 -1
  4. package/docs/02-API.md +21 -21
  5. package/docs/arbitrage.md +754 -0
  6. package/docs/reports/smart-money-analysis-2025-12-23-cn.md +840 -0
  7. package/examples/13-arbitrage-service.ts +211 -0
  8. package/examples/README.md +1 -1
  9. package/package.json +19 -19
  10. package/scripts/arb/faze-bo3-arb.ts +385 -0
  11. package/scripts/arb/settle-position.ts +190 -0
  12. package/scripts/arb/token-rebalancer.ts +420 -0
  13. package/scripts/verify/verify-all-apis.ts +1 -1
  14. package/src/clients/clob-api.ts +1 -1
  15. package/src/clients/gamma-api.ts +1 -1
  16. package/src/core/cache-adapter-bridge.ts +1 -1
  17. package/src/core/types.ts +3 -3
  18. package/src/core/unified-cache.ts +1 -1
  19. package/src/index.ts +25 -19
  20. package/src/services/arbitrage-service.ts +1807 -0
  21. package/.env +0 -0
  22. package/dist/__tests__/clob-api.test.d.ts +0 -5
  23. package/dist/__tests__/clob-api.test.d.ts.map +0 -1
  24. package/dist/__tests__/clob-api.test.js +0 -240
  25. package/dist/__tests__/clob-api.test.js.map +0 -1
  26. package/dist/__tests__/integration/bridge-client.integration.test.d.ts +0 -11
  27. package/dist/__tests__/integration/bridge-client.integration.test.d.ts.map +0 -1
  28. package/dist/__tests__/integration/bridge-client.integration.test.js +0 -260
  29. package/dist/__tests__/integration/bridge-client.integration.test.js.map +0 -1
  30. package/dist/__tests__/integration/clob-api.integration.test.d.ts +0 -13
  31. package/dist/__tests__/integration/clob-api.integration.test.d.ts.map +0 -1
  32. package/dist/__tests__/integration/clob-api.integration.test.js +0 -170
  33. package/dist/__tests__/integration/clob-api.integration.test.js.map +0 -1
  34. package/dist/__tests__/integration/ctf-client.integration.test.d.ts +0 -17
  35. package/dist/__tests__/integration/ctf-client.integration.test.d.ts.map +0 -1
  36. package/dist/__tests__/integration/ctf-client.integration.test.js +0 -234
  37. package/dist/__tests__/integration/ctf-client.integration.test.js.map +0 -1
  38. package/dist/__tests__/integration/data-api.integration.test.d.ts +0 -9
  39. package/dist/__tests__/integration/data-api.integration.test.d.ts.map +0 -1
  40. package/dist/__tests__/integration/data-api.integration.test.js +0 -161
  41. package/dist/__tests__/integration/data-api.integration.test.js.map +0 -1
  42. package/dist/__tests__/integration/gamma-api.integration.test.d.ts +0 -9
  43. package/dist/__tests__/integration/gamma-api.integration.test.d.ts.map +0 -1
  44. package/dist/__tests__/integration/gamma-api.integration.test.js +0 -170
  45. package/dist/__tests__/integration/gamma-api.integration.test.js.map +0 -1
  46. package/dist/__tests__/test-utils.d.ts +0 -92
  47. package/dist/__tests__/test-utils.d.ts.map +0 -1
  48. package/dist/__tests__/test-utils.js +0 -143
  49. package/dist/__tests__/test-utils.js.map +0 -1
  50. package/dist/clients/bridge-client.d.ts +0 -388
  51. package/dist/clients/bridge-client.d.ts.map +0 -1
  52. package/dist/clients/bridge-client.js +0 -587
  53. package/dist/clients/bridge-client.js.map +0 -1
  54. package/dist/clients/clob-api.d.ts +0 -318
  55. package/dist/clients/clob-api.d.ts.map +0 -1
  56. package/dist/clients/clob-api.js +0 -388
  57. package/dist/clients/clob-api.js.map +0 -1
  58. package/dist/clients/ctf-client.d.ts +0 -473
  59. package/dist/clients/ctf-client.d.ts.map +0 -1
  60. package/dist/clients/ctf-client.js +0 -915
  61. package/dist/clients/ctf-client.js.map +0 -1
  62. package/dist/clients/data-api.d.ts +0 -134
  63. package/dist/clients/data-api.d.ts.map +0 -1
  64. package/dist/clients/data-api.js +0 -265
  65. package/dist/clients/data-api.js.map +0 -1
  66. package/dist/clients/gamma-api.d.ts +0 -401
  67. package/dist/clients/gamma-api.d.ts.map +0 -1
  68. package/dist/clients/gamma-api.js +0 -352
  69. package/dist/clients/gamma-api.js.map +0 -1
  70. package/dist/clients/trading-client.d.ts +0 -252
  71. package/dist/clients/trading-client.d.ts.map +0 -1
  72. package/dist/clients/trading-client.js +0 -543
  73. package/dist/clients/trading-client.js.map +0 -1
  74. package/dist/clients/websocket-manager.d.ts +0 -100
  75. package/dist/clients/websocket-manager.d.ts.map +0 -1
  76. package/dist/clients/websocket-manager.js +0 -193
  77. package/dist/clients/websocket-manager.js.map +0 -1
  78. package/dist/core/cache-adapter-bridge.d.ts +0 -36
  79. package/dist/core/cache-adapter-bridge.d.ts.map +0 -1
  80. package/dist/core/cache-adapter-bridge.js +0 -81
  81. package/dist/core/cache-adapter-bridge.js.map +0 -1
  82. package/dist/core/cache.d.ts +0 -40
  83. package/dist/core/cache.d.ts.map +0 -1
  84. package/dist/core/cache.js +0 -71
  85. package/dist/core/cache.js.map +0 -1
  86. package/dist/core/errors.d.ts +0 -38
  87. package/dist/core/errors.d.ts.map +0 -1
  88. package/dist/core/errors.js +0 -84
  89. package/dist/core/errors.js.map +0 -1
  90. package/dist/core/rate-limiter.d.ts +0 -31
  91. package/dist/core/rate-limiter.d.ts.map +0 -1
  92. package/dist/core/rate-limiter.js +0 -70
  93. package/dist/core/rate-limiter.js.map +0 -1
  94. package/dist/core/types.d.ts +0 -314
  95. package/dist/core/types.d.ts.map +0 -1
  96. package/dist/core/types.js +0 -19
  97. package/dist/core/types.js.map +0 -1
  98. package/dist/core/unified-cache.d.ts +0 -63
  99. package/dist/core/unified-cache.d.ts.map +0 -1
  100. package/dist/core/unified-cache.js +0 -114
  101. package/dist/core/unified-cache.js.map +0 -1
  102. package/dist/index.d.ts +0 -94
  103. package/dist/index.d.ts.map +0 -1
  104. package/dist/index.js +0 -258
  105. package/dist/index.js.map +0 -1
  106. package/dist/mcp/errors.d.ts +0 -33
  107. package/dist/mcp/errors.d.ts.map +0 -1
  108. package/dist/mcp/errors.js +0 -86
  109. package/dist/mcp/errors.js.map +0 -1
  110. package/dist/mcp/index.d.ts +0 -62
  111. package/dist/mcp/index.d.ts.map +0 -1
  112. package/dist/mcp/index.js +0 -173
  113. package/dist/mcp/index.js.map +0 -1
  114. package/dist/mcp/server.d.ts +0 -17
  115. package/dist/mcp/server.d.ts.map +0 -1
  116. package/dist/mcp/server.js +0 -155
  117. package/dist/mcp/server.js.map +0 -1
  118. package/dist/mcp/tools/guide.d.ts +0 -12
  119. package/dist/mcp/tools/guide.d.ts.map +0 -1
  120. package/dist/mcp/tools/guide.js +0 -801
  121. package/dist/mcp/tools/guide.js.map +0 -1
  122. package/dist/mcp/tools/index.d.ts +0 -11
  123. package/dist/mcp/tools/index.d.ts.map +0 -1
  124. package/dist/mcp/tools/index.js +0 -27
  125. package/dist/mcp/tools/index.js.map +0 -1
  126. package/dist/mcp/tools/market.d.ts +0 -11
  127. package/dist/mcp/tools/market.d.ts.map +0 -1
  128. package/dist/mcp/tools/market.js +0 -314
  129. package/dist/mcp/tools/market.js.map +0 -1
  130. package/dist/mcp/tools/order.d.ts +0 -10
  131. package/dist/mcp/tools/order.d.ts.map +0 -1
  132. package/dist/mcp/tools/order.js +0 -258
  133. package/dist/mcp/tools/order.js.map +0 -1
  134. package/dist/mcp/tools/trade.d.ts +0 -38
  135. package/dist/mcp/tools/trade.d.ts.map +0 -1
  136. package/dist/mcp/tools/trade.js +0 -314
  137. package/dist/mcp/tools/trade.js.map +0 -1
  138. package/dist/mcp/tools/trader.d.ts +0 -11
  139. package/dist/mcp/tools/trader.d.ts.map +0 -1
  140. package/dist/mcp/tools/trader.js +0 -277
  141. package/dist/mcp/tools/trader.js.map +0 -1
  142. package/dist/mcp/tools/wallet.d.ts +0 -274
  143. package/dist/mcp/tools/wallet.d.ts.map +0 -1
  144. package/dist/mcp/tools/wallet.js +0 -579
  145. package/dist/mcp/tools/wallet.js.map +0 -1
  146. package/dist/mcp/types.d.ts +0 -413
  147. package/dist/mcp/types.d.ts.map +0 -1
  148. package/dist/mcp/types.js +0 -5
  149. package/dist/mcp/types.js.map +0 -1
  150. package/dist/services/authorization-service.d.ts +0 -97
  151. package/dist/services/authorization-service.d.ts.map +0 -1
  152. package/dist/services/authorization-service.js +0 -279
  153. package/dist/services/authorization-service.js.map +0 -1
  154. package/dist/services/market-service.d.ts +0 -108
  155. package/dist/services/market-service.d.ts.map +0 -1
  156. package/dist/services/market-service.js +0 -458
  157. package/dist/services/market-service.js.map +0 -1
  158. package/dist/services/realtime-service.d.ts +0 -82
  159. package/dist/services/realtime-service.d.ts.map +0 -1
  160. package/dist/services/realtime-service.js +0 -150
  161. package/dist/services/realtime-service.js.map +0 -1
  162. package/dist/services/swap-service.d.ts +0 -217
  163. package/dist/services/swap-service.d.ts.map +0 -1
  164. package/dist/services/swap-service.js +0 -695
  165. package/dist/services/swap-service.js.map +0 -1
  166. package/dist/services/wallet-service.d.ts +0 -94
  167. package/dist/services/wallet-service.d.ts.map +0 -1
  168. package/dist/services/wallet-service.js +0 -173
  169. package/dist/services/wallet-service.js.map +0 -1
  170. package/dist/utils/price-utils.d.ts +0 -153
  171. package/dist/utils/price-utils.d.ts.map +0 -1
  172. package/dist/utils/price-utils.js +0 -236
  173. package/dist/utils/price-utils.js.map +0 -1
  174. package/docs/01-mcp.md +0 -2041
  175. package/docs/e2e/01-trader-tools.md +0 -159
  176. package/docs/e2e/02-market-tools.md +0 -180
  177. package/docs/e2e/03-order-tools.md +0 -166
  178. package/docs/e2e/04-wallet-tools.md +0 -224
  179. package/docs/e2e/05-trading-tools.md +0 -327
  180. package/docs/e2e/06-integration-scenarios.md +0 -481
  181. package/docs/e2e/coordinator.md +0 -376
  182. package/scripts/truth.md +0 -440
  183. package/src/mcp/README.md +0 -380
  184. package/src/mcp/errors.ts +0 -124
  185. package/src/mcp/index.ts +0 -309
  186. package/src/mcp/server.ts +0 -183
  187. package/src/mcp/tools/guide.ts +0 -821
  188. package/src/mcp/tools/index.ts +0 -73
  189. package/src/mcp/tools/market.ts +0 -363
  190. package/src/mcp/tools/order.ts +0 -326
  191. package/src/mcp/tools/trade.ts +0 -417
  192. package/src/mcp/tools/trader.ts +0 -322
  193. package/src/mcp/tools/wallet.ts +0 -683
  194. package/src/mcp/types.ts +0 -472
@@ -1,326 +0,0 @@
1
- /**
2
- * Order Tools - MCP tools for orderbook analysis
3
- */
4
-
5
- import type { PolymarketSDK } from '../../index.js';
6
- import type {
7
- ToolDefinition,
8
- GetOrderbookInput,
9
- GetOrderbookOutput,
10
- GetBestPricesInput,
11
- GetBestPricesOutput,
12
- EstimateExecutionInput,
13
- EstimateExecutionOutput,
14
- } from '../types.js';
15
- import {
16
- validateConditionId,
17
- validateOutcome,
18
- validateSide,
19
- validatePositiveNumber,
20
- wrapError,
21
- McpToolError,
22
- ErrorCode,
23
- } from '../errors.js';
24
-
25
- export const orderToolDefinitions: ToolDefinition[] = [
26
- {
27
- name: 'get_orderbook',
28
- description: 'Get orderbook depth for a market outcome',
29
- inputSchema: {
30
- type: 'object',
31
- properties: {
32
- conditionId: {
33
- type: 'string',
34
- description: 'Market condition ID',
35
- },
36
- outcome: {
37
- type: 'string',
38
- enum: ['Yes', 'No'],
39
- description: "Which outcome's orderbook to fetch",
40
- },
41
- depth: {
42
- type: 'number',
43
- description: 'Number of price levels',
44
- default: 10,
45
- },
46
- },
47
- required: ['conditionId', 'outcome'],
48
- },
49
- },
50
- {
51
- name: 'get_best_prices',
52
- description: 'Get best bid/ask prices for both outcomes',
53
- inputSchema: {
54
- type: 'object',
55
- properties: {
56
- conditionId: {
57
- type: 'string',
58
- description: 'Market condition ID',
59
- },
60
- },
61
- required: ['conditionId'],
62
- },
63
- },
64
- {
65
- name: 'estimate_execution',
66
- description: 'Estimate execution price and slippage for a trade',
67
- inputSchema: {
68
- type: 'object',
69
- properties: {
70
- conditionId: {
71
- type: 'string',
72
- },
73
- outcome: {
74
- type: 'string',
75
- enum: ['Yes', 'No'],
76
- },
77
- side: {
78
- type: 'string',
79
- enum: ['BUY', 'SELL'],
80
- },
81
- amount: {
82
- type: 'number',
83
- description: 'Amount in USDC',
84
- },
85
- },
86
- required: ['conditionId', 'outcome', 'side', 'amount'],
87
- },
88
- },
89
- ];
90
-
91
- export async function handleGetOrderbook(
92
- sdk: PolymarketSDK,
93
- input: GetOrderbookInput
94
- ): Promise<GetOrderbookOutput> {
95
- validateConditionId(input.conditionId);
96
- validateOutcome(input.outcome);
97
-
98
- try {
99
- // Get market to find the token ID
100
- const market = await sdk.clobApi.getMarket(input.conditionId);
101
- const isYes = input.outcome === 'Yes';
102
- const token = market.tokens.find(
103
- (t) => t.outcome.toLowerCase() === input.outcome.toLowerCase()
104
- );
105
-
106
- if (!token) {
107
- throw new McpToolError(
108
- ErrorCode.MARKET_NOT_FOUND,
109
- `Token for outcome ${input.outcome} not found`
110
- );
111
- }
112
-
113
- // Get the raw orderbook for this token
114
- const orderbook = await sdk.clobApi.getOrderbook(token.tokenId);
115
- const depth = input.depth || 10;
116
-
117
- // Get market title
118
- let marketTitle = input.conditionId;
119
- try {
120
- const unifiedMarket = await sdk.getMarket(input.conditionId);
121
- marketTitle = unifiedMarket.question;
122
- } catch {
123
- // Use conditionId as fallback
124
- }
125
-
126
- // Calculate totals for each level
127
- let bidTotal = 0;
128
- let askTotal = 0;
129
-
130
- const bids = orderbook.bids.slice(0, depth).map((level) => {
131
- bidTotal += level.size * level.price;
132
- return {
133
- price: level.price,
134
- size: level.size,
135
- total: bidTotal,
136
- };
137
- });
138
-
139
- const asks = orderbook.asks.slice(0, depth).map((level) => {
140
- askTotal += level.size * level.price;
141
- return {
142
- price: level.price,
143
- size: level.size,
144
- total: askTotal,
145
- };
146
- });
147
-
148
- const bestBid = bids[0]?.price || 0;
149
- const bestAsk = asks[0]?.price || 1;
150
- const spread = bestAsk - bestBid;
151
- const spreadPercent = bestBid > 0 ? (spread / bestBid) * 100 : 0;
152
-
153
- const bidDepth = orderbook.bids.slice(0, depth).reduce((sum, l) => sum + l.size, 0);
154
- const askDepth = orderbook.asks.slice(0, depth).reduce((sum, l) => sum + l.size, 0);
155
-
156
- return {
157
- market: {
158
- conditionId: input.conditionId,
159
- title: marketTitle,
160
- },
161
- outcome: input.outcome,
162
- tokenId: token.tokenId,
163
- orderbook: {
164
- bids,
165
- asks,
166
- },
167
- summary: {
168
- bestBid,
169
- bestAsk,
170
- spread,
171
- spreadPercent,
172
- bidDepth,
173
- askDepth,
174
- },
175
- };
176
- } catch (err) {
177
- throw wrapError(err);
178
- }
179
- }
180
-
181
- export async function handleGetBestPrices(
182
- sdk: PolymarketSDK,
183
- input: GetBestPricesInput
184
- ): Promise<GetBestPricesOutput> {
185
- validateConditionId(input.conditionId);
186
-
187
- try {
188
- const processedOrderbook = await sdk.clobApi.getProcessedOrderbook(input.conditionId);
189
-
190
- // Get market title
191
- let marketTitle = input.conditionId;
192
- try {
193
- const market = await sdk.getMarket(input.conditionId);
194
- marketTitle = market.question;
195
- } catch {
196
- // Use conditionId as fallback
197
- }
198
-
199
- const yes = processedOrderbook.yes;
200
- const no = processedOrderbook.no;
201
-
202
- return {
203
- market: marketTitle,
204
- yes: {
205
- bestBid: yes.bid,
206
- bestAsk: yes.ask,
207
- midPrice: (yes.bid + yes.ask) / 2,
208
- spread: yes.spread,
209
- },
210
- no: {
211
- bestBid: no.bid,
212
- bestAsk: no.ask,
213
- midPrice: (no.bid + no.ask) / 2,
214
- spread: no.spread,
215
- },
216
- };
217
- } catch (err) {
218
- throw wrapError(err);
219
- }
220
- }
221
-
222
- export async function handleEstimateExecution(
223
- sdk: PolymarketSDK,
224
- input: EstimateExecutionInput
225
- ): Promise<EstimateExecutionOutput> {
226
- validateConditionId(input.conditionId);
227
- validateOutcome(input.outcome);
228
- validateSide(input.side);
229
- validatePositiveNumber(input.amount, 'amount');
230
-
231
- try {
232
- // Get market to find the token ID
233
- const market = await sdk.clobApi.getMarket(input.conditionId);
234
- const token = market.tokens.find(
235
- (t) => t.outcome.toLowerCase() === input.outcome.toLowerCase()
236
- );
237
-
238
- if (!token) {
239
- throw new McpToolError(
240
- ErrorCode.MARKET_NOT_FOUND,
241
- `Token for outcome ${input.outcome} not found`
242
- );
243
- }
244
-
245
- // Get the raw orderbook
246
- const orderbook = await sdk.clobApi.getOrderbook(token.tokenId);
247
-
248
- // Get market title
249
- let marketTitle = input.conditionId;
250
- try {
251
- const unifiedMarket = await sdk.getMarket(input.conditionId);
252
- marketTitle = unifiedMarket.question;
253
- } catch {
254
- // Use conditionId as fallback
255
- }
256
-
257
- // Simulate execution
258
- const isBuy = input.side === 'BUY';
259
- const levels = isBuy ? orderbook.asks : orderbook.bids;
260
-
261
- if (levels.length === 0) {
262
- throw new McpToolError(
263
- ErrorCode.MARKET_NOT_FOUND,
264
- 'No liquidity available for this order'
265
- );
266
- }
267
-
268
- let remainingAmount = input.amount;
269
- let totalShares = 0;
270
- let worstPrice = levels[0].price;
271
-
272
- for (const level of levels) {
273
- const levelValue = level.size * level.price;
274
-
275
- if (remainingAmount <= levelValue) {
276
- // This level can fill the remaining order
277
- const sharesToBuy = remainingAmount / level.price;
278
- totalShares += sharesToBuy;
279
- worstPrice = level.price;
280
- remainingAmount = 0;
281
- break;
282
- } else {
283
- // Consume entire level
284
- totalShares += level.size;
285
- remainingAmount -= levelValue;
286
- worstPrice = level.price;
287
- }
288
- }
289
-
290
- // If we couldn't fill the entire order
291
- if (remainingAmount > 0) {
292
- throw new McpToolError(
293
- ErrorCode.INSUFFICIENT_BALANCE,
294
- 'Not enough liquidity to fill the entire order',
295
- { remainingAmount, totalShares }
296
- );
297
- }
298
-
299
- const avgPrice = input.amount / totalShares;
300
- const bestPrice = levels[0].price;
301
- const priceImpact = Math.abs(avgPrice - bestPrice) / bestPrice;
302
-
303
- let warning: string | null = null;
304
- if (priceImpact > 0.05) {
305
- warning = `High price impact (${(priceImpact * 100).toFixed(1)}%)`;
306
- }
307
-
308
- return {
309
- market: marketTitle,
310
- order: {
311
- side: input.side,
312
- outcome: input.outcome,
313
- usdcAmount: input.amount,
314
- },
315
- estimate: {
316
- avgPrice,
317
- sharesReceived: totalShares,
318
- priceImpact,
319
- worstPrice,
320
- },
321
- warning,
322
- };
323
- } catch (err) {
324
- throw wrapError(err);
325
- }
326
- }