@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 +21 -0
- package/README.md +142 -11
- package/dist/abi/DynamicParimutuelGateway.d.ts +578 -108
- package/dist/abi/DynamicParimutuelGateway.d.ts.map +1 -1
- package/dist/abi/DynamicParimutuelGateway.js +368 -60
- package/dist/abi/DynamicParimutuelGateway.js.map +1 -1
- package/dist/client/DelphiClient.d.ts +11 -0
- package/dist/client/DelphiClient.d.ts.map +1 -1
- package/dist/client/DelphiClient.js +116 -11
- package/dist/client/DelphiClient.js.map +1 -1
- package/dist/client/signer.d.ts.map +1 -1
- package/dist/client/signer.js +3 -0
- package/dist/client/signer.js.map +1 -1
- package/dist/types/index.d.ts +43 -2
- package/dist/types/index.d.ts.map +1 -1
- package/package.json +5 -1
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
|
|
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 | `
|
|
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",
|
|
148
|
-
category: "crypto",
|
|
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
|
|
221
|
+
Retrieve a single market by its on-chain contract address.
|
|
157
222
|
|
|
158
223
|
```typescript
|
|
159
|
-
const market = await client.getMarket({ 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
|
|
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
|
|
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).
|