Quickstart

Get up and running with Pulse in under 2 minutes.

This guide walks you through installing the SDK, authenticating, and making your first data request. All new accounts start on the Free tier, which gives you access to a set of pre-run cached simulations to explore straight away.

1. Create an account

Go to pulse.simudyne.com and create an account using email, GitHub, or Google.

2. Get an API key

After signing in, go to your Dashboard and click Create new key. Copy the key as it is only shown once.

Store your API key securely. You can create multiple keys and label them for different use cases (e.g. "research", "production").

3. Install the SDK

With pip:

bash
pip install git+https://github.com/simudyne/pulse-api.git

Or with uv:

bash
uv pip install git+https://github.com/simudyne/pulse-api.git

Requires Python 3.10 or later.

4. Download sample data

Before exploring the full catalogue, grab a sample — 5 Monte Carlo runs of a 700.HK baseline simulation to get a feel for the data. No configuration needed beyond your API key.

python
from simudyne import PulseABM

client = PulseABM(api_key="pk_live_...")

# Download 5 MC runs of 700.HK as a ZIP
client.simulation.get_sample_data()
# writes simulation_sample.zip to current directory

You can also download the sample as a ZIP from the homepage without writing any code. See Output format for a full breakdown of the L2 and Ticks DataFrames inside.

5. Browse all cached simulations

Use list_cached() to see everything available on your tier.

python
# List all available cached simulations
cached = client.simulation.list_cached()
for sim in cached["simulations"]:
    print(f"{sim['symbol']} {sim['date']} {sim['scenario']}: {sim['n_runs']} runs")
Output
700.HK 2025-09-02 normal: 25 runs
700.HK 2025-09-02 flash_crash: 25 runs
9999.HK 2025-09-02 normal: 5 runs

6. Download simulation data

python
# Pick a cached simulation
cached = client.simulation.list_cached(symbol="700.HK", scenario="normal")
sim_id = cached["simulations"][0]["example_sim_id"]

# Download as a Polars DataFrame
df = client.simulation.get_sim_data(sim_id)
print(df.head())

# Download mid-price by minute
mid_df = client.simulation.get_sim_data(sim_id, "mid_price_by_min.parquet")
Output
shape: (5, 68)
┌──────────┬─────────────────────────┬─────────────┬───┬──────────────┬──────┬──────┐
│ sequence ┆ timestamp               ┆ bid_price_1 ┆ … ┆ message_type ┆ side ┆ size │
│ ---      ┆ ---                     ┆ ---         ┆   ┆ ---          ┆ ---  ┆ ---  │
│ i64      ┆ datetime[ms]            ┆ f64         ┆   ┆ i64          ┆ i64  ┆ i64  │
╞══════════╪═════════════════════════╪═════════════╪═══╪══════════════╪══════╪══════╡
│ 0        ┆ 2025-09-02 09:30:00.001 ┆ 315.2       ┆ … ┆ 1            ┆ 1    ┆ 500  │
│ 1        ┆ 2025-09-02 09:30:00.014 ┆ 315.2       ┆ … ┆ 2            ┆ -1   ┆ 200  │
│ …        ┆ …                       ┆ …           ┆ … ┆ …            ┆ …    ┆ …    │
└──────────┴─────────────────────────┴─────────────┴───┴──────────────┴──────┴──────┘

Example output — exact rows and the 68-column layout depend on the run.

On the Pro tier, use client.simulation.run() to submit custom simulation jobs with your own symbols, scenarios, and execution algorithms. An instrument is identified by four fields: provider, exchange, symbol, and cal_date. See Simulations for details.

Next steps

Installation→