@gensyn-ai/gensyn-delphi-sdk 0.1.0 → 1.0.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,26 @@ 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)* |
55
66
  | `GENSYN_RPC_URL` | Override the JSON-RPC endpoint | *(network default)* |
56
67
  | `GENSYN_CHAIN_ID` | Override the chain ID | *(network default)* |
57
68
 
@@ -76,7 +87,10 @@ The client is configured via environment variables or by passing a config object
76
87
  |---|---|---|
77
88
  | Chain ID | `685685` | `685689` |
78
89
  | RPC URL | `https://gensyn-testnet.g.alchemy.com/public` | `https://gensyn-mainnet.g.alchemy.com/public` |
79
- | Gateway | `0x469388CD2498b43925f562FaA333D95135b66c06` | *(not yet available)* |
90
+ | Gateway | `0x7b8FDBD187B0Be5e30e48B1995df574A62667147` | `0x4e4e85c52E0F414cc67eE88d0C649Ec81698d700` |
91
+ | Token (USDC) | `0x0724D6079b986F8e44bDafB8a09B60C0bd6A45a1` | `0x5b32c997211621d55a89Cc5abAF1cC21F3A6ddF5` |
92
+ | API URL | `https://delphi-api.gensyn.ai/` | `https://api.delphi.fyi/` |
93
+ | 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) |
80
94
 
81
95
  ### Config Object
82
96
 
@@ -124,6 +138,47 @@ const signer = await createCdpSigner({
124
138
 
125
139
  > `@coinbase/cdp-sdk` is a peer dependency only required when using CDP signing. Private key users do not need it installed.
126
140
 
141
+ ### How to create your own signer
142
+
143
+ If neither built-in option fits your setup you can construct a `DelphiSigner` directly. The interface is:
144
+
145
+ ```typescript
146
+ interface DelphiSigner {
147
+ address: `0x${string}`;
148
+ walletClient: WalletClient<HttpTransport, Chain, Account>; // viem
149
+ publicClient: PublicClient<HttpTransport, Chain>; // viem
150
+ }
151
+ ```
152
+
153
+ The pattern is always the same regardless of how signing works:
154
+
155
+ 1. **Get a viem `Account`** — how depends on your key setup:
156
+ - **Raw private key** (from `.env`, AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler, etc.): use `privateKeyToAccount(key)`
157
+ - **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()`
158
+ - **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`
159
+ 2. **Wrap it** in `createWalletClient()` and `createPublicClient()` pointed at the Gensyn RPC.
160
+ 3. **Inject it** into `DelphiClient` by subclassing and overriding `getSigner()`:
161
+
162
+ ```typescript
163
+ import { DelphiClient } from "@gensyn-ai/gensyn-delphi-sdk";
164
+ import type { DelphiSigner, DelphiClientConfig } from "@gensyn-ai/gensyn-delphi-sdk";
165
+
166
+ class CustomSignerClient extends DelphiClient {
167
+ private readonly _signer: Promise<DelphiSigner>;
168
+
169
+ constructor(signer: Promise<DelphiSigner>, config?: DelphiClientConfig) {
170
+ super(config);
171
+ this._signer = signer;
172
+ }
173
+
174
+ override getSigner(): Promise<DelphiSigner> {
175
+ return this._signer;
176
+ }
177
+ }
178
+
179
+ const client = new CustomSignerClient(myCustomSigner, { apiKey: "your-api-key" });
180
+ ```
181
+
127
182
  ## API Reference
128
183
 
129
184
  ### REST API Methods
@@ -140,12 +195,14 @@ const { status } = await client.health();
140
195
 
141
196
  #### `listMarkets(params?)`
142
197
 
143
- Retrieve markets with optional filtering and pagination.
198
+ Retrieve markets with optional filtering, sorting, and pagination.
144
199
 
145
200
  ```typescript
146
201
  const { markets } = await client.listMarkets({
147
- status: "open", // filter by status
148
- category: "crypto", // filter by metadata category
202
+ status: "open", // "open" | "closed" | "settled"
203
+ category: "crypto", // "crypto" | "culture" | "economics" | "miscellaneous" | "politics" | "sports"
204
+ orderBy: "liquidity", // "liquidity" (default) | "created"
205
+ verifiable: true, // filter by verifiable settlement
149
206
  skip: 0,
150
207
  limit: 50,
151
208
  });
@@ -248,19 +305,30 @@ for (const result of results) {
248
305
  }
249
306
  ```
250
307
 
308
+ #### `liquidate(params)`
309
+
310
+ Liquidate positions on an expired market. Burns shares across the specified outcome indices and returns the collateral tokens.
311
+
312
+ ```typescript
313
+ const { transactionHash, sharesIn, totalTokensOut } = await client.liquidate({
314
+ marketAddress: "0xMarket",
315
+ outcomeIndices: [0, 1], // all outcome indices for the market
316
+ });
317
+ ```
318
+
251
319
  #### `getTokenAllowance(params)`
252
320
 
253
- Read the current ERC-20 allowance your wallet has granted to a market.
321
+ Read the current ERC-20 allowance your wallet has granted to the gateway.
254
322
 
255
323
  ```typescript
256
- const { allowance } = await client.getTokenAllowance({
324
+ const { ownerAddress, allowance } = await client.getTokenAllowance({
257
325
  marketAddress: "0xMarket",
258
326
  });
259
327
  ```
260
328
 
261
329
  #### `approveToken(params)`
262
330
 
263
- Approve the ERC-20 token for spending by a market. Defaults to unlimited (`uint256` max).
331
+ Approve the ERC-20 token for spending by the gateway. Defaults to unlimited (`uint256` max).
264
332
 
265
333
  ```typescript
266
334
  const { transactionHash } = await client.approveToken({
@@ -281,6 +349,61 @@ const { approvalNeeded, allowance, transactionHash } = await client.ensureTokenA
281
349
  });
282
350
  ```
283
351
 
352
+ ### Wallet Methods
353
+
354
+ Read-only balance queries for the signer wallet.
355
+
356
+ #### `getEthBalance()`
357
+
358
+ Returns the native ETH balance for the current signer wallet.
359
+
360
+ ```typescript
361
+ const balance = await client.getEthBalance(); // bigint (wei)
362
+ ```
363
+
364
+ #### `getErc20Balance(tokenAddress?)`
365
+
366
+ Returns the ERC-20 token balance. Defaults to the configured USDC token address when omitted.
367
+
368
+ ```typescript
369
+ const balance = await client.getErc20Balance(); // bigint (6 decimals for USDC)
370
+ ```
371
+
372
+ #### `getErc20BalanceWithDecimals(tokenAddress?)`
373
+
374
+ Returns both the balance and decimals for an ERC-20 token.
375
+
376
+ ```typescript
377
+ const { balance, decimals } = await client.getErc20BalanceWithDecimals();
378
+ ```
379
+
380
+ ### Subgraph Methods
381
+
382
+ Query on-chain event data indexed by the Goldsky subgraph.
383
+
384
+ #### `getSubgraph()`
385
+
386
+ Access the `SubgraphClient` for querying historical trade data.
387
+
388
+ ```typescript
389
+ const subgraph = client.getSubgraph();
390
+
391
+ // Fetch buys and sells for a specific market
392
+ const { buys, sells } = await subgraph.getMarketTrades("0xMarketProxy", {
393
+ first: 20,
394
+ });
395
+
396
+ // Check subgraph indexing metadata
397
+ const meta = await subgraph.getMeta();
398
+
399
+ // Run an arbitrary GraphQL query
400
+ const data = await subgraph.query<{ gatewayBuys: SubgraphBuy[] }>(`{
401
+ gatewayBuys(first: 5, orderBy: timestamp_, orderDirection: desc) {
402
+ id buyer marketProxy tokensIn sharesOut timestamp_
403
+ }
404
+ }`);
405
+ ```
406
+
284
407
  #### `getSigner()`
285
408
 
286
409
  Access the underlying `DelphiSigner` directly (e.g. to call `publicClient` for custom contract reads).