Delphi

Gensyn Delphi is a set of tools for deploying and interacting with information markets on Gensyn. Markets are user-owned and permissionless — Gensyn does not control markets, custody funds, or settle trades. The API is maintained for convenience. All interactions go through DelphiClient from the @gensyn-ai/gensyn-delphi-sdk package.

How dynamic parimutuel markets work

Dynamic parimutuel markets are betting or information systems where prices (odds) emerge endogenously from the distribution of all participants' wagers rather than being set by a market maker. As new bets flow in, the implied probabilities continuously update: outcomes attracting more capital see their odds shorten (higher implied probability), while less-backed outcomes become cheaper. Liquidity is pooled across all participants, so traders are effectively betting against the aggregate market rather than a counterparty, and the depth of the pool determines how sensitive prices are to new information. This creates a self-adjusting mechanism where prices reflect both current beliefs and the marginal impact of incoming liquidity, often leading to smoother, more stable updates than thin order-book markets while still converging toward consensus probabilities over time.

When to use this skill

User wants to list, search, or browse information markets
User wants prices, probabilities, or details for a specific market
User wants to buy or sell outcome shares
User wants to check their portfolio, positions, or trade history
User wants to redeem winnings from a resolved market
User wants to liquidate positions in an expired (unresolved) market
If the user asks you to create a market, remind them that markets not created on the UI will not show up on the UI
User wants to check or set token approval for trading
User wants to query historical on-chain trade data (buys, sells, redemptions, liquidations)
User wants recent trades for a market or wallet via the Goldsky subgraph
User wants to check their wallet ETH or token balances
User wants to get ETH or USDC to fund their wallet for trading (testnet faucet, bridging)
Any question about Delphi information markets, or on-chain trading on Gensyn

Installation

npm install

This will install all required dependencies including the SDK, dotenv, viem, and development tools.

Example scripts

This repository includes working example scripts in the scripts/ folder that demonstrate all common operations. These provide a paved path for agents to reference or run directly:

Script	Purpose	Usage
`scripts/list-markets.ts`	List and filter markets	`npx tsx scripts/list-markets.ts [status] [category] [limit]`
`scripts/get-market.ts`	Get details for a specific market	`npx tsx scripts/get-market.ts <market-id>`
`scripts/quote-buy.ts`	Get buy quote (read-only)	`npx tsx scripts/quote-buy.ts <market-address> <outcome-idx> <shares>`
`scripts/quote-sell.ts`	Get sell quote (read-only)	`npx tsx scripts/quote-sell.ts <market-address> <outcome-idx> <shares>`
`scripts/buy-shares.ts`	Buy shares (on-chain)	`npx tsx scripts/buy-shares.ts <market-address> <outcome-idx> <shares> [slippage-pct]`
`scripts/sell-shares.ts`	Sell shares (on-chain)	`npx tsx scripts/sell-shares.ts <market-address> <outcome-idx> <shares> [slippage-pct]`
`scripts/list-positions.ts`	List wallet positions	`npx tsx scripts/list-positions.ts [wallet-address]`
`scripts/redeem.ts`	Redeem winnings from settled markets	`npx tsx scripts/redeem.ts <market-address> [market-address ...]`
`scripts/liquidate.ts`	Liquidate positions in expired markets	`npx tsx scripts/liquidate.ts <market-address> [market-address ...]`
`scripts/token-approval.ts`	Check or set token approval	`npx tsx scripts/token-approval.ts <market-address> [amount\|unlimited]`
`scripts/list-recent-trades.ts`	List recent trades via subgraph	`npx tsx scripts/list-recent-trades.ts <market-proxy-address> [limit]`
`scripts/get-wallet-balances.ts`	Check ETH and collateral token balances	`npx tsx scripts/get-wallet-balances.ts`
`scripts/testnet-faucet.ts`	Claim 1,000 testnet USDC from the Gensyn faucet	`npx tsx scripts/testnet-faucet.ts`
`scripts/bridge-eth-to-gensyn-testnet.ts`	Bridge ETH from Sepolia to Gensyn Testnet	`npx tsx scripts/bridge-eth-to-gensyn-testnet.ts <amount-eth>`
`scripts/bridge-eth-to-gensyn-mainnet.ts`	Bridge ETH from Ethereum mainnet to Gensyn Mainnet	`npx tsx scripts/bridge-eth-to-gensyn-mainnet.ts <amount-eth>`
`scripts/bridge-usdc-to-gensyn-mainnet.ts`	Bridge USDC from Ethereum mainnet to Gensyn Mainnet via LayerZero	`npx tsx scripts/bridge-usdc-to-gensyn-mainnet.ts <amount-usdc> [slippage-pct]`

All scripts use the shared client setup from scripts/client.ts which handles environment variable configuration automatically. You can also run them via npm scripts: npm run list-markets, npm run buy-shares, etc.

Before running scripts

Before running any script in scripts/, ensure the runtime is prepared.

Required setup checklist:

Install dependencies by running npm install.
Verify required environment variables are set:
- Check for a .env file in the project root (preferred), or
- Verify environment variables are exported in the shell session
If either check fails, fix it before running any task script.
Do not call scripts/*.ts until setup succeeds.
Do not pass environment variables inline with commands - use .env file or export statements instead.

Environment variables

Only two things are mandatory: your API key and wallet signing credentials. Everything else has sensible defaults. The SDK defaults to testnet if DELPHI_NETWORK is not set.

Agent instructions for missing env vars:

When required environment variables are not set, do NOT ask the user for their values in chat. Instead:

Tell the user which variables are needed (list them below).
Tell them where to get each value.
Ask them to create a .env file in the project root themselves with those values.
Wait for them to confirm the file is created before proceeding.
NEVER read the .env file — treat it as a secret store the agent must not access.

Mandatory variables to communicate to the user:

Variable	Where to get it
`DELPHI_API_ACCESS_KEY`	Testnet: Generate at https://delphi-api-access.gensyn.ai/ · Mainnet: Generate at https://api-access.delphi.fyi/

Plus one of these signing options (tell the user to pick one):

Option A — Private key

Variable	Description
`DELPHI_SIGNER_TYPE`	Set to `private_key`
`WALLET_PRIVATE_KEY`	`0x`-prefixed hex private key for their wallet

Option B — Coinbase CDP Server Wallet (default signer, no DELPHI_SIGNER_TYPE needed)

Variable	Where to get it
`CDP_API_KEY_ID`	Server Wallet v2 Quickstart (https://docs.cdp.coinbase.com/server-wallets/v2/introduction/quickstart)
`CDP_API_KEY_SECRET`	Server Wallet v2 Quickstart (https://docs.cdp.coinbase.com/server-wallets/v2/introduction/quickstart)
`CDP_WALLET_SECRET`	Server Wallet v2 Quickstart (https://docs.cdp.coinbase.com/server-wallets/v2/introduction/quickstart)
`CDP_WALLET_ADDRESS`	Their CDP wallet address (`0x`-prefixed) (see https://docs.cdp.coinbase.com/server-wallets/v2/introduction/quickstart)

Make sure to also convey the following 2 points to the user -

For the CDP option, private keys are secured in Coinbase's Trusted Execution Environment (TEE) and never leave the TEE. See Server Wallet v2 docs for details.
To execute Delphi transactions, your signer wallet must have ETH (for gas) and USDC on the Gensyn chain.

Network selection

Variable	Values	Default
`DELPHI_NETWORK`	`"testnet"` \| `"mainnet"`	`"testnet"`

The SDK defaults to testnet — DELPHI_NETWORK is optional. Only set it if the user explicitly wants mainnet.

When DELPHI_NETWORK=testnet (default), the SDK automatically uses:

RPC URL: https://gensyn-testnet.g.alchemy.com/public
Chain ID: 685685
Gateway: 0x7b8FDBD187B0Be5e30e48B1995df574A62667147
Token: 0x0724D6079b986F8e44bDafB8a09B60C0bd6A45a1
API URL: https://delphi-api.gensyn.ai/
Subgraph URL: https://api.goldsky.com/api/public/project_cmnoqdag1obop01z3efnu8ssq/subgraphs/delphi-testnet/1.0.0/gn

When DELPHI_NETWORK=mainnet, the SDK automatically uses:

RPC URL: https://gensyn-mainnet.g.alchemy.com/public
Chain ID: 685689
Gateway: 0x4e4e85c52E0F414cc67eE88d0C649Ec81698d700
Token: 0x5b32c997211621d55a89Cc5abAF1cC21F3A6ddF5
API URL: https://api.delphi.fyi/
Subgraph URL: https://api.goldsky.com/api/public/project_cmnoqdag1obop01z3efnu8ssq/subgraphs/delphi-mainnet/1.0.0/gn

Optional overrides

These override the network defaults if you need to point at a custom endpoint:

Variable	Description
`GENSYN_RPC_URL`	Custom RPC endpoint
`GENSYN_CHAIN_ID`	Custom chain ID
`DELPHI_GATEWAY_CONTRACT`	Custom gateway contract address
`DELPHI_API_BASE_URL`	Custom API base URL
`DELPHI_SUBGRAPH_URL`	Custom Goldsky subgraph endpoint
`DELPHI_TOKEN_ADDRESS`	Override the ERC-20 collateral token address
`DELPHI_SIGNER_TYPE`	`"private_key"` or `"cdp_server_wallet"` (default)

Client setup

import {
  DelphiClient,
  SubgraphClient,
  createPrivateKeySigner,
  createCdpSigner,
} from "@gensyn-ai/gensyn-delphi-sdk";

// All config is read from environment variables automatically.
const client = new DelphiClient();

Units

Type	Raw representation	Human conversion
Shares	18-decimal bigint	`1n * 10n**18n` = 1 share
USDC	6-decimal bigint	`1_000_000n` = 1 USDC
Implied probability	18-decimal (1e18 = 100%)	`5n * 10n**17n` = 50%
Spot price	6-decimal (1e6 = 1.0 USDC/share)	`600_000n` = 0.60 USDC/share

// Human → raw bigint (inputs to SDK)
const sharesToBigint = (n: number) => BigInt(Math.round(n * 1e18));
const usdcToBigint   = (n: number) => BigInt(Math.round(n * 1e6));

// Raw bigint → display string
const toUsdc      = (n: bigint) => `${(Number(n) / 1e6).toFixed(6)} USDC`;
const toShares    = (n: bigint) => `${(Number(n) / 1e18).toFixed(4)} shares`;
const toProb      = (n: bigint) => `${(Number(n) / 1e18 * 100).toFixed(2)}%`;
const toSpotPrice = (n: bigint) => `${(Number(n) / 1e6).toFixed(4)} USDC/share`;

Core patterns

Tip: See scripts/list-markets.ts for a complete working example.

List markets

const { markets } = await client.listMarkets({
  status: "open",        // "open" | "awaiting_settlement" | "settled" | "expired"
  category: "crypto",   // crypto, culture, economics, miscellaneous, politics, sports
  limit: 20,
  skip: 0,
  orderBy: "liquidity", // "liquidity" (default) | "created"
  verifiable: true,     // optional: filter to markets with verifiable settlement
});

for (const market of markets ?? []) {
  const meta = market.metadata as {
    question?: string;
    outcomes?: string[];
    model?: { model_identifier?: string; prompt_context?: string };
    initial_liquidity?: string;
    version?: string;
  } | null;
  console.log(market.id, meta?.question);
  // market.id                     = market address — use this as marketAddress in all SDK calls
  // market.implementation         = underlying logic contract (NOT used for SDK calls)
  // market.category               = market category string (e.g. "crypto")
  // market.verifiable             = true if market uses verifiable settlement
  // market.tradingFee             = 18-decimal bigint string (e.g. "20000000000000000" = 2%); null if no fee
  //                                 convert: Number(market.tradingFee) / 1e18 * 100 → fee percentage
  // market.winningOutcomeIdx      = set after settlement, otherwise null
  // market.resolvesAt             = ISO timestamp for when market resolves, or null
  // market.settlesAt              = ISO timestamp for scheduled settlement, or null
  // market.proof                  = settlement proof string, or null
  // market.error                  = resolution error message if settlement failed, or null
  // market.fetchResponseStatus    = metadata fetch status string (e.g. "success"), or null
  // market.metadataUriContentHash = hex hash of the fetched metadata content (e.g. "0x9434...")
  // market.dataSources            = data source identifiers, or null
}

Get a single market

Tip: See scripts/get-market.ts for a complete working example.

const market = await client.getMarket({ id: "<market-id>" });
const meta = market.metadata as { question?: string; outcomes?: string[] } | null;
// market.id             = use as marketAddress for all SDK calls (quoteBuy, buyShares, etc.)
// market.implementation = the logic contract address — NOT the marketAddress for SDK calls

Live prices (on-chain read via Gateway ABI)

import { createPublicClient, http, defineChain, type Abi } from "viem";
import { DYNAMIC_PARIMUTUEL_GATEWAY_ABI, ERC20_ABI } from "@gensyn-ai/gensyn-delphi-sdk";
// ERC20_ABI is also exported for direct token interactions if needed

const chain = defineChain({
  id: Number(process.env.GENSYN_CHAIN_ID),
  name: "Gensyn Testnet",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: { default: { http: [process.env.GENSYN_RPC_URL!] } },
});
const publicClient = createPublicClient({ chain, transport: http(process.env.GENSYN_RPC_URL!) });
const gateway = process.env.DELPHI_GATEWAY_CONTRACT as `0x${string}`;

// Get implied probabilities for all outcomes
const outcomeIndices = [0n, 1n]; // adjust for outcome count
const probs = await publicClient.readContract({
  address: gateway,
  abi: DYNAMIC_PARIMUTUEL_GATEWAY_ABI as Abi,
  functionName: "spotImpliedProbabilities",
  args: [marketProxy, outcomeIndices],
}) as bigint[];

// Get spot prices
const prices = await publicClient.readContract({
  address: gateway,
  abi: DYNAMIC_PARIMUTUEL_GATEWAY_ABI as Abi,
  functionName: "spotPrices",
  args: [marketProxy, outcomeIndices],
}) as bigint[];

Quote buy (read-only, no gas)

Tip: See scripts/quote-buy.ts for a complete working example.

const { tokensIn } = await client.quoteBuy({
  marketAddress: "0x..." as `0x${string}`,
  outcomeIdx: 0,
  sharesOut: BigInt(Math.round(10 * 1e18)),  // 10 shares
});
// tokensIn = USDC cost in 6-decimal bigint
const costUsdc = Number(tokensIn) / 1e6;

Quote sell (read-only, no gas)

Tip: See scripts/quote-sell.ts for a complete working example.

const { tokensOut } = await client.quoteSell({
  marketAddress: "0x..." as `0x${string}`,
  outcomeIdx: 0,
  sharesIn: BigInt(Math.round(5 * 1e18)),  // 5 shares
});
const payoutUsdc = Number(tokensOut) / 1e6;

Buy shares (on-chain, with auto-approval)

Tip: See scripts/buy-shares.ts for a complete working example.

const marketAddress = "0x..." as `0x${string}`;
const outcomeIdx = 0;
const sharesOut = BigInt(Math.round(10 * 1e18));  // 10 shares

// 1. Quote
const { tokensIn } = await client.quoteBuy({ marketAddress, outcomeIdx, sharesOut });

// 2. Ensure USDC approval (idempotent — only sends tx if needed)
await client.ensureTokenApproval({ marketAddress, minimumAmount: tokensIn });

// 3. Buy with 2% slippage
const maxTokensIn = tokensIn * 102n / 100n;
const { transactionHash } = await client.buyShares({
  marketAddress,
  outcomeIdx,
  sharesOut,
  maxTokensIn,
});

Sell shares (on-chain)

Tip: See scripts/sell-shares.ts for a complete working example.

const sharesIn = BigInt(Math.round(5 * 1e18));

// 1. Quote
const { tokensOut } = await client.quoteSell({ marketAddress, outcomeIdx, sharesIn });

// 2. Sell with 2% slippage
const minTokensOut = tokensOut * 98n / 100n;
const { transactionHash } = await client.sellShares({
  marketAddress,
  outcomeIdx,
  sharesIn,
  minTokensOut,
});

List positions

Tip: See scripts/list-positions.ts for a complete working example.

Important: Positions with shares equal to 0 (i.e. BigInt(p.shares) === 0n) represent fully exited stakes. These cannot be redeemed or liquidated since the wallet holds no shares. Always filter out zero-share positions before attempting redeem or liquidate operations.

const { positions } = await client.listPositions({
  wallet: "0x...",
  redeemedOrLiquidated: false,  // only active positions
  limit: 50,
});

for (const p of positions ?? []) {
  const shares = Number(BigInt(p.shares)) / 1e18;
  if (shares === 0) continue; // no stake — skip
  console.log(`Market ${p.marketProxy} | Outcome ${p.outcomeIdx} | ${shares} shares`);
}

Redeem settled positions

Tip: See scripts/redeem.ts for a complete working example.

Important: Only positions with non-zero shares can be redeemed. If listPositions returns a position with shares === "0", the wallet has no stake in that market and calling redeemMarket will fail or return nothing. Always check shares > 0 before redeeming.

// Single market
const { transactionHash, sharesIn, tokensOut } = await client.redeemMarket({
  marketAddress: "0x..." as `0x${string}`,
});

// Batch
const { results, totalTokensOut } = await client.redeemPositions({
  marketAddresses: ["0x...", "0x..."],
});
for (const r of results) {
  if (r.success) console.log(`Redeemed ${Number(r.tokensOut!) / 1e6} USDC from ${r.marketAddress}`);
  else console.error(`Failed ${r.marketAddress}: ${r.error}`);
}

Liquidate expired positions

Tip: See scripts/liquidate.ts for a complete working example.

Liquidation is for positions in expired markets that were never settled. Unlike redemption (which is for settled markets with a winner), liquidation recovers tokens from markets that expired without resolution.

// Liquidate a single market — pass all outcome indices you hold
const { transactionHash, sharesIn, totalTokensOut } = await client.liquidate({
  marketAddress: "0x..." as `0x${string}`,
  outcomeIndices: [0, 1],  // all outcome indices with positions
});
// sharesIn: bigint[] — shares burned per outcome index
// totalTokensOut: bigint — total USDC recovered across all outcomes

// Derive outcome indices from listPositions:
const { positions } = await client.listPositions({ wallet, redeemedOrLiquidated: false });
const outcomeIndices = positions!
  .filter(p => p.marketProxy === marketAddress && BigInt(p.shares) > 0n)
  .map(p => Number(p.outcomeIdx));

Token approval

Tip: See scripts/token-approval.ts for a complete working example.

// Check current allowance
const { ownerAddress, allowance } = await client.getTokenAllowance({ marketAddress });

// Approve unlimited
await client.approveToken({ marketAddress });

// Approve specific amount (50 USDC)
await client.approveToken({ marketAddress, amount: 50_000_000n });

// Idempotent: only approves if current allowance is below minimum
// Response always includes current allowance, plus transactionHash if a tx was sent
const { approvalNeeded, allowance, transactionHash } = await client.ensureTokenApproval({
  marketAddress,
  minimumAmount: requiredTokens,
  approveAmount: 100_000_000n,  // optional: amount to approve if needed (defaults to max uint256)
});

Check wallet balances

Tip: See scripts/get-wallet-balances.ts for a complete working example.

// ETH (native gas token)
const ethBalance = await client.getEthBalance();
console.log(`ETH: ${(Number(ethBalance) / 1e18).toFixed(6)}`);

// ERC-20 collateral token (defaults to SDK-configured token address)
const tokenAddress = client.getTokenAddress(); // inspect the configured token address
const { balance, decimals } = await client.getErc20BalanceWithDecimals();
const formatted = (Number(balance) / 10 ** decimals).toFixed(decimals > 6 ? 6 : decimals);
console.log(`Token (${tokenAddress}): ${formatted}`);

// Or fetch raw balance only (6-decimal for USDC)
const raw = await client.getErc20Balance(); // uses default token; pass address to override

Query recent trades via subgraph

Tip: See scripts/list-recent-trades.ts for a complete working example.

The SDK's SubgraphClient queries on-chain event data indexed by a Goldsky subgraph. Access it via client.getSubgraph().

const subgraph = client.getSubgraph();

// Convenience method: get buys and sells for a market
const { buys, sells } = await subgraph.getMarketTrades(
  "0x..." as string,  // market proxy address
  { first: 20 }
);

for (const buy of buys) {
  const cost = Number(BigInt(buy.tokensIn ?? "0")) / 1e6;
  const shares = Number(BigInt(buy.sharesOut ?? "0")) / 1e18;
  const time = new Date(Number(buy.timestamp_) * 1000).toLocaleString();
  console.log(`BUY ${time} | ${cost.toFixed(4)} USDC → ${shares.toFixed(4)} shares`);
}

// Arbitrary GraphQL: recent buys across all markets
// SubgraphBuy, SubgraphSell, SubgraphMeta are all exported from the SDK for typing:
//   import type { SubgraphBuy, SubgraphSell, SubgraphMeta } from "@gensyn-ai/gensyn-delphi-sdk";
const data = await subgraph.query<{ gatewayBuys: SubgraphBuy[] }>(`{
  gatewayBuys(first: 5, orderBy: timestamp_, orderDirection: desc) {
    id buyer marketProxy tokensIn sharesOut timestamp_
  }
}`);

// Check subgraph indexing status (block number, deployment, error flag)
const meta = await subgraph.getMeta();
console.log(`Block: ${meta.block.number}, indexing errors: ${meta.hasIndexingErrors}`);

Available entities: gatewayBuys, gatewaySells, gatewayRedemptions, gatewayLiquidations, gatewayWinnerSubmitteds. All support filtering (where), ordering (orderBy + orderDirection), and pagination (first + skip).

Error handling

Error	Cause	Fix
`TokensInExceedsMax`	Price moved above `maxTokensIn`	Re-quote, increase slippage
`TokensOutBelowMin`	Price moved below `minTokensOut`	Re-quote, increase slippage
`MarketNotOpen`	Market is closed or settled	Check `market.status` first
`SharesInExceedSupply`	Selling more shares than held	Check position before selling
`Requires apiKey`	Missing `DELPHI_API_ACCESS_KEY`	Set env var
`Requires rpcUrl`	Missing `GENSYN_RPC_URL`	Set env var or let network default apply
`Requires privateKey`	Missing `WALLET_PRIVATE_KEY`	Set env var or switch to CDP signer
`CDP signing requires ...`	Missing CDP env vars	Set all `CDP_` vars

Reference files (load on demand)

File	When to load
reference/markets.md	Full `listMarkets`/`getMarket` params, `Market` type schema, metadata structure
reference/trading.md	Trading mechanics, slippage formulas, parimutuel pricing explainer
reference/positions.md	`Position`/`Trade` type schemas, batch redemption patterns, portfolio estimation
reference/onchain.md	Full Gateway ABI function list, direct `viem` read patterns, signing config
reference/subgraph.md	Goldsky subgraph GraphQL schema, `SubgraphClient` API, entity types, filtering, raw query examples
reference/funding.md	Getting ETH and USDC onto Gensyn (testnet faucet, OP Stack bridge, LayerZero USDC bridge)