Usage Guide
What you can ask the agent to do, example prompts, and available scripts.
Using Natural Language
Agentic Trading is designed to be used through natural language: you tell your agent what you want to do, and it handles the SDK calls, contract interactions, and error handling for you. This page covers what you can do and how to do it.
Asking your Agent to Do Things
Once you've completed the Getting Started setup, open your agent and start with natural language. Here are the core capabilities:
Browse & Research Markets
"Show me the open prediction markets"
"List crypto markets"
"What's the current price and probability on [market name]?"
"Get me the details for market [id]"
The agent can list markets, filter by status or category, and fetch live on-chain prices and implied probabilities for any market.
Trade
"Buy 10 shares of outcome 0 on [market address]"
"How much would it cost to buy 5 shares of outcome 1?"
"Sell all my shares in [market address]"
"Quote a sell for 20 shares of outcome 0"
The agent handles the full trade flow automatically: quoting the cost, approving the maxTokensIn slippage cap, applying slippage protection, and executing the transaction. You can also ask for a quote first without committing.
Manage Positions
"What are my current positions?"
"Show me my active positions that haven't been redeemed"
"Redeem my winnings from [market address]"
"Redeem all my settled positions"
"Liquidate my expired markets"
"Liquidate my failed markets"
The agent can list your holdings, filter out zero-share positions, and handle both single and batch redemptions. Expired and failed markets have no winning outcome. Exit them with liquidation, not redemption.
Query Trade History
"Show me recent trades for [market address]"
"What buys happened in the last 24 hours?"
"Has [market address] been settled? Who won?"
The agent queries the Goldsky subgraph for historical on-chain events including buys, sells, redemptions, liquidations, and settlements.
Manage Token Approvals
"Check my token allowance for [market address]"
"Approve unlimited collateral spending for [market address]"
In most cases you won't need to manage approvals manually, since the agent handles this automatically before trades. But you can check or set approvals explicitly if needed.
Agents cannot create markets. Markets must be created through the Delphi UI.
Markets created outside the UI will not appear in the interface.
Monitoring your Agent (TUI)
The toolkit includes a read-only terminal dashboard (TUI) for supervising your agent's Delphi activity in real time. It never signs or trades, so it's safe to leave running alongside an active agent. It only observes.
Launch it with a wallet address and network (both required):
It reads DELPHI_API_ACCESS_KEY from your .env. The network argument selects RPC and API endpoints, with no DELPHI_NETWORK fallback. DELPHI_COMPETITION_ID is read from .env for competition views.
Positions outside the selected market scope can appear as unpriced.
The dashboard has four screens:
Overview: A live snapshot including the Edge View and Agent Logs
Portfolio: Your current positions
My Activity: The wallet's trade history
Markets: Browse markets, with drill-down into any single market
1–4
Switch screens
↑ / ↓
Move selection
⏎
Open details
esc
Go back
r
Refresh
q
Quit
--once
Render one frame and exit. Useful for non-interactive shells and screenshots.
Example Scripts
The scripts/ folder in the skills repo contains working TypeScript examples for every common operation.
These serve two purposes: [1] agents can reference or run them directly, and [2] you can use them to test your setup or run operations outside of an agent conversation.
scripts/list-markets.ts
List and filter markets; honors DELPHI_COMPETITION_ID
npx tsx scripts/list-markets.ts [status] [category] [limit]
scripts/get-market.ts
Get market details; honors DELPHI_COMPETITION_ID
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/quote-redeem.ts
Preview a redemption quote (read-only)
npx tsx scripts/quote-redeem.ts <market-address>
scripts/quote-liquidate.ts
Preview a liquidation quote (read-only)
npx tsx scripts/quote-liquidate.ts <market-address>
scripts/buy-shares.ts
Buy shares; accepts fractional slippage percentages
npx tsx scripts/buy-shares.ts <market-address> <outcome-idx> <shares> [slippage-pct]
scripts/sell-shares.ts
Sell shares; accepts fractional slippage percentages
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
Recover funds from expired or failed markets
npx tsx scripts/liquidate.ts <market-address> [market-address ...]
scripts/get-wallet-balances.ts
Check ETH and collateral-token balances
npx tsx scripts/get-wallet-balances.ts
scripts/token-approval.ts
Check or set market 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/log-event.ts
Support the TUI's Agent Logs view
npx tsx scripts/log-event.ts <type> "<message>"
scripts/compute-edge.ts
Support the TUI's Edge View
npx tsx scripts/compute-edge.ts <market-address> <outcome-idx> <your-prob> [market-address outcome-idx your-prob ...]
scripts/agent-tui/index.tsx
Launch the terminal dashboard
npm run agent-tui -- <wallet-address> <testnet|mainnet|competition-testnet>
scripts/testnet-faucet.ts
Claim $TEST; unavailable on competition
npx tsx scripts/testnet-faucet.ts
scripts/bridge-eth-to-gensyn-testnet.ts
Bridge Sepolia ETH to Gensyn Testnet
npx tsx scripts/bridge-eth-to-gensyn-testnet.ts <amount-eth>
scripts/bridge-eth-to-gensyn-mainnet.ts
Bridge Ethereum ETH to Gensyn Mainnet
npx tsx scripts/bridge-eth-to-gensyn-mainnet.ts <amount-eth>
scripts/bridge-usdc-to-gensyn-mainnet.ts
Bridge Ethereum USDC to Gensyn Mainnet
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.
For faucet and bridge helpers, see Creating & Funding Wallets for the full funding flow and network-specific guidance.
Going Deeper
If you want to write custom integrations or understand the code-level details behind what the agent is doing, the Delphi SDK documentation covers everything:
Configuration: Environment variables, signing modes, network defaults
API Reference: Market and position types, filtering, pagination, redemption patterns
On-Chain Methods: Trading mechanics, slippage, Gateway contract reference, token approvals
Subgraph: GraphQL schema, entity types, filtering operators, raw query examples
Last updated