Openfish CLI

Install

Homebrew (macOS / Linux)

brew tap Openfish/openfish-cli https://github.com/Openfish/openfish-cli
brew install openfish

Shell script (one-liner)

curl -sSL https://raw.githubusercontent.com/Openfish/openfish-cli/main/install.sh | sh

Build from source

Requires Rust 1.88+.

git clone https://github.com/Openfish/openfish-cli
cd openfish-cli
cargo install --path .

Update

openfish upgrade
# or
brew upgrade openfish

Verify installation

openfish --version   # prints version
openfish status      # checks API connectivity

First-Time Setup

The guided setup wizard handles wallet creation and contract approvals in one step:

openfish setup

Or do it manually:

# 1. Create or import a wallet
openfish wallet create
# or
openfish wallet import 0xYOUR_PRIVATE_KEY

# 2. Approve Openfish contracts (needs MATIC for gas)
openfish approve set

# 3. Check your balance
openfish clob balance --asset-type collateral

Configuration

Private Key

The CLI looks for your private key in this order:

--private-key 0x... flag
OPENFISH_PRIVATE_KEY environment variable
Config file at ~/.config/openfish/config.json

Config file format:

{
  "private_key": "0x...",
  "chain_id": 137,
  "signature_type": "proxy"
}

Security: Never commit your private key to source control. Use environment variables or the config file. The config file is created with 600 permissions.

Signature Types

Type	Description	Gas
`proxy` (default)	Openfish proxy wallet	Gasless (relayer pays)
`eoa`	Direct wallet signing	You pay gas in MATIC
`gnosis-safe`	Gnosis Safe multisig	Gasless (relayer pays)

Override per-command: --signature-type eoa or OPENFISH_SIGNATURE_TYPE=eoa.

What Needs a Wallet

Most read operations work without a wallet:

No wallet needed	Wallet required
Browse markets	Place/cancel orders
View order books	Check your balances
Check prices	On-chain operations (approve, split, merge, redeem)
View leaderboards	API key management
Search events	Bridge operations

Output Formats

Every command supports two output modes:

# Human-readable table (default)
openfish markets list --limit 3

# Machine-readable JSON (for scripts and integrations)
openfish -o json markets list --limit 3

Short form: -o json or --output json.

Errors follow the same pattern: table mode prints Error: ... to stderr, JSON mode prints {"error": "..."} to stdout. Non-zero exit code in both cases.

Browsing Markets

List and search

# Browse active markets
openfish markets list --limit 10
openfish markets list --active true --order volume_num

# Search by keyword
openfish markets search "bitcoin" --limit 5

# Get market details
openfish markets get will-trump-win-the-2024-election
openfish markets get 12345

Events

Events group related markets (e.g., “2024 Election” contains multiple yes/no markets).

openfish events list --limit 10
openfish events list --tag politics --active true
openfish events get 500

Tags and series

openfish tags list
openfish tags get politics
openfish series list --limit 10

Order Book & Prices

All read-only, no wallet needed.

# Single token
openfish clob price <token_id> --side buy
openfish clob midpoint <token_id>
openfish clob spread <token_id>
openfish clob book <token_id>

# Batch (comma-separated)
openfish clob batch-prices "TOKEN1,TOKEN2" --side buy
openfish clob midpoints "TOKEN1,TOKEN2"
openfish clob books "TOKEN1,TOKEN2"

# Price history
openfish clob price-history <token_id> --interval 1d --fidelity 30

Intervals: 1m, 1h, 6h, 1d, 1w, max

Trading

Requires a configured wallet.

Place orders

# Limit order: buy 10 shares at $0.50
openfish clob create-order \
  --token <token_id> \
  --side buy --price 0.50 --size 10

# Market order: buy $5 worth
openfish clob market-order \
  --token <token_id> \
  --side buy --amount 5

# Batch orders
openfish clob post-orders \
  --tokens "TOKEN1,TOKEN2" \
  --side buy \
  --prices "0.40,0.60" \
  --sizes "10,10"

Order types: GTC (default, Good Till Cancelled), FOK (Fill Or Kill), GTD (Good Till Date), FAK (Fill And Kill). Add --post-only for limit orders that should only add liquidity.

Cancel orders

openfish clob cancel <order_id>
openfish clob cancel-orders "ORDER1,ORDER2"
openfish clob cancel-market --market <condition_id>
openfish clob cancel-all

View your activity

openfish clob orders
openfish clob orders --market <condition_id>
openfish clob order <order_id>
openfish clob trades

Check balances

openfish clob balance --asset-type collateral
openfish clob balance --asset-type conditional --token <token_id>

CTF Operations

Split, merge, and redeem conditional tokens on-chain. Requires MATIC for gas.

# Split $10 USDC into YES + NO tokens
openfish ctf split --condition <condition_id> --amount 10

# Merge YES + NO tokens back to USDC
openfish ctf merge --condition <condition_id> --amount 10

# Redeem winning tokens after market resolution
openfish ctf redeem --condition <condition_id>

--amount is in USDC (e.g., 10 = $10.00).

Contract Approvals

Before trading, Openfish contracts need ERC-20 (USDC) and ERC-1155 (CTF) token approvals.

# Check current approval status
openfish approve check

# Approve all contracts (sends 6 on-chain transactions)
openfish approve set

Portfolio & On-Chain Data

Public data, no wallet needed.

# Your positions
openfish data positions <wallet_address>
openfish data closed-positions <wallet_address>
openfish data value <wallet_address>

# Trade history
openfish data trades <wallet_address> --limit 50

# Market analytics
openfish data holders <condition_id>
openfish data open-interest <condition_id>

# Leaderboards
openfish data leaderboard --period month --order-by pnl --limit 10

API Key Management

openfish clob api-keys         # List your API keys
openfish clob create-api-key   # Generate a new key
openfish clob delete-api-key   # Revoke an existing key

Bridge

Move assets between Openfish and other chains.

openfish bridge deposit <wallet_address>        # Get deposit addresses
openfish bridge supported-assets                # List supported chains/tokens
openfish bridge status <deposit_address>        # Check deposit status

Wallet Management

openfish wallet create           # Generate new wallet
openfish wallet import <key>     # Import existing private key
openfish wallet address          # Print wallet address
openfish wallet show             # Full wallet info
openfish wallet reset            # Delete config (prompts confirmation)

Interactive Shell

Launch a REPL for quick exploration:

openfish shell

openfish> markets list --limit 3
openfish> clob book <token_id>
openfish> exit

All commands work the same as the CLI, just without the openfish prefix. Supports command history.

Scripting Examples

Fetch market prices as JSON

openfish -o json markets list --limit 100 | jq '.[].question'

Check a price programmatically

openfish -o json clob midpoint <token_id> | jq '.mid'

Error handling in scripts

if ! result=$(openfish -o json clob balance --asset-type collateral 2>/dev/null); then
  echo "Failed to fetch balance"
  exit 1
fi
echo "Balance: $(echo $result | jq '.balance')"

Monitor and trade loop

while true; do
  price=$(openfish -o json clob midpoint $TOKEN | jq -r '.mid')
  if (( $(echo "$price < 0.30" | bc -l) )); then
    openfish clob market-order --token $TOKEN --side buy --amount 10
    echo "Bought at $price"
  fi
  sleep 60
done

Common Workflows

Research a market

openfish markets search "bitcoin" --limit 5
openfish markets get bitcoin-above-100k
openfish clob book <token_id>
openfish clob price-history <token_id> --interval 1d

New wallet to first trade

openfish wallet create
openfish approve set                    # needs MATIC for gas
openfish clob balance --asset-type collateral
openfish clob market-order --token <token_id> --side buy --amount 5

Monitor portfolio

openfish data positions <your_address>
openfish data value <your_address>
openfish clob orders
openfish clob trades

Troubleshooting

Problem	Solution
`Error: no private key configured`	Run `openfish wallet create` or set `OPENFISH_PRIVATE_KEY`
`Error: insufficient allowance`	Run `openfish approve set`
`Error: insufficient balance`	Deposit USDC.e to your Polygon wallet
`Error: connection refused`	Check `openfish status`, API may be down
`Error: insufficient gas`	Send MATIC to your wallet for on-chain operations
Command not found	Verify installation with `which openfish`