@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
@@ -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
- }