Summary: Hardened, fully AI agents playable Ape Church fork for GitHub and npm readers. Highlights encrypted-only wallet handling, stronger auto gameplay, expanded game support, on-chain history reporting, and operator-focused CLI tooling.
Encrypted-only, fully AI agents playable gambling CLI for Ape Church on ApeChain.
Private keys stay local, are stored on disk only in encrypted form in this hardened build, and are never sent by the CLI to Ape Church services in plaintext. The fork also expands game coverage, improves auto gameplay for stateful games, and adds deeper on-chain reporting and machine-friendly flows for AI agents and terminal-first users.
- 22 implemented games:
ApeStrong โ๏ธ,Roulette โ๏ธ,Baccarat โ๏ธ,Jungle Plinko โ๏ธ,Cosmic Plinko โ๏ธ,Keno โ๏ธ,Speed Keno โ๏ธ,Dino Dough โ๏ธ,Bubblegum Heist โ๏ธ,Geez Diggerz โ๏ธ,Gimboz Smash โ๏ธ,Glyde or Crash โ๏ธ,Reel Pirates,Cash Dash โ๏ธ,Hi-Lo Nebula โ๏ธ,Sushi Showdown โ๏ธ,Monkey Match โ๏ธ,Bear-A-Dice โ๏ธ,Blocks โ๏ธ,Primes โ๏ธ,Blackjack โ๏ธ, andVideo Poker โ๏ธ / Gimboz Poker. Of these, 21 are ABI-verified;Reel Piratesis playable but not ABI-verified. - Fully AI agents playable: browserless CLI flows, local signing, JSON output, formal command grammar, and self-describing game metadata make it straightforward for coding agents and automations to use directly
- Improved auto gameplay:
Blackjack โ๏ธ,Cash Dash โ๏ธ,Hi-Lo Nebula โ๏ธ, andVideo Poker โ๏ธ / Gimboz Pokerinclude interactive flows, better auto-play, solver-backed decisions, and loop-friendly automation controls - Fully on-chain settlement: every wager is placed on ApeChain and resolved by the live contracts with their on-chain RNG integrations, including Chainlink VRF and Pyth V2 where applicable
- Encrypted-only local signer: private keys stay encrypted on disk, plaintext wallet export is disabled, and signing happens locally without transmitting the key to Ape Church services
- AI-agent-first operator UX: fully AI agents playable command surface with structured outputs, local history caches, and no browser dependency
- Better stateful automation: stronger blackjack, cash-dash, hi-lo-nebula, and video-poker auto gameplay, side-bet support, unfinished-game recovery, and EV / Monte Carlo helpers for loop planning
- Expanded Ape Church coverage: explicit support for both Jungle Plinko and Cosmic Plinko instead of a single generic Plinko entry, plus supported
Blocks โ๏ธ,Primes โ๏ธ, andGlyde or Crash โ๏ธgameplay and a broader maintained game registry - ABI-verified game metadata: verified contracts are marked with
โ๏ธin CLI output, help, JSON payloads, and docs; ApeStrong โ๏ธ, Roulette โ๏ธ, Baccarat โ๏ธ, Jungle Plinko โ๏ธ, Cosmic Plinko โ๏ธ, Keno โ๏ธ, Speed Keno โ๏ธ, Dino Dough โ๏ธ, Bubblegum Heist โ๏ธ, Geez Diggerz โ๏ธ, Gimboz Smash โ๏ธ, Glyde or Crash โ๏ธ, Cash Dash โ๏ธ, Hi-Lo Nebula โ๏ธ, Sushi Showdown โ๏ธ, Monkey Match โ๏ธ, Bear-A-Dice โ๏ธ, Blocks โ๏ธ, Primes โ๏ธ, Blackjack โ๏ธ, and Video Poker โ๏ธ use verified on-chain contract data - RTP and payout modeling overhaul: expected RTP, reported RTP, current RTP, and max-payout references across the game catalog, with exact/formula/statistical provenance markers where available
- Exact Plinko modeling: Jungle and Cosmic Plinko mode RTP and top payouts are derived from the live on-chain bucket tables, and Plinko stats are grouped by risk level rather than by ball count
- Per-wallet history cache:
wallet downloadreconstructs supported on-chain history into a local cache, with incremental backfills and offlinehistoryreads across 26 tracked public game contracts - Richer reporting:
Recent Games, compactGame Status, and fullGame Statsviews show net profit, win rate, RTP, unfinished local games, and per-game breakdowns - Better automation tooling: loop mode supports
take-profit,retrace,stop-loss,max-games, machine-readable JSON output, and strategy-driven game/config selection - Stateful UX improvements: unfinished-game recovery, blackjack side bets, solver-backed auto decisions, and EV / Monte Carlo helpers for loop planning
- Documentation overhaul: formal BNF argument grammar in CLI help, a bundled games reference, clearer examples, and explicit coverage / limitations for on-chain reporting
# 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
# Fund wallet with APE on ApeChain
# Bridge: https://relay.link/bridge/apechain
# Check status
apechurch-cli status
# Download on-chain history for the local wallet
apechurch-cli wallet download
# Read cached history and stats
apechurch-cli history --stats
# Play one random game/config automatically
apechurch-cli play --auto
# Play continuously
apechurch-cli play --loopIf ~/.apechurch-cli/wallet.json already exists, apechurch-cli install reuses the encrypted wallet and does not ask for the private key again.
APECHURCH_CLI_PK: optional fallback for non-interactive fresh install/reinstallAPECHURCH_CLI_PASS: required for non-interactive install/signing; optional otherwiseAPECHURCH_CLI_PROFILE_URL: optional override for the username/profile API endpoint
- Full CLI command, option, alias, and shared BNF reference: docs/COMMAND_REFERENCE.md
- Per-game syntax and game-specific grammar: docs/GAMES_REFERENCE.md
- The House mechanics, current
House Yieldsemantics, and planning-grade APY model: docs/HOUSE_REFERENCE.md
profile defaults to show. Mutating flags require profile set. profile set --username <name> registers or changes the username via the same SIWE flow as register.
# Show the selected wallet profile
apechurch-cli profile
apechurch-cli profile show
# Register or change the username from profile
apechurch-cli profile set --username smith
# Set persona and card rendering
apechurch-cli profile set --persona aggressive --card-display simple
# Set or clear the wallet-specific current GP/APE rate
apechurch-cli profile set --gp-ape 7.5
apechurch-cli profile set --no-gp-apeProfile flags:
--username <name>: register or change the username for the selected wallet--persona <name>:conservative | balanced | aggressive | degen--card-display <mode>:full | simple | json--referral <address>: local-only0x-prefixed wallet address used on future game transactions--gp-ape <points>: positive decimal GP/APE override for the selected wallet--no-gp-ape: clear the wallet-specific GP/APE override and fall back to the base default
--referral does not change the SIWE username registration payload and does not retroactively affect old plays.
Use wallet download to reconstruct supported gaming history from ApeChain into a per-wallet local file, then read that cache with history without rebuilding the chain view every time.
The CLI currently implements 22 playable games, 21 of which are ABI-verified. Wallet history tracks 26 distinct Ape Church games: the 22 implemented games plus history-only support for Blizzard Blitz, Gimboz of the Galaxy, Rico's Revenge, and Cult Quest. Locally started Cash Dash runs are tracked through the same unfinished-game and local-history flow as the other stateful commands.
If [address] is omitted, both commands use the local wallet address.
# Download history for the local wallet address
apechurch-cli wallet download
# List wallets with local cached history files
apechurch-cli history --list
# Download history for any wallet
apechurch-cli wallet download 0x1234...abcd
# Narrow the sync to 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
# Read saved history plus history stats
apechurch-cli history 0x1234...abcd
# Show more than the default 10 recent cached games
apechurch-cli history 0x1234...abcd --limit 25
# Show every cached game
apechurch-cli history 0x1234...abcd --all
# Show only history stats
apechurch-cli history 0x1234...abcd --stats
# Show history stats split by game
apechurch-cli history 0x1234...abcd --breakdown
# Show weekly wAPE wagered totals
apechurch-cli history 0x1234...abcd --leaderboard
# Append the cached wallet leaderboard to the history report
apechurch-cli history 0x1234...abcd --scoreboard
# Include game IDs in the terminal leaderboard tables
apechurch-cli history 0x1234...abcd --scoreboard --ids
# Include game URLs in the terminal leaderboard tables
apechurch-cli history 0x1234...abcd --scoreboard --url
# Read the cached leaderboard on its own
apechurch-cli scoreboard 0x1234...abcd
# Show game IDs in the standalone terminal leaderboard
apechurch-cli scoreboard 0x1234...abcd --ids
# Show URLs in the standalone terminal leaderboard
apechurch-cli scoreboard 0x1234...abcd --url
# Refresh from chain before showing
apechurch-cli history 0x1234...abcd --refresh
# Merge a full-range refresh before showing
apechurch-cli history 0x1234...abcd --refresh --from-block 0
# Machine-readable output
apechurch-cli history 0x1234...abcd --jsonSync and cache behavior:
wallet downloadis incremental by default. Without--from-block, it resumes fromlast_synced_block + 1.- Use
wallet download --from-block 0to rebuild the local history file from scratch, or pass an explicit historical range to fill older blocks. - Explicit backfills and
history --refreshare merged into the local file and deduplicated bycontract + game_id. history --refreshruns the same on-chain sync path before reading the local file, but it does not clear cached records first.historyshows๐ Recent Gamesplus๐ History Statsby default.--statssuppresses the game list, while--breakdownappends the same stats split by game.history --leaderboardshows global and weekly wAPE wagered, grouped by UTC ISO week, and listed newest first. Terminal amounts are rounded to 2 decimals; JSON keeps exact cached values.history --scoreboardappends two cached Top 20 tables:Highest MultipliersandBiggest Payouts.- Scoreboard terminal tables hide the reference column by default; pass
--urlto showgame_urlor--idsto showgame_id. If both are passed, the last option wins. JSON output keeps both fields. - Standard
historyoutput also includes a compact๐ฎ Game Statussection with per-gameplayed,net,win rate,RTP, and localunfinishedcounts when available.
Text output includes:
๐ฐ Games: economically synced games included in totals๐ธ Contract fees paid: contract-side fees actually paid by the walletโฝ๏ธ Gas paid: network gas actually paid by the walletNet result:payout - wager - contract fees - gasโ๏ธ Win rate: wins divided by economically synced games๐ฒ RTP:total payout / total wagered๐๏ธ APE Wagered (wAPE): current on-chain balance / total APE wagered by synced games๐งฎ Gimbo Points (GP): current on-chain balance / total GP received from synced games; every10,000 GPequals1 Level
wallet download options:
| Option | Description |
|---|---|
--list |
List locally available wallet addresses |
--from-block <n> |
Start block for the sync; wallet download --from-block 0 rebuilds the history file |
--to-block <n> |
End block for the sync (default: latest block) |
--chunk-size <n> |
Block span per log query (default: 50000) |
--json |
Emit the machine-readable download report |
history options:
| Option | Description |
|---|---|
--list |
Show wallet addresses with local cached history files |
--limit <n> |
Number of recent cached games to show (default: 10) |
--all |
Show all cached games instead of the recent slice |
--ids |
Show game IDs in history lines and scoreboard tables |
--stats |
Show only history stats |
--breakdown |
Append the same stats split by game |
--leaderboard |
Show weekly wAPE wagered totals grouped from Monday 00:00 UTC |
--scoreboard |
Append the cached wallet leaderboard derived from history |
--url |
Show game URLs in terminal scoreboard tables |
--refresh |
Merge an on-chain sync before rendering |
--from-block <n> |
Start block for --refresh |
--to-block <n> |
End block for --refresh (default: latest block) |
--chunk-size <n> |
Block span per log query for --refresh |
--json |
Emit the machine-readable cached report |
games options:
| Option | Description |
|---|---|
--stats |
Append the full Game Stats catalog after the game summary, using local history when available |
--json |
Emit the game registry as JSON |
Coverage and 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 canonical
wager_wei. - The downloader tracks 26 distinct public games. Stateless implemented and history-only contracts are reconstructed from settlement logs, fallback play logs, and
getEssentialGameInfo; locally-known stateful entries are refreshed through their game-specific getters. BlackjackandVideo Poker(Gimboz Pokerin Ape Church naming) cannot yet be generically enumerated from raw RPC, so locally-known entries remain minimal until a reliable fetch path is implemented.- Sponsored transactions contribute
0contract fees and0gas for the analyzed wallet.
| Game | Command | Aliases | Description |
|---|---|---|---|
| ApeStrong โ๏ธ | play ape-strong 10 50 |
apestrong, strong |
Pick-your-odds dice |
| Roulette โ๏ธ | play roulette 10 RED |
- | American roulette |
| Baccarat โ๏ธ | play baccarat 10 BANKER |
- | Classic baccarat |
| Jungle Plinko โ๏ธ | play jungle-plinko 10 2 50 |
jungleplinko, jungle |
Drop balls for multipliers |
| Cosmic Plinko โ๏ธ | play cosmic-plinko 10 1 10 |
cosmic |
Asymmetric plinko with higher top-end payouts |
| Keno โ๏ธ | play keno 10 |
- | Pick numbers 1-40 |
| Speed Keno โ๏ธ | play speed-keno 10 |
speedkeno, skeno |
Fast batched keno |
| Dino Dough โ๏ธ | play dino-dough 10 10 |
dinodough, dino |
Slot machine |
| Bubblegum Heist โ๏ธ | play bubblegum-heist 10 10 |
bubblegumheist, bubblegum, heist |
Slot machine |
| Cash Dash โ๏ธ | cash-dash 10 --auto |
cashdash, dash |
Stateful death-tile ladder game with cash-out |
| Geez Diggerz โ๏ธ | play geez-diggerz 10 10 |
geezdiggerz, geez |
Slot machine |
| Gimboz Smash โ๏ธ | play gimboz-smash 10 1-50 or play gimboz-smash 10 --out-range 45-50 |
gimbozsmash, smash |
One-or-two interval target game on a 1-100 board |
| Glyde or Crash โ๏ธ | play glyde-or-crash 10 2x |
glyde, glyde-crash, glydecrash, speed-crash, speedcrash, crash |
Target a crash multiplier |
| Reel Pirates | play reel-pirates 20 |
reelpirates, pirates, reel |
Match-anywhere cascade slot |
| Hi-Lo Nebula โ๏ธ | hi-lo-nebula 10 --auto best |
hilonebula, hilo |
Stateful higher/lower/same card streak game with cash-out |
| Sushi Showdown โ๏ธ | play sushi-showdown 10 10 |
sushishowdown, sushi |
Slot machine |
| Monkey Match โ๏ธ | play monkey-match 10 |
monkeymatch, monkey |
Poker hands from barrels |
| Bear-A-Dice โ๏ธ | play bear-dice 10 |
bear, dice |
Avoid unlucky numbers |
| Blocks โ๏ธ | play blocks 10 1 5 |
- | 3x3 cluster board with consecutive all-or-nothing rolls |
| Primes โ๏ธ | play primes 10 0 20 |
- | Prime-or-zero number draws with batched runs |
| Blackjack โ๏ธ | blackjack 25 --side 1 --auto |
bj |
Card game with auto-play and optional player side bet |
| Video Poker โ๏ธ / Gimboz Poker | video-poker 10 --auto |
vp |
Jacks or Better with auto-play and solver tools |
The CLI help now exposes formal argument grammar in apechurch-cli play --help, apechurch-cli bet --help, and apechurch-cli game <name>.
<points> ::= <number> ; decimal GP per APE rate; value > 0
<keno-numbers> ::= "random" | <keno-number> ( "," <keno-number> )*
<keno-number> ::= <integer> ; 1 <= value <= 40
<speed-keno-numbers> ::= "random" | <speed-keno-number> ( "," <speed-keno-number> )*
<speed-keno-number> ::= <integer> ; 1 <= value <= 20
<roulette-bets> ::= <roulette-bet> ( "," <roulette-bet> )*
<baccarat-bet> ::= "PLAYER" | "BANKER" | "TIE" | <combo-baccarat-bet>
<combo-baccarat-bet> ::= <ape> <baccarat-side> <ape> "TIE"
<baccarat-side> ::= "PLAYER" | "BANKER"
--numbers must be passed as one CLI token, for example --numbers 1,7,13,25,40.
The full command surface lives in docs/COMMAND_REFERENCE.md. The full per-game grammar lives in docs/GAMES_REFERENCE.md.
Play continuously with safety controls:
# Basic loop
apechurch-cli play --loop
# With safety limits
apechurch-cli play --loop --take-profit 200 --stop-loss 50 --max-games 100
# Stop on session P&L thresholds
apechurch-cli play roulette 10 RED --loop --min-profit 25
apechurch-cli play roulette 10 RED --loop --max-loss 20
# Stop after any big hit
apechurch-cli play ape-strong 10 50 --loop --target-x 3.9
apechurch-cli play ape-strong 10 50 --loop --target-profit 39
apechurch-cli play roulette 10 RED --loop --retrace 10
# Stop after recovering a drawdown or giving back a run-up
apechurch-cli play roulette 10 RED --loop --recover-loss 25
apechurch-cli play roulette 10 RED --loop --giveback-profit 40
# Specific game
apechurch-cli play ape-strong 10 50 --loop --take-profit 150| Option | Description |
|---|---|
--take-profit <ape> |
Stop when balance reaches target |
--min-profit <ape> |
Stop when session P&L reaches the target profit |
--target-x <x> |
Stop when one game pays at least this multiplier |
--target-profit <ape> |
Stop when one game pays at least this payout |
--retrace <ape> |
Stop when one game loses at least this amount |
--recover-loss <ape> |
Stop when session P&L gets back to break-even/profit after a drawdown of at least this size |
--giveback-profit <ape> |
Stop when session P&L falls back to break-even/loss after a run-up of at least this size |
--stop-loss <ape> |
Stop when balance drops to limit |
--max-loss <ape> |
Stop when session P&L reaches the loss limit |
--max-games <n> |
Stop after N games |
--delay <sec> |
Seconds between games (default: 3) |
--gp-ape <points> |
Override the loop points conversion for this run |
Loop summaries now assume a base rate of 5 GP/APE. Use --gp-ape <points> for a one-off override, or persist a wallet-specific current rate with apechurch-cli profile set --gp-ape <points>.
Local loop summaries and local-only GP estimates use a base rate of 5 GP/APE.
- One-off override for a single run:
--gp-ape <points>onbet,play,blackjack,cash-dash,hi-lo-nebula, andvideo-poker - Wallet-specific current override:
apechurch-cli profile set --gp-ape <points> - Clear the wallet-specific current override:
apechurch-cli profile set --no-gp-ape
When on-chain GP is available for a settled game, reporting uses that on-chain value instead of any local estimate.
# Martingale: double on loss, reset on win
apechurch-cli play roulette 10 RED --loop --bet-strategy martingale --max-bet 100
# Fibonacci: sequence on losses
apechurch-cli play --loop --bet-strategy fibonacci| Strategy | Behavior |
|---|---|
flat |
Same bet every time (default) |
martingale |
Double on loss, reset on win |
reverse-martingale |
Double on win, reset on loss |
fibonacci |
Fibonacci sequence on losses |
dalembert |
+1 unit on loss, -1 on win |
video-poker is the CLI command for Ape Church's Gimboz Poker.
Interactive multi-transaction games with auto-play support:
# Auto-play
apechurch-cli blackjack 10 --auto --loop
apechurch-cli cash-dash 10 --auto --cashout-after 1
apechurch-cli blackjack 25 --side 1 --auto
apechurch-cli cash-dash 10 --solver # Interactive tile suggestion (best EV)
apechurch-cli video-poker 10 --auto --loop
apechurch-cli video-poker 10 --solver # Interactive hold suggestion (best EV)
# Interactive mode
apechurch-cli blackjack 10
apechurch-cli cash-dash 10 # Prompts for the opening tile--autoenables automatic play for stateful gamesblackjack --side <ape>adds a player side bet to the opening deal without changing the in-hand EV solvercash-dashshows the opening row and prompts for the first tile when--tileis omitted in manual modecash-dash --cashout-after <rows>lets auto-play target deeper rows before cashing outvideo-poker --solvershows the same best-EV hold suggestion in interactive modevideo-poker --display fullnow uses the boxed ASCII table layout;simplekeeps the compact text layoutblackjackandvideo-pokeruse--delay 5by default in loop mode- where loop game estimates are supported, startup prints a pre-loop estimate before asking
Proceed? (Y/n); games with a Monte Carlo model show the typical run plus lucky-day / bad-run bounds, while the others keep the EV-based estimate - use
apechurch-cli help autofor advanced stateful auto-play modes and pacing controls
apechurch-cli play --auto # Auto-select random game/config
apechurch-cli play [game] [amount] [config...] # Play a specific simple game
apechurch-cli cash-dash <amount> [--auto [simple|best]] # Cash Dash (aliases: cashdash, dash)
apechurch-cli hi-lo-nebula <amount> [--auto [simple|best]] # Hi-Lo Nebula (aliases: hilonebula, hilo)
apechurch-cli blackjack <amount> [--auto] [--side <ape>] # Blackjack (alias: bj)
apechurch-cli video-poker <amount> [--auto] # Video Poker / Gimboz Poker (alias: vp)
apechurch-cli status # Check balance
apechurch-cli wallet --list # List locally available wallet addresses
apechurch-cli wallet download [address] # Download supported on-chain history into local cache
apechurch-cli games # List all games
apechurch-cli game <name> # Game details
apechurch-cli pause # Stop autonomous play
apechurch-cli continue # Continue play
apechurch-cli history --list # List wallets with local cached history files
apechurch-cli history [address] [--stats] [--breakdown] [--leaderboard] [--scoreboard] [--ids] [--url] [--refresh] # Read cached history and reporting
apechurch-cli scoreboard [address] [--ids] [--url] # Read cached leaderboard tables
apechurch-cli commands # Full referenceUse apechurch-cli games or apechurch-cli game <name> to see the current alias set in the terminal.
All commands support --json for machine-readable output:
apechurch-cli status --json
apechurch-cli play --auto --json
apechurch-cli play --loop --json
apechurch-cli wallet download 0x1234...abcd --json
apechurch-cli history 0x1234...abcd --breakdown --json
apechurch-cli scoreboard 0x1234...abcd --jsonSee SKILL.md for complete agent documentation.
Maintainer and deep-dive docs live under docs/README.md in the repo.
- Node.js >= 18
- APE on ApeChain (gas + wagers)
- Website: https://ape.church
- Games: https://ape.church/games
- Bridge APE: https://relay.link/bridge/apechain
- GitHub: https://github.com/ape-church/agent-skills
ISC