Metadata-Version: 2.4
Name: candella
Version: 0.0.1
Summary: Candella Copytrade SDK. Push algo signals that fan out to followers' brokers.
Project-URL: Homepage, https://candella.dev/copytrade
Project-URL: Documentation, https://candella.dev/copytrade/developers
Project-URL: Repository, https://github.com/jwlutz/candella-sdk-python
Author: Candella Labs
License: MIT
License-File: LICENSE
Keywords: algo,candella,copytrading,signals,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Requires-Dist: httpx[http2]>=0.27
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Candella SDK (Python)

The official Python SDK for [Candella Copytrade](https://candella.dev/copytrade).
Push your algo's signals into Candella with one signed call, and Candella fans
them out to your followers' brokerage accounts.

Full API reference: https://candella.dev/copytrade/developers

## Install

```bash
pip install candella
```

## Quickstart

```python
from candella import Copytrade

cc = Copytrade(api_key="...", secret="...", strategy_id="my-algo")

cc.start_session()                          # arms live execution when your algo wakes

# right next to your own broker order:
webull.place_order("SPY", "buy", 10)        # your execution, your account
cc.signal("SPY", "buy", 10, price=512.30)   # the copy signal, one line

# options use canonical OCC fields (broker-neutral; Candella re-encodes per follower):
cc.signal_option("SPY", "BTO", 5, price=3.10, expiry="2026-07-18", strike=520, right="C")

cc.end_session()                            # when your algo sleeps
```

Or as a context manager:

```python
with Copytrade(api_key="...", secret="...", strategy_id="my-algo") as cc:
    cc.start_session()
    ...
```

## How it works

- **Identity is server-side.** You never send which lead or account you are; your
  API key resolves that. You only describe the trade.
- **Sessions are the consent gate.** Signals only fan out to real accounts while a
  session is active. A signal sent with no active session is recorded and dropped
  before any order, which is how you integration-test safely.
- **Idempotency.** Pass a stable `signal_id` (your order id or a hash) for safe
  retries. If omitted, a content hash of the signal is used, so an identical
  re-send collapses instead of double-firing.
- **Emit explicit closes.** A `sell` or `stc` signal must accompany every exit, or
  followers hold positions that never close.
- **Latency floor around one second**, dominated by the downstream broker write
  rather than this client. Good for minute-bar and swing strategies, not
  sub-second HFT.

## Credentials

Generate an API key and secret on your
[Algo keys](https://candella.dev/lead/algo-keys) page.

## Development

```bash
git clone https://github.com/jwlutz/candella-sdk-python
cd candella-sdk-python
pip install -e ".[dev]"
pytest
```

## License

MIT
