Metadata-Version: 2.4
Name: pulse-tax
Version: 0.1.0
Summary: Collect crypto trade history from any exchange and export for tax reporting (Koinly, CoinTracker)
Author: PULSE Protocol
License: Apache-2.0
Project-URL: Homepage, https://github.com/pulseprotocolorg-cyber/pulse-tax
Project-URL: Repository, https://github.com/pulseprotocolorg-cyber/pulse-tax
Keywords: crypto,tax,trading,binance,bybit,kraken,okx,koinly,cointracker,pulse
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build>=0.10; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"

# pulse-tax

**Crypto tax reporting via PULSE Protocol** — collect trade history from Binance, Bybit, Kraken, and OKX in one command. Export to Koinly, CoinTracker, or JSON.

[![PyPI version](https://badge.fury.io/py/pulse-tax.svg)](https://pypi.org/project/pulse-tax/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

---

## The problem

You trade on 3 exchanges. Each one stores your history differently. Koinly, CoinTracker, and every tax accountant want a CSV. You end up logging in to each exchange, hunting for the export button, downloading 3 different CSV formats, and converting them manually.

With pulse-tax: one command.

---

## Installation

```bash
pip install pulse-tax
```

---

## Quick Start

### 1. Create config file

```bash
pulse-tax init
```

This creates `pulse_tax_config.json`. Edit it to add your API keys (read-only keys are sufficient — no trading permissions needed):

```json
{
  "binance": {
    "api_key": "YOUR_BINANCE_API_KEY",
    "api_secret": "YOUR_BINANCE_API_SECRET"
  },
  "bybit": {
    "api_key": "YOUR_BYBIT_API_KEY",
    "api_secret": "YOUR_BYBIT_API_SECRET"
  },
  "kraken": {
    "api_key": "YOUR_KRAKEN_API_KEY",
    "api_secret": "YOUR_KRAKEN_API_SECRET"
  },
  "okx": {
    "api_key": "YOUR_OKX_API_KEY",
    "api_secret": "YOUR_OKX_API_SECRET",
    "passphrase": "YOUR_OKX_PASSPHRASE"
  }
}
```

Remove exchanges you don't use.

### 2. Export

```bash
# Export 2026 trades to Koinly CSV
pulse-tax export --year 2026 --format koinly

# Export to CoinTracker
pulse-tax export --year 2026 --format cointracker

# Export to JSON (backup / custom processing)
pulse-tax export --year 2026 --format json
```

Output files are created in the current directory:
- `koinly_2026.csv` — import directly at koinly.com
- `cointracker_2026.csv` — import directly at cointracker.io
- `pulse_tax_2026.json` — full structured data

---

## Python API

```python
from pulse_tax import TaxCollector, KoinlyExporter
from pulse_tax.collectors import BinanceCollector, BybitCollector

# Configure exchanges
collector = TaxCollector()
collector.add_exchange(BinanceCollector(api_key="...", api_secret="..."))
collector.add_exchange(BybitCollector(api_key="...", api_secret="..."))

# Collect
report = collector.collect(year=2026, verbose=True)
print(f"{report.total_trades} trades from {report.exchanges}")

# Export
csv = KoinlyExporter().export(report.trades, report.transfers)
with open("koinly_2026.csv", "w") as f:
    f.write(csv)
```

---

## Supported Exchanges

| Exchange | Trades | Deposits/Withdrawals |
|---|---|---|
| Binance | Yes | Yes |
| Bybit | Yes (spot + perps) | Yes |
| Kraken | Yes | Yes |
| OKX | Yes (spot + futures) | Yes |

---

## Supported Export Formats

| Format | Service | How to import |
|---|---|---|
| `koinly` | Koinly | Imports > Add import > Universal CSV |
| `cointracker` | CoinTracker | Portfolio > Add transaction > CSV |
| `json` | Any | Custom processing |

---

## Why PULSE?

pulse-tax is part of the [PULSE Protocol](https://pypi.org/project/pulse-protocol/) ecosystem. PULSE provides a universal semantic interface for AI-to-AI and agent-to-service communication.

The same exchange adapters that pulse-tax uses for collecting history are also used by:
- [pulse-binance](https://pypi.org/project/pulse-binance/) for live trading
- [pulse-bybit](https://pypi.org/project/pulse-bybit/) for Bybit integration
- AI trading agents built with [pulse-anthropic](https://pypi.org/project/pulse-anthropic/) (Claude) or [pulse-openai](https://pypi.org/project/pulse-openai/) (GPT)

---

## Security Note

pulse-tax only needs **read-only** API keys. It never places orders, never withdraws funds. Create a separate read-only key on each exchange specifically for tax reporting.

---

## License

Apache 2.0 — free forever, open source.
