Metadata-Version: 2.4
Name: agenttax
Version: 0.2.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
Project-URL: Agent Guide, https://agenttax.io/api/v1/agents
Project-URL: Pricing, https://agenttax.io/api/v1/pricing
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 — no signup required

```python
from agenttax import AgentTaxClient

client = AgentTaxClient()          # keyless: demo mode, 50 calls/day

result = client.calculate(
    role="buyer",                  # buyer side needs no nexus setup
    amount=1000.00,
    buyer_state="TX",
    transaction_type="compute",
    counterparty_id="agent_seller_001",
)

print(result["total_tax"])         # use tax owed on the purchase
print(result["combined_rate"])     # the location's composed rate (state + local)
print(result["applied_rate"])      # the rate actually applied to compute total_tax
print(result["confidence"])        # {"score": ..., "level": ...}
```

Demo mode returns the tax figure, the rate and a confidence score. It omits the
audit trail, jurisdiction breakdown and advisories, and it keeps no history.

## API Key

Get a free API key at [agenttax.io](https://agenttax.io) — 1,500 calls/month at no
cost — for the full response plus transaction history, nexus monitoring, capital
gains tracking and 1099 export.

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

### Why `role="seller"` returns $0.00 on a new account

A seller only has to collect tax where it has economic nexus, and a new account
has none configured — so every seller-side calculation correctly returns
`total_tax` 0 with `final_determination: "no_nexus"` until you set nexus up:

```python
import requests
requests.post(
    "https://agenttax.io/api/v1/nexus",
    headers={"X-API-Key": "atx_live_..."},
    json={"nexus": {"TX": {"hasNexus": True, "reason": "Economic nexus"}}},
)
```

Or pass `nexus_override={"TX": {"hasNexus": True}}` to `calculate()` to model a
seller position without saving it. Note the shape — a bare list of state codes
is read as "no nexus" and silently returns $0.00. Buyer-side calls need none of
this, which is why the quickstart above starts there.

## 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 |
| `use_context` | str | | `"enterprise_system"`, `"individual"`, or `"mixed"` — Maryland-only in v1, declares whether the purchase is solely for commercial use in an enterprise computer system (TB-56); absent = unchanged `is_b2b`-proxy default |
| `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

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