On-Chain Methods

Trading, quoting, token approvals, and direct Gateway contract interaction via RPC.

Overview

On-chain methods send transactions or read directly from the Gensyn blockchain via the Gateway contract, which is the single entry point for all on-chain interactions.

Contract Addresses

You can find Testnet and mainnet RPC endpoints, contract addresses, and more by visiting Network Information on the Gensyn Foundation docs.

Trading

Pricing Mechanism (DPM)

Delphi uses Dynamic Parimutuel (DPM) markets. This means:

• Prices shift continuously with every trade (no fixed order book)

• spotImpliedProbability reflects the market's current consensus probability

• For a binary market: prob[0] + prob[1] = 1e18 (100%)

• A spot price of 0.65 USDC/share means ~65% implied probability

Quoting Trades

These are read-only and therefore do not consume any gas.

quoteBuy

The cost to receive an exact number of shares.

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

quoteSell

The payout for selling an exact number of shares.

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

Buying Shares

Token approval must exist before buying. The full flow with approval and slippage looks like this:

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

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

// 2. Ensure USDC approval (no-op if already approved)
await client.ensureTokenApproval({ marketAddress, minimumAmount: tokensIn });

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

BuyShares (params)

Field	Type	Description
marketAddress	`0x${string}`	Market proxy address
outcomeIdx	number	Outcome index to buy
sharesOut	bigint	Exact shares to receive (18 decimals)
maxTokensIn	bigint	Max USDC to spend — slippage cap (6 decimals)

Selling Shares

const sharesIn = BigInt(Math.round(5 * 1e18));
const { tokensOut } = await client.quoteSell({ marketAddress, outcomeIdx, sharesIn });

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

SellShares (params)

Field	Type	Description
marketAddress	`0x${string}`	Market proxy address
outcomeIdx	number	Outcome index to sell
sharesIn	bigint	Exact shares to sell (18 decimals)
minTokensOut	bigint	Min USDC to receive — slippage floor (6 decimals)

Slippage Guidelines

Scenario	Recommended slippage
Quiet market	1–2%
Active market	2–5%
Large trade (>$100)	5–10%
Time-sensitive execution	5%

Here's an example of using integer arithmetic to avoid floating point:

const slippageBps = 200n; // 200 = 2%
const maxTokensIn  = tokensIn  * (10000n + slippageBps) / 10000n;
const minTokensOut = tokensOut * (10000n - slippageBps) / 10000n

Common Contract Errors

Error	Cause	Fix
TokensInExceedsMax	Actual cost > maxTokensIn	Re-quote and increase slippage
TokensOutBelowMin	Actual payout < minTokensOut	Re-quote and increase slippage
MarketNotOpen	Market closed or settled	Cannot trade; check status
SharesInExceedSupply	Selling more than held	Query balance first
GrossTokensOutNotPositive	Nothing to sell	Position is empty
ZeroTokensIn	sharesOut too small	Use a larger share amount

Token Approvals

getTokenAllowance(params)

Read the current ERC-20 allowance your wallet has granted to a market.

const { allowance } = await client.getTokenAllowance({
  marketAddress: "0xMarket",
});

approveToken(params)

Approve the ERC-20 token for spending by a market.

This defaults to unlimited (uint256 max).

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

// Approve exact amount (e.g. 100 USDC)
await client.approveToken({ marketAddress, amount: 100_000_000n });

ensureTokenApproval(params)

Check if sufficient allowance exists and only sends an approval transaction if needed. Recommended before buying shares.

const { approvalNeeded, allowance, transactionHash } = await client.ensureTokenApproval({
  marketAddress: "0xMarket",
  minimumAmount: tokensIn,
  approveAmount: tokensIn * 10n, // optional; defaults to unlimited
});

The SDK resolves the collateral token address from Gateway.token(marketProxy) automatically so there is no need to hardcode it.

Gateway Contract Reference

This section is for advanced users who want to call the Gateway contract directly via viem.

viem Client Setup

Set up your viem client like this:

import { createPublicClient, http, defineChain, type Abi } from "viem";
import { DYNAMIC_PARIMUTUEL_GATEWAY_ABI } from "@gensyn-ai/gensyn-delphi-sdk";

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}`;

Gateway Functions

All of the gateway functions, broken down into tables by [1] read and [2] write.

1. Read Functions

Function	Args	Returns	Notes
quoteBuyExactOut	marketProxy, outcomeIdx, sharesOut	tokensIn: uint256	USDC cost (6 dec)
quoteSellExactIn	marketProxy, outcomeIdx, sharesIn	tokensOut: uint256	USDC payout (6 dec)
spotImpliedProbability	marketProxy, outcomeIdx	uint256	1e18 = 100%
spotImpliedProbabilities	marketProxy, outcomeIndices[]	uint256[]	Batch
spotPrice	marketProxy, outcomeIdx	uint256	1e18 = 1.0 USDC/share
spotPrices	marketProxy, outcomeIndices[]	uint256[]	Batch
balanceOf	marketProxy, owner, outcomeIdx	uint256	Shares (18 dec)
batchBalanceOf	marketProxy, owners[], outcomeIndices[]	uint256[]	Batch
totalSupply	marketProxy, outcomeIdx	uint256	Total shares (18 dec)
totalSupplies	marketProxy, outcomeIndices[]	uint256[]	Batch
getMarket	marketProxy	Market struct	Full on-chain state
marketStatus	marketProxy	uint8	0=Open, 1=Closed, 2=Settled
token	marketProxy	address	Collateral token address

2. Write Functions

Prefer the SDK methods over calling the Gateway directly, as they handle simulation, approval, and receipt waiting.

Function	Args	Notes
buyExactOut	marketProxy, outcomeIdx, sharesOut, maxTokensIn	Use DelphiClient.buyShares()
sellExactIn	marketProxy, outcomeIdx, sharesIn, minTokensOut	Use DelphiClient.sellShares()
redeem	marketProxy	Use DelphiClient.redeemMarket()

Direct Read Examples

Implied Probability for All Outcomes

const probs = await publicClient.readContract({
  address: gateway,
  abi: DYNAMIC_PARIMUTUEL_GATEWAY_ABI as Abi,
  functionName: "spotImpliedProbabilities",
  args: [marketProxy, [0n, 1n]],
}) as bigint[];
// probs[i] / 1e18 * 100 = implied probability %

Spot Prices

const prices = await publicClient.readContract({
  address: gateway,
  abi: DYNAMIC_PARIMUTUEL_GATEWAY_ABI as Abi,
  functionName: "spotPrices",
  args: [marketProxy, [0n, 1n]],
}) as bigint[];
// prices[i] / 1e18 = USDC per share

Full Market State

const onchainMarket = await publicClient.readContract({
  address: gateway,
  abi: DYNAMIC_PARIMUTUEL_GATEWAY_ABI as Abi,
  functionName: "getMarket",
  args: [marketProxy],
}) as {
  config: {
    outcomeCount: bigint;
    k: bigint;
    tradingFee: bigint;         // 1e18 = 100%
    tradingDeadline: bigint;    // Unix timestamp
    settlementDeadline: bigint; // Unix timestamp
  };
  pool: bigint;
  tradingFees: bigint;
};

const feePercent = Number(onchainMarket.config.tradingFee) / 1e18 * 100;
const deadline = new Date(Number(onchainMarket.config.tradingDeadline) * 1000);

Share Balance for a Wallet

const balance = await publicClient.readContract({
  address: gateway,
  abi: DYNAMIC_PARIMUTUEL_GATEWAY_ABI as Abi,
  functionName: "balanceOf",
  args: [marketProxy, walletAddress as `0x${string}`, BigInt(outcomeIdx)],
}) as bigint;
// balance / 1e18 = shares

Price Impact Estimation

const spotPrices = await publicClient.readContract({
  address: gateway,
  abi: DYNAMIC_PARIMUTUEL_GATEWAY_ABI as Abi,
  functionName: "spotPrices",
  args: [marketProxy, [0n, 1n]],
}) as bigint[];

const currentPricePerShare = Number(spotPrices[outcomeIdx]) / 1e18;
const { tokensIn } = await client.quoteBuy({ marketAddress, outcomeIdx, sharesOut });
const quotedPricePerShare = (Number(tokensIn) / 1e6) / sharesHuman;
const priceImpact = ((quotedPricePerShare - currentPricePerShare) / currentPricePerShare) * 100;
console.log(`Price impact: ${priceImpact.toFixed(2)}%`);