zeroalpha 0.7.2

Project Zero DeFi Simulator

WARNING: original source file is docs/getting_started.rst

Getting Started

ProjectZero Quantitative System SDK is a purpose-built SDK for decentralized finance. It enables a unified lifecycle that supports research, protocol-level simulation, backtesting, optimization, and live monitoring. Designed to empower quants, researchers, and developers, ZeroAlpha makes it easy to experiment, iterate, and bring DeFi protocols and strategies from concept to execution.

This repository is the public endpoint for the zeroalpha package, available on PyPI, providing all the tools needed to build, test, and run strategies within a single, integrated environment.

For additional examples and tests, please visit the companion repository at https://github.com/projectzero-io/zeroalpha-extension/.

Prerequisites

Before installing the ZeroAlpha, ensure you have:

• Python 3.12 or 3.13
• pip package manager

Installation

Install the ZeroAlpha using pip:

pip install zeroalpha

Note: This installation will also include several other packages provided by ProjectZero.

Environment Configuration

Get your API key from

https://register.projectzero.io

The following command creates a projectzero-quantlib.toml file with the required proxy configuration for accessing ProjectZero gRPC API. Make sure to replace YOUR_API_KEY.

(
echo '[grpc]'
echo 'url = "https://ns31798707.ip-198-244-253.eu:50051"'
echo 'api-key = "<YOUR_API_KEY>"'
echo '[eth-rpc]'
echo 'url = "https://ns31798707.ip-198-244-253.eu/reth"' # <- or your own JSON RPC access to an Ethereum archive node
echo 'api-key = "<YOUR_API_KEY>"'
) > projectzero-quantlib.toml

Then, export it as an environment variable:

export QUANTLIB_CONFIG=/path/to/projectzero-quantlib.toml

Verify Installation

First, verify that the installation was successful:

import zeroalpha
print(f"ZeroAlpha version: {zeroalpha.__version__}")

Quick Start

Basic Use Case

Here’s a simple example to get you started with the ZeroAlpha:

from zeroalpha import Simulation
from zeroalpha.protocols import UniswapV3Factory
import json

# Initialize simulation with protocols and configuration
uniswap_v3 = UniswapV3Factory() # factory for all UniswapV3 instances
sim = Simulation([uniswap_v3], "./examples/configs/basic_config.yml")

# Run the simulation
all_observables = sim.run()

# Access results
print(f"Simulation completed with {len(all_observables)} observables")

Tips:

• By default, the execution is quiet, and you can make it verbose to watch the execution flow.
• Data queries to feed the simulation can be expensive; consider setting the quantlib cache to make it faster.

for both, see Useful environment variables section below.

Getting Involved

• Documentation: https://projectzero-io.github.io/zeroalpha/

  • Explore Core Concepts - Learn about the fundamental architecture and components
  • Study How to Build - Dive deeper into configuration and practical examples
  • Check the API Reference - Detailed documentation of all classes and methods

• GitHub Issues: https://github.com/projectzero-io/zeroalpha/issues
• Contact: Contact us to [e-mail] for joining us on private Telegram channel
• Examples: Explore practical implementations in the examples directory. JSON schemas are provided to ensure proper format and validation.

Now that you have the ZeroAlpha installed and understand the basics, you might want to:

Known issues and roadmap

Coming soon:

• API stabilisation
• API examples with arbitrageur or other multi-actor scenarios

And later:

• Compound V2 support, more protocols will follow

• Open Rust API to extend core interfaces directly in Rust

• API for external data provider

  (Currently, the ZeroAlpha uses quantlib and ProjectZero gRPC server for data handling.)

• EVM based any protocol executions

Known issues:

• Support of Python 3.11
• Support of Linux arm64

Useful environment variables

Variable name	Example	Description
QUANTLIB_CONFIG	projectzero-quantlib.toml	Path to a config file in TOML format
QUANTLIB_CACHE	./your_dir/.cache	Cache directory to optimize quantlib calls (be sure to create the directory)
RUST_LOG	debug	Configure the log level of core engine

For more environment variables, see Environment variables