@gensyn-ai/gensyn-delphi-sdk 0.1.0 → 1.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.
package/LICENSE.TXT ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) [2026] [Gensyn]
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Gensyn Delphi SDK
2
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).
3
+ TypeScript SDK for agents to interact with the Delphi information market platform on the Gensyn blockchain. Provides on-chain trading (buy/sell shares, redeem/liquidate positions, ERC-20 approvals) and a REST API client (list markets, query positions).
4
4
 
5
5
  ## Installation
6
6
 
@@ -43,15 +43,27 @@ await client.buyShares({
43
43
 
44
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
45
 
46
+ ### API Key
47
+
48
+ An API key is required for all REST API endpoints (listing markets, querying positions, etc.).
49
+
50
+ | Network | Generate your key at |
51
+ |---|---|
52
+ | Testnet | <https://delphi-api-access.gensyn.ai/> |
53
+ | Mainnet | <https://api-access.delphi.fyi> |
54
+
46
55
  ### Environment Variables
47
56
 
48
57
  | Variable | Description | Default |
49
58
  |---|---|---|
50
59
  | `DELPHI_NETWORK` | Network to use: `testnet` or `mainnet` | `testnet` |
51
60
  | `DELPHI_SIGNER_TYPE` | Signing method: `cdp_server_wallet` or `private_key` | `cdp_server_wallet` |
52
- | `DELPHI_API_ACCESS_KEY` | REST API key | — |
61
+ | `DELPHI_API_ACCESS_KEY` | REST API key (see [API Key](#api-key) above) | — |
53
62
  | `DELPHI_API_BASE_URL` | Override the REST API base URL | *(network default)* |
54
63
  | `DELPHI_GATEWAY_CONTRACT` | Override the Gateway contract address | *(network default)* |
64
+ | `DELPHI_TOKEN_ADDRESS` | Override the ERC-20 token (USDC) address | *(network default)* |
65
+ | `DELPHI_SUBGRAPH_URL` | Override the Goldsky subgraph endpoint | *(network default)* |
66
+ | `DELPHI_APP_URL` | Override the Delphi app base URL (used to build `marketUrl`) | *(network default)* |
55
67
  | `GENSYN_RPC_URL` | Override the JSON-RPC endpoint | *(network default)* |
56
68
  | `GENSYN_CHAIN_ID` | Override the chain ID | *(network default)* |
57
69
 
@@ -76,7 +88,11 @@ The client is configured via environment variables or by passing a config object
76
88
  |---|---|---|
77
89
  | Chain ID | `685685` | `685689` |
78
90
  | RPC URL | `https://gensyn-testnet.g.alchemy.com/public` | `https://gensyn-mainnet.g.alchemy.com/public` |
79
- | Gateway | `0x469388CD2498b43925f562FaA333D95135b66c06` | *(not yet available)* |
91
+ | Gateway | `0x7b8FDBD187B0Be5e30e48B1995df574A62667147` | `0x4e4e85c52E0F414cc67eE88d0C649Ec81698d700` |
92
+ | Token (USDC) | `0x0724D6079b986F8e44bDafB8a09B60C0bd6A45a1` | `0x5b32c997211621d55a89Cc5abAF1cC21F3A6ddF5` |
93
+ | API URL | `https://delphi-api.gensyn.ai/` | `https://api.delphi.fyi/` |
94
+ | Subgraph URL | [Goldsky endpoint](https://api.goldsky.com/api/public/project_cmnoqdag1obop01z3efnu8ssq/subgraphs/delphi-testnet/1.0.0/gn) | [Goldsky endpoint](https://api.goldsky.com/api/public/project_cmnoqdag1obop01z3efnu8ssq/subgraphs/delphi-mainnet/1.0.0/gn) |
95
+ | App URL | `https://testnet.delphi.fyi` | `https://app.delphi.fyi` |
80
96
 
81
97
  ### Config Object
82
98
 
@@ -124,6 +140,47 @@ const signer = await createCdpSigner({
124
140
 
125
141
  > `@coinbase/cdp-sdk` is a peer dependency only required when using CDP signing. Private key users do not need it installed.
126
142
 
143
+ ### How to create your own signer
144
+
145
+ If neither built-in option fits your setup you can construct a `DelphiSigner` directly. The interface is:
146
+
147
+ ```typescript
148
+ interface DelphiSigner {
149
+ address: `0x${string}`;
150
+ walletClient: WalletClient<HttpTransport, Chain, Account>; // viem
151
+ publicClient: PublicClient<HttpTransport, Chain>; // viem
152
+ }
153
+ ```
154
+
155
+ The pattern is always the same regardless of how signing works:
156
+
157
+ 1. **Get a viem `Account`** — how depends on your key setup:
158
+ - **Raw private key** (from `.env`, AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler, etc.): use `privateKeyToAccount(key)`
159
+ - **MPC / managed wallets** (Privy, Fireblocks, CDP, etc.): the private key never leaves the provider — use their SDK to get an account handle, then wrap it with `toAccount()`
160
+ - **Cloud KMS** (AWS KMS, GCP KMS): the key never leaves the HSM — the KMS SDK signs on your behalf, typically via a community adapter like `viem-kms-account`
161
+ 2. **Wrap it** in `createWalletClient()` and `createPublicClient()` pointed at the Gensyn RPC.
162
+ 3. **Inject it** into `DelphiClient` by subclassing and overriding `getSigner()`:
163
+
164
+ ```typescript
165
+ import { DelphiClient } from "@gensyn-ai/gensyn-delphi-sdk";
166
+ import type { DelphiSigner, DelphiClientConfig } from "@gensyn-ai/gensyn-delphi-sdk";
167
+
168
+ class CustomSignerClient extends DelphiClient {
169
+ private readonly _signer: Promise<DelphiSigner>;
170
+
171
+ constructor(signer: Promise<DelphiSigner>, config?: DelphiClientConfig) {
172
+ super(config);
173
+ this._signer = signer;
174
+ }
175
+
176
+ override getSigner(): Promise<DelphiSigner> {
177
+ return this._signer;
178
+ }
179
+ }
180
+
181
+ const client = new CustomSignerClient(myCustomSigner, { apiKey: "your-api-key" });
182
+ ```
183
+
127
184
  ## API Reference
128
185
 
129
186
  ### REST API Methods
@@ -140,12 +197,20 @@ const { status } = await client.health();
140
197
 
141
198
  #### `listMarkets(params?)`
142
199
 
143
- Retrieve markets with optional filtering and pagination.
200
+ Retrieve markets with optional filtering, sorting, and pagination.
201
+
202
+ Each market object includes:
203
+ - `id` — on-chain contract address of the market proxy
204
+ - `appMarketId` — UUID identifying the market in the Delphi app UI
205
+ - `marketUrl` — direct link to the market on the Delphi app (`{appUrl}/market/{appMarketId}`)
206
+ - `deployer` — wallet address of the market creator
144
207
 
145
208
  ```typescript
146
209
  const { markets } = await client.listMarkets({
147
- status: "open", // filter by status
148
- category: "crypto", // filter by metadata category
210
+ status: "open", // "open" | "closed" | "settled"
211
+ category: "crypto", // "crypto" | "culture" | "economics" | "miscellaneous" | "politics" | "sports"
212
+ orderBy: "liquidity", // "liquidity" (default) | "created" | "settles_at"
213
+ verifiable: true, // filter by verifiable settlement
149
214
  skip: 0,
150
215
  limit: 50,
151
216
  });
@@ -153,10 +218,10 @@ const { markets } = await client.listMarkets({
153
218
 
154
219
  #### `getMarket(params)`
155
220
 
156
- Retrieve a single market by ID.
221
+ Retrieve a single market by its on-chain contract address.
157
222
 
158
223
  ```typescript
159
- const market = await client.getMarket({ id: "market-id" });
224
+ const market = await client.getMarket({ id: "0xMarketContractAddress" });
160
225
  ```
161
226
 
162
227
  #### `listPositions(params)`
@@ -248,19 +313,30 @@ for (const result of results) {
248
313
  }
249
314
  ```
250
315
 
316
+ #### `liquidate(params)`
317
+
318
+ Liquidate positions on an expired market. Burns shares across the specified outcome indices and returns the collateral tokens.
319
+
320
+ ```typescript
321
+ const { transactionHash, sharesIn, totalTokensOut } = await client.liquidate({
322
+ marketAddress: "0xMarket",
323
+ outcomeIndices: [0, 1], // all outcome indices for the market
324
+ });
325
+ ```
326
+
251
327
  #### `getTokenAllowance(params)`
252
328
 
253
- Read the current ERC-20 allowance your wallet has granted to a market.
329
+ Read the current ERC-20 allowance your wallet has granted to the gateway.
254
330
 
255
331
  ```typescript
256
- const { allowance } = await client.getTokenAllowance({
332
+ const { ownerAddress, allowance } = await client.getTokenAllowance({
257
333
  marketAddress: "0xMarket",
258
334
  });
259
335
  ```
260
336
 
261
337
  #### `approveToken(params)`
262
338
 
263
- Approve the ERC-20 token for spending by a market. Defaults to unlimited (`uint256` max).
339
+ Approve the ERC-20 token for spending by the gateway. Defaults to unlimited (`uint256` max).
264
340
 
265
341
  ```typescript
266
342
  const { transactionHash } = await client.approveToken({
@@ -281,6 +357,61 @@ const { approvalNeeded, allowance, transactionHash } = await client.ensureTokenA
281
357
  });
282
358
  ```
283
359
 
360
+ ### Wallet Methods
361
+
362
+ Read-only balance queries for the signer wallet.
363
+
364
+ #### `getEthBalance()`
365
+
366
+ Returns the native ETH balance for the current signer wallet.
367
+
368
+ ```typescript
369
+ const balance = await client.getEthBalance(); // bigint (wei)
370
+ ```
371
+
372
+ #### `getErc20Balance(tokenAddress?)`
373
+
374
+ Returns the ERC-20 token balance. Defaults to the configured USDC token address when omitted.
375
+
376
+ ```typescript
377
+ const balance = await client.getErc20Balance(); // bigint (6 decimals for USDC)
378
+ ```
379
+
380
+ #### `getErc20BalanceWithDecimals(tokenAddress?)`
381
+
382
+ Returns both the balance and decimals for an ERC-20 token.
383
+
384
+ ```typescript
385
+ const { balance, decimals } = await client.getErc20BalanceWithDecimals();
386
+ ```
387
+
388
+ ### Subgraph Methods
389
+
390
+ Query on-chain event data indexed by the Goldsky subgraph.
391
+
392
+ #### `getSubgraph()`
393
+
394
+ Access the `SubgraphClient` for querying historical trade data.
395
+
396
+ ```typescript
397
+ const subgraph = client.getSubgraph();
398
+
399
+ // Fetch buys and sells for a specific market
400
+ const { buys, sells } = await subgraph.getMarketTrades("0xMarketProxy", {
401
+ first: 20,
402
+ });
403
+
404
+ // Check subgraph indexing metadata
405
+ const meta = await subgraph.getMeta();
406
+
407
+ // Run an arbitrary GraphQL query
408
+ const data = await subgraph.query<{ gatewayBuys: SubgraphBuy[] }>(`{
409
+ gatewayBuys(first: 5, orderBy: timestamp_, orderDirection: desc) {
410
+ id buyer marketProxy tokensIn sharesOut timestamp_
411
+ }
412
+ }`);
413
+ ```
414
+
284
415
  #### `getSigner()`
285
416
 
286
417
  Access the underlying `DelphiSigner` directly (e.g. to call `publicClient` for custom contract reads).