Metadata-Version: 2.4
Name: agenttax
Version: 0.1.0
Summary: Python SDK for the AgentTax API — sales tax, use tax, and capital gains for AI agents
License: MIT
Project-URL: Homepage, https://agenttax.io
Project-URL: Documentation, https://agenttax.io/api-docs
Project-URL: Repository, https://github.com/agenttax/agenttax
Project-URL: Bug Tracker, https://github.com/agenttax/agenttax/issues
Keywords: tax,sales-tax,ai-agent,agentic,x402,capital-gains,compliance,fintech
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: requests-mock>=1.11; extra == "dev"

# AgentTax Python SDK

Sales tax, use tax, and capital gains for AI agents. Full docs at [agenttax.io/api-docs](https://agenttax.io/api-docs).

## Install

```bash
pip install agenttax
```

## Quickstart

```python
from agenttax import AgentTaxClient

client = AgentTaxClient(api_key="atx_live_...")

# Calculate sales tax
result = client.calculate(
    role="seller",
    amount=1000.00,
    buyer_state="TX",
    transaction_type="saas",
    counterparty_id="agent_buyer_001",
    is_b2b=True,
)

print(result["taxable"])     # True
print(result["total_tax"])   # 50.0 (5% TX — 80% rule applied)
print(result["confidence"])  # {"score": 95, "level": "high"}
```

## API Key

Get a free API key at [agenttax.io](https://agenttax.io) — 100 calls/month at no cost.

## Methods

### `calculate(**kwargs)`

Calculate sales tax for a transaction.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `role` | str | ✓ | `"seller"` or `"buyer"` |
| `amount` | float | ✓ | Transaction amount in USD |
| `buyer_state` | str | ✓ | Two-letter state code |
| `transaction_type` | str | ✓ | `"saas"`, `"compute"`, `"consulting"`, etc. |
| `counterparty_id` | str | ✓ | Counterparty identifier |
| `work_type` | str | | `"compute"`, `"research"`, `"content"`, `"consulting"`, `"trading"` |
| `is_b2b` | bool | | Business-to-business transaction |
| `buyer_zip` | str | | 5-digit ZIP for local rate lookup |

### `get_rates(state=None, format=None, explain=False)`

Fetch sales tax rates for all 51 jurisdictions. No auth required.

### `get_capital_gains_rates(state=None)`

Fetch state capital gains rates. No auth required.

### `get_local_rate(zip_code)`

Fetch combined local + state rate for a ZIP code.

### `get_transactions(limit=50, offset=0, ...)`

Fetch transaction history. Auth required.

### `log_trade(**kwargs)` / `get_trades(**kwargs)`

Capital gains trade tracking (FIFO/LIFO/Specific ID). Auth required.

## Error Handling

```python
from agenttax import AgentTaxClient, AuthError, RateLimitError, ValidationError

client = AgentTaxClient(api_key="atx_live_...")

try:
    result = client.calculate(...)
except AuthError:
    # Invalid or missing API key
    pass
except RateLimitError:
    # Monthly quota exceeded — upgrade tier or wait
    pass
except ValidationError as e:
    # Bad request parameters
    print(e)
```

## Free Tier

100 API calls/month at $0. Paid plans start at $25/month (10K calls).
See [agenttax.io/pricing](https://agenttax.io/pricing).
