--- name: predictarena description: Trade prediction market outcome tokens on Solana using DFlow. Discovery, wallet management, and automated trading for agents. license: MIT metadata: author: PredictArena version: "0.1.0" requires: ["node >= 18"] --- # PredictArena Trading Skill Complete guidance for prediction market discovery and trading on Solana using the PredictArena CLI. Designed for autonomous agents, trading bots, and automation scripts. ## Prerequisites Check (Always Run First) Before using any commands, ensure the CLI is available: 1. **Check Node.js version**: `node --version` (must be >= 18) 2. **Install CLI**: `npm install -g predictarena` or use `npx predictarena` (no install) 3. **Test CLI**: `predictarena --help` From source (development): `npm install && npm run build` then `node dist\/bin.mjs --help`. ## Environment Setup (Required for Trading) Set these environment variables before trading: ```bash # RPC endpoint (REQUIRED for trade execution) export SOLANA_RPC_URL="https:\/\/api.mainnet-beta.solana.com" # or export PREDICTARENA_RPC_URL="https:\/\/your-rpc-endpoint.com" # API endpoints (optional, defaults to dev) export METADATA_API_BASE="https:\/\/dev-prediction-markets-api.dflow.net" export TRADE_API_BASE="https:\/\/dev-quote-api.dflow.net" # API key (optional for dev, rate-limited without) export DFLOW_API_KEY="your-api-key" # or export PREDICTARENA_API_KEY="your-api-key" # Wallet path (optional, can be passed via --wallet flag) export PREDICTARENA_WALLET=".\/agent-wallet.json" # or export WALLET_PATH=".\/agent-wallet.json" ``` **For production**: Request an API key at `https:\/\/docs.dflow.net\/build\/api-key`. ## First-Time Setup Checklist Run these commands in order for initial setup: ```bash # 1. Install CLI npm install -g predictarena # or use npx predictarena for each command (no install) # 2. Create a wallet for trading predictarena wallet create .\/agent-wallet.json --json # 3. Fund the wallet (copy publicKey from step 2 output) # Use Solana CLI or transfer SOL\/USDC to the public key # 4. Verify wallet funding solana balance # 5. Test market discovery predictarena markets list --limit 3 --json ``` ## Command Reference All commands support: - `--json`: Structured JSON output with `data`, `pagination`, `_hints` - `--verbose`: Enable verbose logging for debugging - Default output: Human-readable full JSON (no truncation) ### 1. Wallet Management **Create a new Solana keypair:** ```bash predictarena wallet create [--json] ``` **Output (--json):** ```json { "data": { "publicKey": "8xK...", "path": ".\/agent-wallet.json" } } ``` **Agent usage:** - Always use `--json` flag for structured output - Parse `data.publicKey` and fund it before trading - Store the keypair path securely - File format: standard Solana keypair (JSON array of 64 bytes) ### 2. Market Discovery **List all categories:** ```bash predictarena categories [--json] ``` Use categories to discover series tickers for filtering. **List series templates:** ```bash predictarena series [options] [--json] Options: --category Filter by category (e.g., Economics, Sports) --tags Comma-separated tags --status Filter by status --is-initialized Only series with market ledger ``` **List events:** ```bash predictarena events list [options] [--json] Options: --status Event status (default: active) --sort Sort field (default: volume) --order Sort order (default: desc) --series-tickers Comma-separated series tickers (max 25) --limit Max results --cursor Pagination offset --is-initialized Only events with market ledger --with-nested-markets Include nested markets (default: true) ``` **Get single event:** ```bash predictarena events get [--with-nested-markets] [--json] ``` **List markets:** ```bash predictarena markets list [options] [--json] Options: --status Market status (default: active) --sort Sort field (default: volume) --order Sort order (default: desc) --limit Max results --cursor Pagination offset --is-initialized Only markets with market ledger ``` **Get single market:** ```bash predictarena markets get [--json] ``` **Get market by outcome mint:** ```bash predictarena markets get-by-mint [--json] ``` Use this to identify which market an outcome token belongs to. **Get orderbook:** ```bash predictarena markets orderbook [--json] ``` ### 3. Search **Search events by title or ticker:** ```bash predictarena search [options] [--json] Options: --sort Sort field --order Sort order --limit Limit results --cursor Pagination offset --with-nested-markets Include nested markets (default: true) --with-market-accounts Include market account info ``` **Example:** ```bash predictarena search "bitcoin" --limit 5 --json ``` ### 4. Trade History **List trades:** ```bash predictarena trades list [options] [--json] Options: --ticker Filter by market ticker --min-ts Min unix timestamp --max-ts Max unix timestamp --limit Limit trades (1-1000) --cursor Pagination cursor (trade ID) ``` ### 5. Trade Execution **Execute a swap:** ```bash predictarena trade \ --wallet \ --input-mint \ --output-mint \ --amount \ [--slippage-bps ] \ [--priority ] \ [--rpc ] \ [--dry-run] \ [--no-confirm] \ [--skip-preflight] \ [--json] ``` **Required flags:** - `--wallet `: Path to wallet keypair JSON file - `--input-mint `: Input token mint address - `--output-mint `: Output token mint address - `--amount `: Input amount (raw integer, e.g., 1000000 for 1 USDC with 6 decimals) **Optional flags:** - `--slippage-bps `: Slippage in basis points (default: 50) - `--priority `: Priority fee - `auto`, `medium`, `high`, `veryHigh`, `disabled`, or lamports number (default: auto) - `--rpc `: Solana RPC URL (overrides env vars) - `--dry-run`: Fetch order and print quote only; do not sign or send - `--no-confirm`: Send transaction but do not wait for confirmation - `--skip-preflight`: Skip preflight simulation (default: false) **Output (--json):** Dry run: ```json { "data": { "trade": { "inputMint": "EPjF...", "outputMint": "7xK...", "inAmount": "1000000", "outAmount": "980000", "inputMintDecimals": 6, "outputMintDecimals": 6, "executionMode": "instant", "marketTicker": "BTC-100K-2024", "eventTicker": "BTC-PRICE-2024", "marketTitle": "Bitcoin to reach $100k in 2024?" }, "dryRun": true, "quote": { "minOutAmount": "970000", "priceImpactPct": "0.5", "lastValidBlockHeight": 250000000 }, "message": "Dry run — no transaction signed or sent." } } ``` Actual trade: ```json { "data": { "trade": { "inputMint": "EPjF...", "outputMint": "7xK...", "inAmount": "1000000", "outAmount": "980000", "inputMintDecimals": 6, "outputMintDecimals": 6, "executionMode": "instant", "marketTicker": "BTC-100K-2024", "eventTicker": "BTC-PRICE-2024", "marketTitle": "Bitcoin to reach $100k in 2024?" }, "result": { "signature": "5xK...", "confirmed": true, "orderStatus": { "status": "filled", "fills": [...] } } } } ``` ## Trading Workflows ### Workflow 1: Open a Position (Buy YES\/NO) ```bash # 1. Discover active markets predictarena markets list --status active --limit 10 --json # 2. Get market details to find outcome mints predictarena markets get --json # Extract: data.yesMint or data.noMint # 3. Dry run to verify trade predictarena trade \ --wallet .\/agent-wallet.json \ --input-mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \ --output-mint \ --amount 1000000 \ --dry-run \ --json # 4. Execute trade predictarena trade \ --wallet .\/agent-wallet.json \ --input-mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \ --output-mint \ --amount 1000000 \ --json ``` ### Workflow 2: Close a Position (Sell YES\/NO) ```bash # 1. Get wallet's outcome token balance solana-cli or web3.js to check token accounts # 2. Get market details to verify settlement mint predictarena markets get-by-mint --json # 3. Execute sell trade predictarena trade \ --wallet .\/agent-wallet.json \ --input-mint \ --output-mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \ --amount \ --json ``` ### Workflow 3: Redeem After Settlement ```bash # 1. Check market status predictarena markets get --json # Verify: data.status is "determined" or "finalized" # Verify: data.redemptionStatus is "open" # 2. Redeem outcome tokens predictarena trade \ --wallet .\/agent-wallet.json \ --input-mint \ --output-mint \ --amount \ --json ``` ## Known Mints (Reference) - **SOL (wrapped)**: `So11111111111111111111111111111111111111112` - **USDC**: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` - **CASH**: `CASHx9KJUStyftLFWGvEVf59SGeG9sh5FfcnZMVPCASH` ## Error Handling Common errors and resolutions: | Error | Cause | Resolution | |-------|-------|------------| | `Wallet path required` | Missing `--wallet` flag or env var | Set `PREDICTARENA_WALLET` or use `--wallet` | | `RPC URL required` | Missing RPC endpoint | Set `SOLANA_RPC_URL` or use `--rpc` | | `Order failed (404)` | Invalid mint or market not found | Verify mints with `markets get-by-mint` | | `Quote expired` | Transaction too old | Retry trade immediately | | `Order has no lastValidBlockHeight` | Cannot confirm transaction | Use `--no-confirm` flag | | WalletLoadError | Invalid keypair file | Recreate wallet with `wallet create` | ## Agent Best Practices 1. **Always dry run first**: Use `--dry-run` to verify trade intent, market, and pricing before execution 2. **Use `--json` flag**: Parse structured output instead of human-readable text 3. **Check market status**: Only trade on `active` markets; check `redemptionStatus` before redeeming 4. **Handle errors gracefully**: Catch API errors (404, 400, 500) and retry with exponential backoff 5. **Secure wallet files**: Never log or expose keypair files; use environment variables for paths 6. **Monitor transactions**: After trading, check `result.signature` and `result.confirmed` status 7. **Rate limiting**: Dev endpoints are rate-limited; use production API key for high-frequency trading 8. **Decimal conversions**: Outcome tokens use Token-2022 and may have variable decimals; use `inputMintDecimals` and `outputMintDecimals` from trade output ## Pagination Pattern Commands that return lists support cursor-based pagination: ```bash # First page predictarena markets list --limit 10 --json # Extract: data.cursor # Next page predictarena markets list --limit 10 --cursor --json ``` The `_hints.next` field in JSON output provides the exact command for the next page. ## Testing and Validation Before deploying to production: 1. **Test wallet creation**: `predictarena wallet create .\/test-wallet.json --json` 2. **Test market discovery**: `predictarena markets list --limit 3 --json` 3. **Test dry run trading**: Use `--dry-run` to verify order construction 4. **Test small trades**: Start with small amounts (e.g., 0.01 USDC = 10000 raw) 5. **Run integration tests**: `npm test` (requires live API access) ## Market Lifecycle States Understand market status before trading: - `initialized`: Market created but not yet active - `active`: Trading is open (agents should trade here) - `inactive`: Trading paused temporarily - `closed`: Trading ended, awaiting determination - `determined`: Outcome decided, redemption may be open - `finalized`: Final state, redemption available **Redemption status** (separate from market status): - `open`: Users can redeem outcome tokens for settlement mint - `closed`: Redemption not available ## Advanced: Platform Fees To charge platform fees on trades (monetization): 1. Create a fee token account for your platform 2. Add fee parameters to trade command (requires custom API integration) 3. Fees only apply on successful trades 4. Constraints: Fees can only be collected from `outputMint` in standard trades *Note: Platform fee configuration requires code changes to the trade command. Contact DFlow for production fee setup.* ## References - **Trade API docs**: https:\/\/docs.dflow.net\/build\/trading-api\/introduction - **Metadata API docs**: https:\/\/docs.dflow.net\/build\/metadata-api\/introduction - **DFlow skill**: https:\/\/pond.dflow.net\/skill.md - **DFlow docs index**: https:\/\/pond.dflow.net\/llms.txt - **Compliance**: https:\/\/docs.dflow.net\/legal\/prediction-market-compliance ## Quick Reference **Setup sequence:** ```bash npm install -g predictarena # or: npx predictarena predictarena wallet create .\/wallet.json --json # Fund the wallet predictarena markets list --json ``` **Trading sequence:** ```bash # Discovery predictarena search "query" --json predictarena markets get --json # Trade predictarena trade \ --wallet .\/wallet.json \ --input-mint \ --output-mint \ --amount \ --dry-run --json # Execute predictarena trade \ --wallet .\/wallet.json \ --input-mint \ --output-mint \ --amount \ --json ``` ## Support For issues or questions: - Check error messages in `--verbose` mode - Review DFlow documentation at https:\/\/docs.dflow.net - Test with `--dry-run` before live trades - Verify RPC endpoint connectivity - Ensure wallet is funded with SOL for transaction fees