Quickstart Guide
================

Get started with OpenClaw Trading in 5 minutes.

Installation
------------

1. Clone the repository:

.. code-block:: bash

   git clone https://github.com/yourusername/openclaw-trading.git
   cd openclaw-trading

2. Create a virtual environment and install dependencies:

.. code-block:: bash

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -e ".[dev]"

3. Verify installation:

.. code-block:: bash

   python -c "import openclaw; print('OpenClaw installed successfully')"

Basic Usage
-----------

Economic Tracker Example
~~~~~~~~~~~~~~~~~~~~~~~~

The economic tracker is the core component for tracking agent finances:

.. code-block:: python

   from openclaw.core.economy import TradingEconomicTracker

   # Create an economic tracker
   tracker = TradingEconomicTracker(
       agent_id="demo_agent",
       initial_capital=1000.0
   )

   # Check survival status
   status = tracker.get_survival_status()
   print(f"Status: {status.value}")

   # Calculate decision costs
   cost = tracker.calculate_decision_cost(
       tokens_input=1000,
       tokens_output=500,
       market_data_calls=2
   )
   print(f"Decision cost: ${cost:.4f}")

   # Simulate a trade
   result = tracker.calculate_trade_cost(
       trade_value=500.0,
       is_win=True,
       win_amount=50.0
   )
   print(f"Trade fee: ${result.fee:.4f}")
   print(f"New balance: ${result.balance:.2f}")

Running the Complete Workflow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use the trading workflow to analyze a stock:

.. code-block:: python

   import asyncio
   from openclaw.workflow.trading_workflow import TradingWorkflow

   async def analyze_stock():
       # Create workflow for AAPL
       workflow = TradingWorkflow(
           symbol="AAPL",
           initial_capital=1000.0,
           enable_parallel=True
       )

       # Run the analysis
       result = await workflow.run()

       # Print results
       print(f"Signal: {result['signal']}")
       print(f"Confidence: {result['confidence']:.2%}")
       print(f"Recommended position: {result['position_size']:.2f}")

   asyncio.run(analyze_stock())

Running Examples
----------------

The project includes several example scripts:

.. code-block:: bash

   # Quickstart example
   python examples/01_quickstart.py

   # Workflow demo
   python examples/02_workflow_demo.py

   # Factor market example
   python examples/03_factor_market.py

   # Learning system example
   python examples/04_learning_system.py

   # Work-trade balance example
   python examples/05_work_trade_balance.py

   # Portfolio risk example
   python examples/06_portfolio_risk.py

Next Steps
----------

* Read the :doc:`architecture` overview
* Explore the :doc:`api` reference
* Learn about :doc:`agents` and their roles
* Understand the :doc:`workflow` system