What is Percolypse?
Percolypse is an autonomous on-chain execution engine. It continuously ingests live blockchain state, extracts actionable signals, and resolves execution — without human intervention.
Built as a fork of percolator-cli, Percolypse advances beyond passive monitoring. Where Percolator collected and surfaced data, Percolypse acts on it. The gap between signal and execution is closed entirely.
The core thesis: in on-chain markets, the edge belongs to whoever acts first. Percolypse removes the human from that decision path.
Live on-chain data across 5+ chains, ingested every block.
Pattern detection across liquidity, order flow, and lifecycle events.
Deterministic execution. No approval queue. No human gate.
Quick Start
Get Percolypse running in autonomous mode in under 5 minutes.
1. Install
2. Configure RPC endpoints
3. Run
Use the --dry-run flag to simulate execution without submitting transactions. Signals are evaluated and actions are computed but never broadcast.
Architecture
Percolypse is structured as a single continuous loop with four stages. There are no queues, no handoffs, and no human checkpoints between ingestion and execution.
Each stage runs in the same process, sharing in-memory state. There is no network hop between signal extraction and execution routing. The full cycle — from block ingestion to transaction broadcast — targets a sub-3-second round trip.
The Loop
The loop is the fundamental unit of Percolypse. It is not a scheduler, not a cron job, not a reactive pipeline. It is a single process that runs continuously and never waits for external input.
The loop binds directly to RPC event streams. Each new block triggers a synchronous pass through all four stages. If no actionable signal is extracted, the loop discards the block and moves to the next. If a signal is extracted and passes risk gating, execution is triggered inline.
The loop is single-threaded per chain. Multi-chain deployments run one loop process per network, coordinated by a shared state store.
Signal Types
Percolypse natively classifies eight signal types. Each type maps to a distinct on-chain pattern and triggers a corresponding class of execution actions.
Execution Engine
The execution engine receives a resolved action from the router and is responsible for constructing, simulating, signing, and broadcasting the transaction.
Transaction lifecycle
Simulation failures are non-fatal. The engine logs the revert reason and continues the loop. A revert rate above RISK_REVERT_THRESHOLD will trigger automatic circuit-breaker activation.
CLI Flags
| Flag | Default | Description |
|---|---|---|
--mode | autonomous | Execution mode. Options: autonomous, monitor, dry-run. |
--network | ethereum | Target network. Use multi for multi-chain mode. |
--threshold | 30 | Minimum signal magnitude (0–100) to trigger pipeline. |
--max-gas | 0.05 | Maximum gas spend per transaction in ETH. |
--risk-level | medium | Risk gating profile. Options: conservative, medium, aggressive. |
--log-level | info | Log verbosity. Options: silent, info, verbose, debug. |
--dry-run | false | Simulate execution without broadcasting transactions. |
--dashboard | false | Launch the web dashboard alongside the runtime. |
Config File
All CLI flags can be set in percolypse.config.json at the project root. File-based config is merged with CLI flags — CLI takes precedence.
Environment Variables
| Variable | Required | Description |
|---|---|---|
PERCOLYPSE_RPC_ETHEREUM | yes* | Ethereum mainnet RPC endpoint. |
PERCOLYPSE_RPC_ARBITRUM | yes* | Arbitrum One RPC endpoint. |
PERCOLYPSE_RPC_BASE | yes* | Base mainnet RPC endpoint. |
PERCOLYPSE_RPC_OPTIMISM | yes* | Optimism mainnet RPC endpoint. |
PERCOLYPSE_RPC_POLYGON | yes* | Polygon PoS RPC endpoint. |
PERCOLYPSE_EXECUTION_KEY | yes | Private key used to sign and broadcast transactions. |
PERCOLYPSE_MODE | no | Overrides --mode CLI flag. |
PERCOLYPSE_WEBHOOK_URL | no | POST target for execution event notifications. |
PERCOLYPSE_EXECUTION_KEY grants full signing authority. Never commit this value. Use a dedicated execution wallet with scoped fund limits.
Liquidity Shifts
The LIQUIDITY_SHIFT signal fires when Percolypse detects meaningful TVL migration across AMM pools or lending protocol vaults.
Percolypse monitors reserve ratios, deposit/withdrawal event patterns, and cross-protocol TVL deltas in real time. A shift is classified when the 5-block rolling delta exceeds the configured magnitude threshold.
Triggerable actions
Orderbook Imbalances
Percolypse tracks depth asymmetries, fill-rate anomalies, and spoofing signatures across DEX and hybrid order-book venues. Signal is extracted at the tick level — before the imbalance resolves in price.
Supported venues
Orderbook signal extraction requires a WebSocket-capable RPC endpoint. HTTP polling will degrade signal quality and latency.
Token Lifecycle Events
Structural token events — launches, vesting unlocks, governance transitions, protocol migrations — shift token dynamics before market consensus forms. Percolypse identifies these events at contract level and executes ahead of the crowd.
| Event | Code | Trigger condition |
|---|---|---|
Token launch | TKN_LAUNCH | New ERC-20 deployment with initial liquidity provision detected. |
Vesting unlock | TKN_VEST | Cliff or linear vesting schedule reaches unlock epoch. |
Governance transition | TKN_GOV | Timelock queue execution or multisig confirmation detected. |
Protocol migration | TKN_MIG | Proxy upgrade or migration contract interaction logged. |
Signal Evaluation
The intelligence layer sits between signal extraction and the execution router. It is not advisory — it is inline. Every candidate signal passes through evaluation before a routing decision is made.
Evaluation produces a confidence score (0–1) and a magnitude score (0–100). Signals below the configured threshold are discarded before reaching the router. Signals above the threshold proceed to risk gating.
Risk Gating
Risk gating is the final checkpoint before execution. It enforces pre-configured boundaries around gas cost, position size, daily exposure, and revert rate.
| Gate | Conservative | Medium | Aggressive |
|---|---|---|---|
Max gas / tx | 0.01 ETH | 0.04 ETH | 0.1 ETH |
Max position | $5,000 | $50,000 | unlimited |
Daily exposure | $20,000 | $200,000 | unlimited |
Revert threshold | 5% | 12% | 25% |
Circuit breaker | 3 reverts | 7 reverts | disabled |
The circuit breaker halts all execution when the revert threshold is exceeded. It resets automatically after 15 minutes. Manual override requires restarting the runtime with --reset-circuit-breaker.
Action Selection
The router maps evaluated signals to execution actions. Routing is deterministic — given the same signal state, the same action is always selected. There is no randomness and no model sampling in the critical path.
Action selection considers: signal kind, magnitude, protocol context, current gas price, and available capital. The result is a fully-specified action object passed to the execution engine.
Webhooks
Set PERCOLYPSE_WEBHOOK_URL to receive POST notifications for all execution events.
Payload shape
Event types
| Event | Fires when |
|---|---|
execution.resolved | Transaction confirmed on-chain (success or revert). |
signal.detected | A signal is extracted and passes magnitude threshold. |
signal.rejected | A signal is dropped by risk gating. |
circuit_breaker.triggered | Revert threshold exceeded. Execution halted. |
loop.started | Runtime initializes and begins the loop. |
loop.paused | Runtime is manually paused or circuit-broken. |
REST API
When started with --dashboard, Percolypse exposes a local REST API on port 4242.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/status | Runtime status, uptime, and active chain connections. |
GET | /api/signals | Recent signal feed (last 200 entries). |
GET | /api/pipelines | Active and recent pipeline states. |
GET | /api/executions | Execution log with tx hashes and outcomes. |
GET | /api/metrics | Aggregated metrics: exec/hr, latency, success rate. |
POST | /api/pause | Pause the execution loop (signals still ingested). |
POST | /api/resume | Resume a paused execution loop. |
POST | /api/reset-circuit-breaker | Manually reset an active circuit breaker. |