# predictarena

> Trade prediction market outcome tokens on Solana using DFlow. Discovery, wallet management, and automated trading for agents.

- Author: 0xPratik
- Repository: pratikbuilds/predict-arena
- Version: 20260206172709
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/pratikbuilds/predict-arena
- Web: https://mule.run/skillshub/@@pratikbuilds/predict-arena~predictarena:20260206172709

---

---
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 <publicKey>

# 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 <path> [--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 <category>    Filter by category (e.g., Economics, Sports)
  --tags <tags>           Comma-separated tags
  --status <status>       Filter by status
  --is-initialized        Only series with market ledger
```

**List events:**

```bash
predictarena events list [options] [--json]

Options:
  --status <status>              Event status (default: active)
  --sort <sort>                  Sort field (default: volume)
  --order <order>                Sort order (default: desc)
  --series-tickers <tickers>     Comma-separated series tickers (max 25)
  --limit <limit>                Max results
  --cursor <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 <ticker> [--with-nested-markets] [--json]
```

**List markets:**

```bash
predictarena markets list [options] [--json]

Options:
  --status <status>     Market status (default: active)
  --sort <sort>         Sort field (default: volume)
  --order <order>       Sort order (default: desc)
  --limit <limit>       Max results
  --cursor <cursor>     Pagination offset
  --is-initialized      Only markets with market ledger
```

**Get single market:**

```bash
predictarena markets get <ticker> [--json]
```

**Get market by outcome mint:**

```bash
predictarena markets get-by-mint <mint> [--json]
```

Use this to identify which market an outcome token belongs to.

**Get orderbook:**

```bash
predictarena markets orderbook <ticker> [--json]
```

### 3. Search

**Search events by title or ticker:**

```bash
predictarena search <query> [options] [--json]

Options:
  --sort <sort>               Sort field
  --order <order>             Sort order
  --limit <limit>             Limit results
  --cursor <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 <ticker>     Filter by market ticker
  --min-ts <timestamp>  Min unix timestamp
  --max-ts <timestamp>  Max unix timestamp
  --limit <limit>       Limit trades (1-1000)
  --cursor <cursor>     Pagination cursor (trade ID)
```

### 5. Trade Execution

**Execute a swap:**

```bash
predictarena trade \
  --wallet <path> \
  --input-mint <mint> \
  --output-mint <mint> \
  --amount <raw> \
  [--slippage-bps <bps>] \
  [--priority <level>] \
  [--rpc <url>] \
  [--dry-run] \
  [--no-confirm] \
  [--skip-preflight] \
  [--json]
```

**Required flags:**
- `--wallet <path>`: Path to wallet keypair JSON file
- `--input-mint <mint>`: Input token mint address
- `--output-mint <mint>`: Output token mint address
- `--amount <raw>`: Input amount (raw integer, e.g., 1000000 for 1 USDC with 6 decimals)

**Optional flags:**
- `--slippage-bps <bps>`: Slippage in basis points (default: 50)
- `--priority <level>`: Priority fee - `auto`, `medium`, `high`, `veryHigh`, `disabled`, or lamports number (default: auto)
- `--rpc <url>`: 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 <ticker> --json
# Extract: data.yesMint or data.noMint

# 3. Dry run to verify trade
predictarena trade \
  --wallet ./agent-wallet.json \
  --input-mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --output-mint <yesMint or noMint> \
  --amount 1000000 \
  --dry-run \
  --json

# 4. Execute trade
predictarena trade \
  --wallet ./agent-wallet.json \
  --input-mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --output-mint <yesMint or noMint> \
  --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 <outcomeMint> --json

# 3. Execute sell trade
predictarena trade \
  --wallet ./agent-wallet.json \
  --input-mint <outcomeMint> \
  --output-mint EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v \
  --amount <raw outcome token amount> \
  --json
```

### Workflow 3: Redeem After Settlement

```bash
# 1. Check market status
predictarena markets get <ticker> --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 <winningOutcomeMint> \
  --output-mint <settlementMint> \
  --amount <raw outcome token 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 <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 <ticker> --json

# Trade
predictarena trade \
  --wallet ./wallet.json \
  --input-mint <mint> \
  --output-mint <mint> \
  --amount <raw> \
  --dry-run --json

# Execute
predictarena trade \
  --wallet ./wallet.json \
  --input-mint <mint> \
  --output-mint <mint> \
  --amount <raw> \
  --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