# AgentTax — Agent Integration Guide

**If you are an AI coding agent, this file tells you everything you need to integrate AgentTax into your project.**

Base URL: `https://agenttax.io`
Docs: `https://agenttax.io/?view=api-docs`
Live guide (always current): `GET https://agenttax.io/api/v1/agents`

---

## What AgentTax Does

AgentTax calculates US sales tax, use tax, and capital gains for AI agent transactions. When your agent buys compute from another agent, AgentTax tells you exactly how much tax is owed, which jurisdiction it goes to, and why.

---

## 5-Minute Integration

### 1. Sign up and save your API key

```bash
curl -X POST https://agenttax.io/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "securepass", "agent_name": "my-agent", "agent_work_type": "compute"}'
```

Response (truncated):

```json
{
  "success": true,
  "api_key": {
    "key": "atx_live_abc123xyz...",
    "prefix": "atx_live_abc1",
    "note": "Save this key — it won't be shown again."
  },
  "next_steps": [
    "Save your API key securely",
    "Try a test calculation: POST /api/v1/calculate"
  ]
}
```

**Save the `api_key.key` value immediately.** It is only returned once at signup.

Or skip signup and use demo mode (no key needed, 50 calls/day).

### 1.5. Configure your nexus states (sellers only)

If you're a seller, you must configure which states you have economic nexus in. Without this, **sales tax** on seller calculations returns $0 (no collection obligation) with a `nexus_warning` advisory.

One exception, and it is the one most likely to surprise you: taxes that are not the seller's sales tax are not gated on your nexus. The Chicago Personal Property Lease Transaction Tax (15%) is a city lease tax levied on the Chicago **buyer**, so a Chicago SaaS transaction returns a non-zero total with no nexus configured at all. A $0 total means "no sales tax collection obligation," not "no tax on this transaction" — read `nexus_warning` and the advisories rather than the total alone.

```bash
curl -X POST https://agenttax.io/api/v1/nexus \
  -H "X-API-Key: atx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "nexus": {
      "TX": { "hasNexus": true, "reason": "Economic nexus — over $500K revenue" },
      "NY": { "hasNexus": true, "reason": "Physical presence" },
      "CA": { "hasNexus": true, "reason": "Economic nexus" }
    }
  }'
```

Buyers don't need nexus configuration — use tax is calculated regardless.

### 2. Calculate tax on a transaction

```bash
curl -X POST https://agenttax.io/api/v1/calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: atx_live_your_key" \
  -d '{
    "role": "buyer",
    "amount": 500,
    "buyer_state": "TX",
    "buyer_zip": "78701",
    "transaction_type": "compute",
    "work_type": "compute",
    "counterparty_id": "seller-agent-123",
    "is_b2b": true
  }'
```

### 3. Read the response

```json
{
  "success": true,
  "engine_version": "1.5",
  "transaction_id": "txn_m3k9x2_a1b2c3",
  "timestamp": "2026-03-26T14:30:00.000Z",
  "amount": 500,
  "buyer_state": "TX",
  "buyer_zip": "78701",
  "jurisdiction": "Austin, TX",
  "combined_rate": 0.0825,
  "work_type": "compute",
  "classification_basis": "data_processing",
  "total_tax": 33.00,
  "use_tax": {
    "jurisdiction": "Austin, TX",
    "state_rate": 0.0625,
    "local_rate": 0.02,
    "combined_rate": 0.0825,
    "rate": 0.0825,
    "amount": 33.00,
    "gross_amount": 500,
    "taxable_amount": 400,
    "taxable_percentage": 0.80,
    "reason": "Austin, TX 8.25% combined rate applied to 80% of Compute/Processing ($400.00 of $500.00).",
    "note": "TX Tax Code §151.351 — 20% statutory exemption"
  },
  "confidence": { "score": 90, "level": "complete", "factors": ["..."] },
  "audit_trail": {
    "engine_version": "1.5",
    "jurisdiction_chain": [
      { "level": "state", "jurisdiction": "Texas", "code": "TX", "rate": 0.0625, "applied": true, "source": "TAX_RATES" },
      { "level": "local", "jurisdiction": "Austin", "zip": "78701", "rate": 0.02, "applied": true, "source": "LOCAL_RATES" },
      { "level": "special_rule", "rules": [
        { "rule": "taxable_percentage", "state": "TX", "value": 0.80, "effect": "Taxable base reduced to 80%", "note": "TX Tax Code §151.351 — 20% statutory exemption" }
      ]}
    ],
    "combined_rate": 0.0825,
    "classification": {
      "input_transaction_type": "compute",
      "input_work_type": "compute",
      "resolved_work_type": "compute",
      "work_type_source": "explicit",
      "economic_category": "data_processing",
      "label": "Compute/Processing"
    },
    "taxability": {
      "source": "TAXABILITY_MATRIX",
      "state": "TX",
      "category": "data_processing",
      "taxable": true,
      "note": "TX Tax Code §151.351 — 20% statutory exemption"
    },
    "exemptions_evaluated": [
      { "check": "no_sales_tax", "result": "not_exempt", "detail": "Texas has 6.25% state sales tax" },
      { "check": "financial_service", "result": "not_exempt", "detail": "Category is data_processing" },
      { "check": "b2b_statutory", "result": "not_exempt", "detail": "B2B exemption does not apply in Texas for data_processing" }
    ],
    "final_determination": "taxable",
    "policy_references": [
      { "id": "texas_80pct_rule", "settlement": "settled", "note": "TX Tax Code §151.351" }
    ]
  },
  "advisories": [],
  "disclaimer": "This calculation is informational only and does not constitute tax advice."
}
```

---

## API Reference

### Core Endpoints

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `/api/v1/calculate` | POST | API Key / x402 / Demo | Calculate sales/use tax |
| `/api/v1/trades` | POST | API Key | Log a buy or sell trade |
| `/api/v1/trades` | GET | API Key | List trades with realized gains |
| `/api/v1/transactions` | GET | API Key | Transaction history |
| `/api/v1/nexus` | POST/GET | API Key | Configure nexus states |
| `/api/v1/rates` | GET | None | 50-state rate data |
| `/api/v1/rates/local` | GET | None | Zip-level combined rates |
| `/api/v1/rates/capital-gains` | GET | None | State capital gains rates |
| `/api/v1/network` | POST/GET | API Key | Agent network profile |
| `/api/v1/network-directory` | GET | None | Browse agent directory |
| `/api/v1/export/1099-da` | GET | API Key | IRS Form 1099-DA export |
| `/api/v1/verify` | POST | None | Cross-verify rates against 8 sources |
| `/api/v1/agents` | GET | None | This integration guide (plain text) |
| `/api/v1/health` | GET | None | Health check |
| `/api/v1/pricing` | GET | None | Structured pricing tiers (machine-readable) |

### Authentication

Three modes — use whichever fits your architecture:

1. **API Key** (recommended): `X-API-Key: atx_live_xxx` header or `Authorization: Bearer atx_live_xxx`
2. **x402 USDC micropayment**: Pay-per-call via x402 protocol (USDC on Base). No account needed.
3. **Demo mode**: No auth. 50 calls/day, 30/min. Returns simplified responses (no audit trail).

### POST /api/v1/calculate — Required Fields

| Field | Type | Description |
|-------|------|-------------|
| `amount` | number | Transaction amount in USD |
| `buyer_state` | string | 2-letter US state code (e.g., `"TX"`) |
| `counterparty_id` | string | Identifier for the other party |

### POST /api/v1/calculate — Optional Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `role` | `"buyer"` or `"seller"` | `"seller"` | Your role in the transaction. Omitting it makes this a seller call, which returns $0 sales tax until nexus is configured — buyers should always send `"buyer"` |
| `transaction_type` | string | `"saas"` | See transaction types below |
| `buyer_zip` | string | null | 5-digit zip for local rate lookup |
| `work_type` | string | inferred | `compute`, `research`, `content`, `consulting`, `trading` |
| `is_b2b` | boolean | false | B2B flag (affects rates in MD, IA) |
| `digital_content_type` | string | null | What a downloaded product is: `ebook`, `audio`, `video`, `art_image`, `photograph`, `printable_document`, `software`, `data`, `other`. Used only with `transaction_type: "digital_good"`. See "Digital downloads" below |
| `seller_remitting` | boolean | null | Whether seller is collecting tax |
| `nexus_override` | object | null | Override nexus states (demo/x402 only) |

### Digital downloads: `digital_content_type`

Many states tax only a closed list of digital products (e-books, music, video) and do not tax digital art or printable documents. A plain `digital_good` cannot tell a printable planner from an e-book, so without more information the engine gives the conservative answer: the state's generic digital-goods treatment.

Send `digital_content_type` with `transaction_type: "digital_good"` to get the per-state answer for that kind of file:

- `art_image`: non-photographic digital art: illustrations, drawings, designs, clip art, digital paintings, wall-art prints that are not photographs.
- `photograph`: an image captured by a camera, including a camera photo of a painting. A few states treat photographs differently from other art (North Carolina taxes photographs but not other digital art; Arkansas keeps photographs taxable; Tennessee exempts them only to a buyer declared a consumer). Everywhere else a `photograph` gets the same answer as `art_image`.
- `printable_document`: PDF planners, worksheets, calendars, trackers, templates and similar printables that are not art or books.
- `ebook`, `audio`, `video`, `software`, `data`, `other`: accepted and recorded. Today they return the generic `digital_good` answer.

```json
{ "role": "seller", "amount": 12, "buyer_state": "MN", "transaction_type": "digital_good",
  "digital_content_type": "printable_document", "counterparty_id": "shop_buyer_7" }
```

- The value is echoed as `digital_content_type` in the response, recorded with the transaction, and shown in `audit_trail.classification` (`digital_content_type_applied`) and `audit_trail.taxability.digital_content_type_override`.
- When a declaration changes the answer, the response carries a `DIGITAL_CONTENT_TYPE_DECLARED` advisory. The answer rests on your description of the product; it is not a state safe harbor.
- A generic `digital_good` into a state that exempts art, photographs or printables carries a `DIGITAL_CONTENT_TYPE_MAY_REDUCE` advisory naming the types that would be exempt.
- Where a state has no separate photograph rule and the `art_image` rule answered, `audit_trail.taxability.digital_content_type_rule` is `"art_image"`.
- On any other `transaction_type` (for example `license` or `data_purchase`) the field is ignored and a `DIGITAL_CONTENT_TYPE_NOT_APPLIED` advisory says so.
- Where the law is unclear, the engine keeps the generic (taxable) answer for that state. Per-state treatment is on the [classification page](https://agenttax.io/classification).

### Transaction Types

`compute`, `api_access`, `data_purchase`, `saas`, `ai_labor`, `storage`, `digital_good`, `consulting`, `data_processing`, `cloud_infrastructure`, `ai_model_access`, `marketplace_fee`, `subscription`, `license`, `service`

### Work Types (drive per-state classification)

| Work Type | Economic Category | Use When |
|-----------|------------------|----------|
| `compute` | data_processing | GPU jobs, inference, batch processing |
| `research` | information_service | Analysis, data retrieval, search |
| `content` | digital_service | Text/image/video generation, SaaS |
| `consulting` | digital_service (Arizona: professional_service, exempt) | Advisory, recommendations, planning |
| `trading` | financial_service | Asset trading (routes to gains tracker) |

---

## Capital Gains Tracking

For trading bots and agents that buy/sell assets:

```bash
# Log a buy
curl -X POST https://agenttax.io/api/v1/trades \
  -H "X-API-Key: atx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_symbol": "COMPUTE",
    "trade_type": "buy",
    "quantity": 100,
    "price_per_unit": 12.50
  }'

# Log a sell — response includes realized gain/loss
curl -X POST https://agenttax.io/api/v1/trades \
  -H "X-API-Key: atx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_symbol": "COMPUTE",
    "trade_type": "sell",
    "quantity": 50,
    "price_per_unit": 18.00,
    "resident_state": "TX"
  }'
```

### POST /api/v1/trades — Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `asset_symbol` | string | yes | Asset identifier (e.g., `"COMPUTE"`, `"GPU_HOUR"`) |
| `trade_type` | `"buy"` or `"sell"` | yes | Buy or sell |
| `quantity` | number | yes | Number of units |
| `price_per_unit` | number | yes | Price per unit in USD |
| `accounting_method` | string | no | `"fifo"` (default), `"lifo"`, or `"specific_id"` |
| `resident_state` | string | no | 2-letter state code for state tax estimates on gains |
| `specific_lot_id` | string | no | Lot ID for specific identification method |
| `notes` | string | no | Free-text notes |

---

## Understanding the Response

### Audit Trail

Every authenticated response includes an `audit_trail` showing exactly how the tax was determined (see full example in Step 3 above):

- **`jurisdiction_chain`**: Layered rate composition — state base rate, local add-on, special rules (TX 80%, MD split, CT 1%)
- **`classification`**: How your `transaction_type` and `work_type` mapped to an economic category
- **`taxability`**: Which state rule (TAXABILITY_MATRIX or digitalTaxable fallback) determined taxability
- **`exemptions_evaluated`**: Every exemption check that was run and its result
- **`final_determination`**: `"taxable"` or the exemption type that applied
- **`policy_references`**: Which entries in the AgentTax Tax Policy Registry applied, with settlement status

Demo mode responses do not include `audit_trail`, `advisories`, or detailed tax objects. Create a free account ($0) to get the full response.

### Confidence Scoring

Every response includes a confidence object with a score (0-100) and level (`complete`, `high`, `partial`, `minimal`). To maximize confidence:
- Provide `buyer_zip` (not just `buyer_state`)
- Provide `work_type` explicitly
- Configure nexus states via `/api/v1/nexus`

### Advisories

The `advisories` array flags edge cases: zip/state mismatches, nexus warnings, classification review suggestions, local tax advisories (e.g., Chicago's Personal Property Lease Transaction Tax on cloud software, 15% from 2026-01-01).

---

## Common Integration Patterns

### Pattern 1: Pre-transaction tax lookup (buyer)

```python
import requests

response = requests.post("https://agenttax.io/api/v1/calculate", json={
    "role": "buyer",
    "amount": 1000,
    "buyer_state": "NY",
    "buyer_zip": "10001",
    "transaction_type": "compute",
    "work_type": "compute",
    "counterparty_id": "gpu-provider-42",
    "is_b2b": True
}, headers={"X-API-Key": API_KEY})

tax = response.json()
total_cost = 1000 + tax["total_tax"]  # Factor tax into budget
```

### Pattern 2: Invoice tax collection (seller)

```python
response = requests.post("https://agenttax.io/api/v1/calculate", json={
    "role": "seller",
    "amount": 2500,
    "buyer_state": "TX",
    "buyer_zip": "75201",
    "transaction_type": "saas",
    "work_type": "content",
    "counterparty_id": "buyer-agent-99"
}, headers={"X-API-Key": API_KEY})

tax = response.json()
invoice_total = 2500 + tax["total_tax"]
```

### Pattern 3: Multi-state rate check

```python
for state in ["TX", "NY", "CA", "WA"]:
    r = requests.get(f"https://agenttax.io/api/v1/rates?state={state}")
    data = r.json()
    print(f"{state}: {data['rate']*100}% — {data['saasNote']}")
```

### Pattern 4: x402 micropayment (no account)

```python
# Pay per call with USDC — no API key needed
# Your x402-compatible HTTP client handles payment automatically
response = x402_client.post("https://agenttax.io/api/v1/calculate", json={...})
```

---

## Key Concepts

- **Nexus**: Sellers must configure nexus states to get non-zero tax results. Without nexus config, seller calculations return $0. Use `POST /api/v1/nexus`. Buyers don't need this — use tax is calculated regardless.
- **Use tax**: If the seller doesn't collect, the buyer owes use tax. AgentTax calculates both.
- **Conservative default**: When law is ambiguous, AgentTax defaults to more tax, not less. Better to over-reserve than face penalties.
- **Local rates**: 105+ zip codes with city/county/district rates. Pass `buyer_zip` to get combined rates.
- **1099 tracking**: AgentTax tracks cumulative vendor payments and flags when a vendor's calendar-year total reaches the $2,000 1099-NEC threshold (OBBBA, TY 2026; it was $600 for TY 2025 and prior).

---

## Rate Limits

| Mode | Limit |
|------|-------|
| Demo (no key) | 50/day, 30/min |
| Free tier | 1,500 calls/month |
| Starter ($25/mo) | 10,000 calls/month |
| Growth ($99/mo) | 100,000 calls/month |
| Pro ($199/mo) | 1,000,000 calls/month |
| x402 | Unlimited (pay per call) |

---

## Error Handling

All errors return `{ "success": false, "error": "message", "agent_guide": "https://agenttax.io/api/v1/agents" }`. Common codes:

| Status | Meaning |
|--------|---------|
| 400 | Bad request — check `error` and `errors` fields |
| 401 | Invalid or missing API key |
| 402 | x402 payment required |
| 429 | Rate limited |
| 405 | Wrong HTTP method |

---

## Need Help?

- This guide (always current): https://agenttax.io/api/v1/agents
- API docs: https://agenttax.io/?view=api-docs
- Health check: https://agenttax.io/api/v1/health
- Rate data: https://agenttax.io/api/v1/rates