Ape Church Gambler

Ape Church CLI 🦍🎰

Summary: Agent-facing manual for the Ape Church CLI skill bundle. Documents commands, game syntax, automation patterns, JSON schemas, bankroll constraints, and recommended operating flows.

Fully on-chain, decentralized casino on ApeChain.

Every bet is placed and settled on-chain via smart contracts. Provably fair with Chainlink VRF randomness. No servers, no trust required.

Use --resilient for long autonomous runs. Generic transient errors and reverted receipts retry after 30s, 1m, 2m, 5m, 10m × 6, and 1h × 7; network/DNS, allowlisted pause guards (PRICE TOO LOW, PvH GAMES PAUSED, All Games Paused, Paused), RNG/VRF, out-of-gas, and RPC-node failures retry after 3m, 7m, 10m × 5, 30m × 10, and 1h × 18. These policies are hard-coded and finite.

Table of Contents

1. Quick Start
2. History Download & Reporting
3. All Games
4. Loop Mode & Automation
5. Betting Strategies
6. Blackjack
7. Video Poker
8. Commands Reference
9. JSON Output Schemas
10. Agent Play Patterns
11. Costs & Limits

Quick Start

# Install
npm install -g @n0ther/apechurch-cli

# Optional for non-interactive local signing
export APECHURCH_CLI_PASS=your-local-password

# Optional to override the username/profile API
export APECHURCH_CLI_PROFILE_URL=https://www.ape.church/api/profile

# Fresh install/import prompts securely for the private key
apechurch-cli install --username MY_AGENT

# Fund wallet with APE on ApeChain (address shown after install)
# Bridge: https://relay.link/bridge/apechain

# Check status
apechurch-cli status

# Download wallet history from chain data
apechurch-cli wallet download

# Read cached history stats
apechurch-cli history --stats

# Play one random game/config automatically
apechurch-cli play --auto

# Play continuously
apechurch-cli play --loop

On a fresh install/reinstall, apechurch-cli install prompts securely for the private key with hidden input unless ~/.apechurch-cli/wallets/current.json already points to an encrypted wallets/<address>.json entry. APECHURCH_CLI_PK remains an optional non-interactive fallback, APECHURCH_CLI_PASS is required for non-interactive install/signing, and APECHURCH_CLI_PROFILE_URL overrides the default username/profile API.

History Download & Reporting

Use wallet download to reconstruct supported gaming history directly from ApeChain into a local per-wallet cache, then read it with history.

If [address] is omitted, both commands use the local wallet address.

# Download the local wallet history
apechurch-cli wallet download

# Download a specific address
apechurch-cli wallet download 0x1234...abcd

# Scan only a recent block range
apechurch-cli wallet download 0x1234...abcd --from-block 35000000 --to-block 35300000

# Rebuild the local history file from genesis
apechurch-cli wallet download 0x1234...abcd --from-block 0

# JSON output for automation
apechurch-cli wallet download 0x1234...abcd --json

# Read saved history and stats
apechurch-cli history 0x1234...abcd

# Show more than the default 10 cached games
apechurch-cli history 0x1234...abcd --limit 25

# Show every cached game
apechurch-cli history 0x1234...abcd --all

# Stats only
apechurch-cli history 0x1234...abcd --stats

# Stats split by game
apechurch-cli history 0x1234...abcd --breakdown

# Weekly wAPE wagered totals with play breakdowns
apechurch-cli history 0x1234...abcd --leaderboard

# Refresh before reading
apechurch-cli history 0x1234...abcd --refresh

# Merge a full-range refresh before reading
apechurch-cli history 0x1234...abcd --refresh --from-block 0

Sync and cache behavior:

• wallet download is incremental by default. Without --from-block, it resumes from last_synced_block + 1.
• Use wallet download --from-block 0 to rebuild the local history file from scratch, or pass an explicit historical range to fill older blocks.
• Explicit backfills and history --refresh are merged into the local file and deduplicated by contract + game_id.
• history --refresh runs the same sync path before reading the local file, but it does not clear cached records first.
• The default or explicit --chunk-size is an initial maximum block span; oversized or timed-out RPC log ranges shrink automatically, the learned size is reused, and completed initial ranges are checkpointed.
• Cached metadata normalization is local. RPC metadata enrichment and incomplete stateful rehydration run only during refresh/download and progressively process bounded legacy backlogs.
• Plain history reads current balances after loading the cache; history --offline performs no RPC reads.
• history shows 👀 Recent Games plus 📜 History Stats by default. --stats suppresses the game list, while --breakdown appends the same stats split by game.
• Standard history output also includes a compact 🎮 Game Status section with per-game played, net, win rate, RTP, and local unfinished counts when available.

Report Fields

Wallet Download Options

History Options

Coverage Limits

• Downloaded histories live under ~/.apechurch-cli/history/<wallet>_history.json.
• Economic totals only include games whose wager, payout, fees, gas, and GP can be reconstructed exactly from on-chain data. Total wAPE wagered uses the canonical wager_wei.
• Enumerates the supported single-transaction games in the local registry via indexed GameEnded(user, ...) logs.
• Blackjack and Video Poker cannot yet be generically enumerated from raw RPC, so locally-known entries remain minimal until a reliable fetch path is implemented.
• Sponsored transactions contribute 0 contract fees and 0 gas for the analyzed wallet.

All Games

Quick Reference

ApeStrong ✔︎ (Dice)

Pick your win probability. Roll under your number to win.

apechurch-cli play ape-strong <amount> --cover <cover>
apechurch-cli play ape-strong 10 --cover 50      # 50% chance, 1.95x payout
apechurch-cli play ape-strong 10 --cover 25      # 25% chance, 3.9x payout
apechurch-cli play ape-strong 10 --cover 75      # 75% chance, 1.2999x payout

Aliases: strong, dice, limbo ABI verified: true

Roulette

American roulette with 0, 00, and 1-36.

apechurch-cli play roulette <amount> <bet>
apechurch-cli play roulette 10 RED        # Color bet (2.05x)
apechurch-cli play roulette 10 17         # Single number (36.9x)
apechurch-cli play roulette 10 RED,BLACK  # Split bet (hedge)
apechurch-cli play roulette 10 0          # Zero (36.9x)
apechurch-cli play roulette 10 00         # Double zero (36.9x)

Bet Types:

Multi-bet: Comma-separate to split wager evenly: RED,BLACK

Alias: rl

Baccarat ✔︎

Classic baccarat. Bet on Player, Banker, or Tie.

apechurch-cli play baccarat <amount> <bet>
apechurch-cli play baccarat 50 BANKER           # Single bet
apechurch-cli play baccarat 50 PLAYER           # Single bet
apechurch-cli play baccarat 150 140 BANKER 10 TIE  # Combined: 140 on Banker, 10 on Tie

Combined bets: Specify explicit amounts (must sum to total wager).

Alias: bacc ABI verified: true

Jungle Plinko ✔︎

Drop balls through pegs into multiplier buckets.

apechurch-cli play jungle <amount> <mode> <balls>
apechurch-cli play jungle 10 2 50           # 10 APE, mode 2, 50 balls
apechurch-cli play jungle 50 4 100          # High risk, max balls

Alias: jungle ABI verified: true

Cosmic Plinko ✔︎

Drop biased balls through pegs into asymmetric multiplier buckets.

apechurch-cli play cosmic <amount> <mode> <balls>
apechurch-cli play cosmic 10 1 10           # 10 APE, mode 1, 10 balls
apechurch-cli play cosmic 25 2 30           # High risk, max balls

Alias: cosmic ABI verified: true

Keno ✔︎

Pick numbers, hope they hit.

ABI verified: true

apechurch-cli play keno <amount> [--picks N] [--numbers X,Y,Z]
apechurch-cli play keno 10                     # Random 5 picks
apechurch-cli play keno 10 --picks 10          # 10 random picks
apechurch-cli play keno 10 --picks 5 --numbers 1,7,13,25,40

Max payout: 10/10 hits = 1,000,000x

Alias: k

Speed Keno ✔︎

Fast keno with batched games.

ABI verified: true

apechurch-cli play speed-keno <amount> [--picks N] [--games N]
apechurch-cli play speed-keno 10                # 3 picks, 5 games
apechurch-cli play speed-keno 10 --picks 5 --games 20

Max payout: 5/5 = 2000x

Aliases: speedkeno, skeno, speed

Dino Dough ✔︎, Bubblegum Heist ✔︎, Geez Diggerz ✔︎ & Sushi Showdown ✔︎ (Slots)

Verified multi-spin slot contracts with ordered left-to-right symbol triples.

apechurch-cli play dino-dough <amount> <spins>
apechurch-cli play dino-dough 10 10      # 10 APE, 10 spins
apechurch-cli play bubblegum-heist 10 15 # 10 APE, 15 spins
apechurch-cli play geez-diggerz 10 10    # 10 APE, 10 spins
apechurch-cli play sushi-showdown 10 10  # 10 APE, 10 spins

ABI verified: true Verified runtime: all four games decode (gameId, numSpins, ref, userRandomWord), use a live getVRFFee() read, request numSpins * 3 VRF words, and resolve ordered symbol triples through cumulative reel-stop tables. Slot-family note: Dino Dough and Geez Diggerz are currently exact-match verified on ApeScan; Bubblegum Heist and Sushi Showdown are currently linked Similar Match deployments in the same verified Slots family. Exact RTP: 97.90% for Dino Dough, 97.80% for Bubblegum Heist, 97.69% for Geez Diggerz, and 97.87% for Sushi Showdown from live reel/payout snapshots recorded in the repo. Reel Pirates note: playable but not ABI verified; the observed gameplay tx uses (numSpins, gameId, ref, userRandomWord) and the exact cascade odds are not public in this repo. Current max payout: 333x for Dino Dough, 100x for Bubblegum Heist, 50x for Geez Diggerz, and 500x for Sushi Showdown. Aliases: dinodough, dino, bubblegumheist, bubblegum, heist, geezdiggerz, geez, diggerz, sushishowdown, sushi

Monkey Match ✔︎

Monkeys pop from barrels — form poker hands!

apechurch-cli play monkey-match <amount> [--mode N]
apechurch-cli play monkey-match 10           # Low risk (default)
apechurch-cli play monkey-match 10 --mode 2  # Normal risk / best EV

Max payout: Five of a Kind = 50x

Exact RTP: 97.99% in Low Risk, 98.29% in Normal Risk

Best-play note: there is no redraw or post-deal decision tree; the only strategic choice is mode selection, and mode 2 has the higher exact RTP

Aliases: monkey, mm

Bear-A-Dice ✔︎

Roll dice, avoid unlucky numbers.

ABI verified: true

apechurch-cli play bear-dice <amount> [--difficulty N] [--rolls N]
apechurch-cli play bear-dice 10                    # Easy, 1 roll
apechurch-cli play bear-dice 10 --difficulty 0 --rolls 5

Verified runtime: all five difficulties support 1-5 rolls on-chain; the local CLI no longer applies a fake 3-roll cap to Extreme or Master. Settlement detail: the contract is all-or-nothing. It stops on the first losing sum, zeroes the full payout, and leaves any remaining dice1Results / dice2Results slots at 0, so the CLI filters those tails as "not executed". Exact RTP: ranges from 97.25% (Normal / 5 rolls) to 97.94% (Normal / 1 roll) across the verified on-chain table. Exact win rate: ranges from 83.33% (Easy / 1 roll) down to 0.000053% (Master / 5 rolls). Max payout: up to 1,847,949.193x at Master / 5 rolls Aliases: bear, bd

Loop Mode & Automation

Play continuously with safety controls.

Basic Loop

apechurch-cli play --loop                    # Random games, default settings
apechurch-cli play ape-strong 10 --cover 50 --loop   # Specific game
apechurch-cli play --loop --delay 5          # 5 seconds between games

Safety Controls

# Stop when balance reaches target
apechurch-cli play --loop --target 200

# Stop when balance drops to limit
apechurch-cli play --loop --stop-loss 50

# Stop after N games
apechurch-cli play --loop --max-games 100

# Combine them all
apechurch-cli play ape-strong 10 --cover 50 --loop --target 200 --stop-loss 50 --max-games 100

Loop Output

🔄 Loop mode: ApeStrong (3s delay | Strategy: martingale)
   🎯 Target: 200 APE
   🛑 Stop-loss: 50 APE
   🏁 Max games: 100
──────────────────────────────────────────────────
   📊 martingale: betting 10.00 APE

🎰 ApeStrong (50% chance)
   Betting 10.00 APE

🎉 WON! 10.00 APE → 19.50 APE (+9.50 APE)

⏳ Next game in 3s | 💰 Balance: 109.50 APE (+9.50)

Betting Strategies

Control bet sizing based on win/loss patterns.

Available Strategies

Using Strategies

# Martingale with 10 APE base bet
apechurch-cli play ape-strong 10 --cover 50 --loop --bet-strategy martingale

# Martingale with safety cap
apechurch-cli play roulette 10 RED --loop --bet-strategy martingale --max-bet 100

# Fibonacci on blackjack
apechurch-cli blackjack 5 --auto --loop --bet-strategy fibonacci --max-games 50

# Bankroll fraction sizing (no explicit wager amount)
apechurch-cli play roulette --bet RED --loop --bankroll 500 --bet-strategy bankroll-fraction=0.09 --max-bet 100 --min-bet 5

Strategy Behavior Examples

Martingale (10 APE base):

Win → bet 10 → Win → bet 10 → Lose → bet 20 → Lose → bet 40 → Win → bet 10

Fibonacci (10 APE base):

Lose → bet 10 → Lose → bet 10 → Lose → bet 20 → Lose → bet 30 → Win → bet 10

Safety Options

--max-bet <ape>    # Cap maximum bet (prevents runaway martingale)
--min-bet <ape>    # Floor dynamic bankroll-fraction bets
--stop-loss <ape>  # Stop if balance drops too low

Recommended: Always use --max-bet with progressive strategies.

bankroll-fraction=<n> requires --bankroll/--max-loss or --stop-loss, conflicts with an explicit starting wager, and sizes each new play from the remaining bankroll.

Blackjack ✔︎

Interactive H17 blackjack with optional auto-play. The dealer hits soft 17.

CLI aliases: bj ABI verified: true

Quick Play (Auto)

apechurch-cli blackjack 10 --auto              # Single game, simple auto-play
apechurch-cli blackjack 10 --auto best         # Single game, exact-EV auto-play
apechurch-cli blackjack 10 --auto max          # Exact-EV auto-play with larger solver budget
apechurch-cli blackjack 10 --solver max        # Manual play with worker and simple suggestions
apechurch-cli blackjack 10 --auto best --solver-max-states 100000
apechurch-cli blackjack 10 --auto best --solver-timeout-ms 3000
apechurch-cli blackjack 10 --auto --loop       # Continuous auto-play
apechurch-cli blackjack 10 --auto --loop --max-games 20 --bet-strategy martingale
apechurch-cli bj 10 --auto --loop --max-games 20 # Using alias

Interactive Play

apechurch-cli blackjack 10   # Prompts for each decision

Actions

Auto Strategy

--auto enables automatic play for decision-heavy hands:

• Considers your hand value and dealer context
• Chooses actions such as hit, stand, double, split, insurance, and surrender when available
• Models the live dealer-hits-soft-17 rule surface
• Supports loop mode and betting strategies

--auto best runs the exact-EV search in a worker capped by --solver-max-states <n> and --solver-timeout-ms <ms>. Defaults are 50000 recursive player states and 5000 ms; either guard falls back to simple mode. --auto max uses the same solver with larger defaults: 150000 states and 30000 ms. Raise the state cap for branchy hands only when you can tolerate the extra CPU, and lower the timeout when loop latency matters more than exact completion.

--solver [simple|best|max] enables manual suggestions without executing an action. Bare --solver defaults to best; best and max show both the worker choice and the simple-strategy choice for comparison.

Use apechurch-cli help auto for advanced auto-play modes and pacing controls.

Managing Games

apechurch-cli blackjack resume     # Resume unfinished game
apechurch-cli blackjack status     # Check active games
apechurch-cli blackjack clear      # Clear stuck games

Video Poker

Jacks or Better video poker with interactive and auto-play flows. Ape Church calls this game Gimboz Poker; the CLI command is video-poker and the alias gimboz-poker is supported too.

Quick Play (Auto)

apechurch-cli video-poker 10 --auto              # Single game, simple mode
apechurch-cli video-poker 10 --solver           # Show best-EV hold suggestion
apechurch-cli video-poker 10 --auto --loop       # Continuous
apechurch-cli vp 10 --auto --loop --max-games 50 # Using alias

Bet Amounts

Video poker uses fixed denominations: 10, 25, 50, 100, 250, 400 APE

Hand Rankings

Auto & Solver Behavior

• --auto
  • Enables automatic play for the draw and hold phases
  • Works with loop mode and betting strategies
• --solver
  • Leaves play interactive
  • Shows the best-EV hold suggestion before you choose cards to keep

Use apechurch-cli help auto for advanced auto-play modes and pacing controls.

Display Modes

• --display full
  • Uses the boxed ASCII table renderer for video poker
• --display simple
  • Keeps the compact text renderer

Managing Games

apechurch-cli video-poker resume   # Resume unfinished game
apechurch-cli video-poker status   # Check active games
apechurch-cli video-poker clear    # Clear stuck games
apechurch-cli video-poker payouts  # Show payout table

CLI aliases: vp, gimboz-poker

Commands Reference

Core Commands

Wallet Commands

Profile Commands

Global Flags

JSON Output Schemas

All commands support --json for machine-readable output. Samples below are abridged to the stable fields most agents typically consume.

Status Response

{
  "address": "0x1234...abcd",
  "balance": "52.4500",
  "available_ape": "51.4500",
  "gas_reserve_ape": "1.0000",
  "gp_balance": "150",
  "house_balance": "0.0000",
  "paused": false,
  "persona": "balanced",
  "username": "MY_AGENT",
  "gp_rate": {
    "base_gp_per_ape": 5,
    "current_gp_per_ape": 5,
    "effective_gp_per_ape": 5,
    "source": "default",
    "source_label": "default"
  },
  "can_play": true,
  "unfinished_games": []
}

Play Response

{
  "status": "complete",
  "game": "ape-strong",
  "tx": "0xabc123...",
  "game_url": "https://www.ape.church/games/ape-strong?id=...",
  "wager_ape": "10.000000",
  "config": {
    "range": 50,
    "winChance": "50%",
    "approxPayout": "1.95x"
  },
  "result": {
    "payout_ape": "19.50",
    "won": true,
    "pnl_ape": "9.500000"
  }
}

Wallet Download Response

{
  "history": {
    "version": 2,
    "wallet": "0x1234...abcd",
    "chain_id": 33139,
    "last_synced_block": "35300000",
    "last_download_on": "2026-03-29T12:00:00.000Z",
    "games": [
      {
        "contract": "0x...",
        "game_key": "bear-dice",
        "game_id": "1137230...",
        "play_tx": "0xabc123...",
        "settlement_tx": "0xdef456...",
        "block_number": "35299999",
        "timestamp": 1710000000000,
        "wager_wei": "5000000000000000000",
        "payout_wei": "0",
        "contract_fee_wei": "100000000000000000",
        "gas_fee_wei": "20000000000000000",
        "gp_received_raw": "25",
        "gp_source": "receipt",
        "settled": true,
        "last_sync_on": "2026-03-29T12:00:00.000Z",
        "last_sync_msg": "ok"
      }
    ]
  },
  "stats": {
    "total_saved_games": 14,
    "games": 11,
    "unsynced_games": 3,
    "contract_fees_paid_ape": "0.75528483626624",
    "gas_paid_ape": "0.50494651956676",
    "gross_result_ape": "-500.60836035",
    "net_result_ape": "-500.867599619911120003",
    "win_rate": 63.6,
    "rtp": 11.1,
    "total_wape_received_ape": "35",
    "total_gp_received_display": "175"
  },
  "sync": {
    "wallet": "0x1234...abcd",
    "file_path": "/Users/me/.apechurch-cli/history/0x1234...abcd_history.json",
    "from_block": "35000000",
    "to_block": "35300000",
    "latest_block": "35300000",
    "downloaded_games": 11,
    "new_games": 11,
    "saved_games": 14,
    "missing_transaction_metadata": 0,
    "unsupported_saved_games": 3
  }
}

History Response

{
  "wallet": "0x1234...abcd",
  "history_file": "/Users/me/.apechurch-cli/history/0x1234...abcd_history.json",
  "meta": {
    "version": 2,
    "chain_id": 33139,
    "last_synced_block": "35300000",
    "last_download_on": "2026-03-29T12:00:00.000Z"
  },
  "stats": {
    "total_saved_games": 14,
    "games": 11,
    "unsynced_games": 3,
    "contract_fees_paid_ape": "0.75528483626624",
    "gas_paid_ape": "0.50494651956676",
    "gross_result_ape": "-500.60836035",
    "net_result_ape": "-500.867599619911120003",
    "win_rate": 63.6,
    "rtp": 11.1,
    "current_wape_balance_ape": "32306.9125",
    "total_wape_received_ape": "35",
    "current_gp_balance_display": "188777",
    "total_gp_received_display": "175"
  },
  "game_stats": [
    {
      "game": "Bear-A-Dice",
      "games_played": 6,
      "net_profit_ape": "-32.5200",
      "net_profit_complete": true,
      "wins": 2,
      "pushes": 0,
      "losses": 4,
      "win_rate": 33.33,
      "rtp": 45.8,
      "unfinished_games": 0,
      "unfinished_game_ids": []
    }
  ],
  "breakdown": [
    {
      "game": "Bear-A-Dice",
      "games": 6,
      "contract_fees_paid_ape": "0.4",
      "gas_paid_ape": "0.12",
      "net_result_ape": "-32.52"
    }
  ],
  "sync": null,
  "games": [
    {
      "game": "Bear-A-Dice",
      "gameId": "1137230...",
      "settled": true,
      "wager_ape": "5",
      "payout_ape": "0",
      "contract_fee_ape": "0.1",
      "gas_fee_ape": "0.02"
    }
  ]
}

Error Response

{
  "error": "Insufficient balance. Available: 5.00 APE"
}

Agent Play Patterns

Pattern 1: Simple Loop with Safety

Best for hands-off autonomous play.

apechurch-cli play --loop --target 200 --stop-loss 50 --max-games 500

The agent will:

• Play random games with balanced strategy
• Stop if balance reaches 200 APE (profit target)
• Stop if balance drops to 50 APE (loss limit)
• Stop after 500 games maximum

Pattern 2: Specific Game Grinding

Target a specific game with fixed parameters.

apechurch-cli play ape-strong 10 --cover 50 --loop --target 150 --stop-loss 80

Pattern 3: Martingale Recovery

Progressive betting to recover losses.

apechurch-cli play roulette 5 RED --loop --bet-strategy martingale --max-bet 50 --stop-loss 20

Important: Always set --max-bet with martingale to prevent exponential loss.

Pattern 4: Session-Based Play

Play a fixed number of games per session.

apechurch-cli play --loop --max-games 20

Pattern 5: Blackjack Grinding

Auto-play blackjack in loop mode.

apechurch-cli blackjack 10 --auto --loop --max-games 50 --target 200

Pattern 6: Check Before Play

Always verify state before starting:

# Check if can play
apechurch-cli status --json | jq '.can_play'

# Check balance
apechurch-cli status --json | jq '.available_ape'

# Then play
apechurch-cli play --loop --max-games 10

Pattern 7: Handle Pause/Continue

# Human says "stop gambling"
apechurch-cli pause

# Human says "you can play again"
apechurch-cli continue

# Check state
apechurch-cli status --json | jq '.paused'

Costs & Limits

Transaction Costs

Minimum Bets

Recommended Starting Balance

• Minimum: 20 APE
• Recommended: 50+ APE
• For martingale: 100+ APE

Security

Your selected encrypted wallet is tracked by ~/.apechurch-cli/wallets/current.json, which points to wallets/<address>.json. Encrypted wallet material lives in the address-specific entry; if that entry is a symlink, normal filesystem resolution applies.

⚠️ CRITICAL:

• Never share your private key
• Never paste it into prompts or third-party tools
• The CLI handles all signing locally
• Consider using wallet password periodically to rotate local password protection

Updates

npm update -g @n0ther/apechurch-cli
apechurch-cli --version

Links

• Website: https://ape.church
• Games: https://ape.church/games
• GitHub: https://github.com/ape-church/agent-skills
• npm: https://www.npmjs.com/package/@n0ther/apechurch-cli

Built for apes, agents, and degens. 🦍