@gensyn-ai/gensyn-delphi-sdk 0.1.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 (38) hide show
  1. package/README.md +310 -0
  2. package/dist/abi/DynamicParimutuelGateway.d.ts +1910 -0
  3. package/dist/abi/DynamicParimutuelGateway.d.ts.map +1 -0
  4. package/dist/abi/DynamicParimutuelGateway.js +1260 -0
  5. package/dist/abi/DynamicParimutuelGateway.js.map +1 -0
  6. package/dist/abi/ERC20.d.ts +552 -0
  7. package/dist/abi/ERC20.d.ts.map +1 -0
  8. package/dist/abi/ERC20.js +365 -0
  9. package/dist/abi/ERC20.js.map +1 -0
  10. package/dist/client/DelphiClient.d.ts +128 -0
  11. package/dist/client/DelphiClient.d.ts.map +1 -0
  12. package/dist/client/DelphiClient.js +436 -0
  13. package/dist/client/DelphiClient.js.map +1 -0
  14. package/dist/client/signer.d.ts +41 -0
  15. package/dist/client/signer.d.ts.map +1 -0
  16. package/dist/client/signer.js +72 -0
  17. package/dist/client/signer.js.map +1 -0
  18. package/dist/client/subgraph.d.ts +39 -0
  19. package/dist/client/subgraph.d.ts.map +1 -0
  20. package/dist/client/subgraph.js +91 -0
  21. package/dist/client/subgraph.js.map +1 -0
  22. package/dist/client/token.d.ts +18 -0
  23. package/dist/client/token.d.ts.map +1 -0
  24. package/dist/client/token.js +58 -0
  25. package/dist/client/token.js.map +1 -0
  26. package/dist/client/wallet.d.ts +28 -0
  27. package/dist/client/wallet.d.ts.map +1 -0
  28. package/dist/client/wallet.js +57 -0
  29. package/dist/client/wallet.js.map +1 -0
  30. package/dist/index.d.ts +8 -0
  31. package/dist/index.d.ts.map +1 -0
  32. package/dist/index.js +10 -0
  33. package/dist/index.js.map +1 -0
  34. package/dist/types/index.d.ts +239 -0
  35. package/dist/types/index.d.ts.map +1 -0
  36. package/dist/types/index.js +3 -0
  37. package/dist/types/index.js.map +1 -0
  38. package/package.json +54 -0
package/README.md ADDED
@@ -0,0 +1,310 @@
1
+ # Gensyn Delphi SDK
2
+
3
+ TypeScript SDK for agents to interact with the [Delphi](https://delphi.gensyn.ai) prediction market platform on the Gensyn blockchain. Provides on-chain trading (buy/sell shares, redeem positions, ERC-20 approvals) and a REST API client (list markets, query positions).
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @gensyn-ai/gensyn-delphi-sdk
9
+ ```
10
+
11
+ ## Quick Start
12
+
13
+ ```typescript
14
+ import { DelphiClient } from "@gensyn-ai/gensyn-delphi-sdk";
15
+
16
+ const client = new DelphiClient(); // reads config from env vars
17
+
18
+ // List open markets
19
+ const { markets } = await client.listMarkets({ status: "open", limit: 10 });
20
+
21
+ // Quote a buy before committing
22
+ const { tokensIn } = await client.quoteBuy({
23
+ marketAddress: "0xYourMarketAddress",
24
+ outcomeIdx: 0,
25
+ sharesOut: BigInt("1000000000000000000"), // 1 share (18 decimals)
26
+ });
27
+
28
+ // Approve spending and buy shares
29
+ await client.ensureTokenApproval({
30
+ marketAddress: "0xYourMarketAddress",
31
+ minimumAmount: tokensIn,
32
+ });
33
+
34
+ await client.buyShares({
35
+ marketAddress: "0xYourMarketAddress",
36
+ outcomeIdx: 0,
37
+ sharesOut: BigInt("1000000000000000000"),
38
+ maxTokensIn: tokensIn * 101n / 100n, // 1% slippage tolerance
39
+ });
40
+ ```
41
+
42
+ ## Configuration
43
+
44
+ The client is configured via environment variables or by passing a config object to the constructor. Environment variables are loaded from `.env` automatically.
45
+
46
+ ### Environment Variables
47
+
48
+ | Variable | Description | Default |
49
+ |---|---|---|
50
+ | `DELPHI_NETWORK` | Network to use: `testnet` or `mainnet` | `testnet` |
51
+ | `DELPHI_SIGNER_TYPE` | Signing method: `cdp_server_wallet` or `private_key` | `cdp_server_wallet` |
52
+ | `DELPHI_API_ACCESS_KEY` | REST API key | — |
53
+ | `DELPHI_API_BASE_URL` | Override the REST API base URL | *(network default)* |
54
+ | `DELPHI_GATEWAY_CONTRACT` | Override the Gateway contract address | *(network default)* |
55
+ | `GENSYN_RPC_URL` | Override the JSON-RPC endpoint | *(network default)* |
56
+ | `GENSYN_CHAIN_ID` | Override the chain ID | *(network default)* |
57
+
58
+ **For `private_key` signing:**
59
+
60
+ | Variable | Description |
61
+ |---|---|
62
+ | `WALLET_PRIVATE_KEY` | Hex-encoded private key (`0x...`) |
63
+
64
+ **For `cdp_server_wallet` signing (default):**
65
+
66
+ | Variable | Description |
67
+ |---|---|
68
+ | `CDP_API_KEY_ID` | Coinbase Developer Platform API key ID |
69
+ | `CDP_API_KEY_SECRET` | Coinbase Developer Platform API key secret |
70
+ | `CDP_WALLET_SECRET` | CDP Server Wallet secret |
71
+ | `CDP_WALLET_ADDRESS` | On-chain address of the CDP wallet (`0x...`) |
72
+
73
+ ### Network Defaults
74
+
75
+ | | Testnet | Mainnet |
76
+ |---|---|---|
77
+ | Chain ID | `685685` | `685689` |
78
+ | RPC URL | `https://gensyn-testnet.g.alchemy.com/public` | `https://gensyn-mainnet.g.alchemy.com/public` |
79
+ | Gateway | `0x469388CD2498b43925f562FaA333D95135b66c06` | *(not yet available)* |
80
+
81
+ ### Config Object
82
+
83
+ All environment variables can also be passed directly to the constructor, which takes precedence over env vars:
84
+
85
+ ```typescript
86
+ const client = new DelphiClient({
87
+ network: "testnet",
88
+ signerType: "private_key",
89
+ privateKey: "0xYourPrivateKey",
90
+ apiKey: "your-api-key",
91
+ });
92
+ ```
93
+
94
+ ## Signing
95
+
96
+ Two signing modes are supported, both producing the same `DelphiSigner` interface consumed by on-chain methods.
97
+
98
+ ### Private Key
99
+
100
+ ```typescript
101
+ import { createPrivateKeySigner } from "@gensyn-ai/gensyn-delphi-sdk";
102
+
103
+ const signer = await createPrivateKeySigner({
104
+ privateKey: "0xYourPrivateKey",
105
+ rpcUrl: "https://gensyn-testnet.g.alchemy.com/public",
106
+ chainId: 685685,
107
+ });
108
+ ```
109
+
110
+ ### CDP Server Wallet
111
+
112
+ ```typescript
113
+ import { createCdpSigner } from "@gensyn-ai/gensyn-delphi-sdk";
114
+
115
+ const signer = await createCdpSigner({
116
+ apiKeyId: "your-cdp-api-key-id",
117
+ apiKeySecret: "your-cdp-api-key-secret",
118
+ walletSecret: "your-cdp-wallet-secret",
119
+ walletAddress: "0xYourWalletAddress",
120
+ rpcUrl: "https://gensyn-testnet.g.alchemy.com/public",
121
+ chainId: 685685,
122
+ });
123
+ ```
124
+
125
+ > `@coinbase/cdp-sdk` is a peer dependency only required when using CDP signing. Private key users do not need it installed.
126
+
127
+ ## API Reference
128
+
129
+ ### REST API Methods
130
+
131
+ These methods read data from the Delphi API and require `DELPHI_API_ACCESS_KEY`.
132
+
133
+ #### `health()`
134
+
135
+ Check service availability. Does not require authentication.
136
+
137
+ ```typescript
138
+ const { status } = await client.health();
139
+ ```
140
+
141
+ #### `listMarkets(params?)`
142
+
143
+ Retrieve markets with optional filtering and pagination.
144
+
145
+ ```typescript
146
+ const { markets } = await client.listMarkets({
147
+ status: "open", // filter by status
148
+ category: "crypto", // filter by metadata category
149
+ skip: 0,
150
+ limit: 50,
151
+ });
152
+ ```
153
+
154
+ #### `getMarket(params)`
155
+
156
+ Retrieve a single market by ID.
157
+
158
+ ```typescript
159
+ const market = await client.getMarket({ id: "market-id" });
160
+ ```
161
+
162
+ #### `listPositions(params)`
163
+
164
+ Retrieve positions for a wallet address.
165
+
166
+ ```typescript
167
+ const { positions } = await client.listPositions({
168
+ wallet: "0xYourWalletAddress",
169
+ redeemedOrLiquidated: false,
170
+ skip: 0,
171
+ limit: 50,
172
+ });
173
+ ```
174
+
175
+ ### On-Chain Methods
176
+
177
+ These methods send transactions or read directly from the blockchain.
178
+
179
+ #### `quoteBuy(params)` / `quoteSell(params)`
180
+
181
+ Simulate a trade to get an estimated cost/payout without spending gas.
182
+
183
+ ```typescript
184
+ const { tokensIn } = await client.quoteBuy({
185
+ marketAddress: "0xMarket",
186
+ outcomeIdx: 0,
187
+ sharesOut: BigInt("1000000000000000000"),
188
+ });
189
+
190
+ const { tokensOut } = await client.quoteSell({
191
+ marketAddress: "0xMarket",
192
+ outcomeIdx: 0,
193
+ sharesIn: BigInt("1000000000000000000"),
194
+ });
195
+ ```
196
+
197
+ #### `buyShares(params)`
198
+
199
+ Buy an exact number of outcome shares. Token approval must exist beforehand.
200
+
201
+ ```typescript
202
+ const { transactionHash } = await client.buyShares({
203
+ marketAddress: "0xMarket",
204
+ outcomeIdx: 0,
205
+ sharesOut: BigInt("1000000000000000000"), // exact shares to receive
206
+ maxTokensIn: BigInt("1100000000000000000"), // max tokens to spend (slippage cap)
207
+ });
208
+ ```
209
+
210
+ #### `sellShares(params)`
211
+
212
+ Sell an exact number of outcome shares.
213
+
214
+ ```typescript
215
+ const { transactionHash } = await client.sellShares({
216
+ marketAddress: "0xMarket",
217
+ outcomeIdx: 0,
218
+ sharesIn: BigInt("1000000000000000000"), // exact shares to sell
219
+ minTokensOut: BigInt("900000000000000000"), // min tokens to receive (slippage floor)
220
+ });
221
+ ```
222
+
223
+ #### `redeemMarket(params)`
224
+
225
+ Redeem a winning position for a single resolved market.
226
+
227
+ ```typescript
228
+ const { transactionHash, sharesIn, tokensOut } = await client.redeemMarket({
229
+ marketAddress: "0xMarket",
230
+ });
231
+ ```
232
+
233
+ #### `redeemPositions(params)`
234
+
235
+ Batch-redeem positions across multiple markets. Failures are captured per-market rather than aborting the whole batch.
236
+
237
+ ```typescript
238
+ const { results, totalTokensOut } = await client.redeemPositions({
239
+ marketAddresses: ["0xMarket1", "0xMarket2"],
240
+ });
241
+
242
+ for (const result of results) {
243
+ if (result.success) {
244
+ console.log(`Redeemed ${result.tokensOut} tokens from ${result.marketAddress}`);
245
+ } else {
246
+ console.error(`Failed ${result.marketAddress}: ${result.error}`);
247
+ }
248
+ }
249
+ ```
250
+
251
+ #### `getTokenAllowance(params)`
252
+
253
+ Read the current ERC-20 allowance your wallet has granted to a market.
254
+
255
+ ```typescript
256
+ const { allowance } = await client.getTokenAllowance({
257
+ marketAddress: "0xMarket",
258
+ });
259
+ ```
260
+
261
+ #### `approveToken(params)`
262
+
263
+ Approve the ERC-20 token for spending by a market. Defaults to unlimited (`uint256` max).
264
+
265
+ ```typescript
266
+ const { transactionHash } = await client.approveToken({
267
+ marketAddress: "0xMarket",
268
+ amount: BigInt("1000000000000000000"), // optional; omit for unlimited
269
+ });
270
+ ```
271
+
272
+ #### `ensureTokenApproval(params)`
273
+
274
+ Check if sufficient allowance exists; only sends an approval transaction if needed. Useful before buying shares.
275
+
276
+ ```typescript
277
+ const { approvalNeeded, allowance, transactionHash } = await client.ensureTokenApproval({
278
+ marketAddress: "0xMarket",
279
+ minimumAmount: tokensIn, // required minimum
280
+ approveAmount: tokensIn * 10n, // optional; defaults to unlimited
281
+ });
282
+ ```
283
+
284
+ #### `getSigner()`
285
+
286
+ Access the underlying `DelphiSigner` directly (e.g. to call `publicClient` for custom contract reads).
287
+
288
+ ```typescript
289
+ const { address, publicClient, walletClient } = await client.getSigner();
290
+ ```
291
+
292
+ ## Development
293
+
294
+ ```bash
295
+ # Install dependencies
296
+ npm install
297
+
298
+ # Build
299
+ npm run build
300
+
301
+ # Run tests
302
+ npm test
303
+
304
+ # Watch mode
305
+ npm run dev
306
+ ```
307
+
308
+ ## License
309
+
310
+ MIT