# 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://www.agenttax.io`
Docs: `https://www.agenttax.io/api-docs`
Live guide (always current): `GET https://www.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. Call it now, no key

`POST /api/v1/calculate` works with no key and no signup. The body is the same as a keyed call. Demo mode allows 10 calls a day and 30 a minute per IP.

```bash
curl -X POST https://www.agenttax.io/api/v1/calculate \
  -H "Content-Type: application/json" \
  -d '{"role":"buyer","amount":2500,"buyer_state":"TX","transaction_type":"api_access","counterparty_id":"seller_01"}'
```

Real response (demo mode, trimmed):

```json
{
  "success": true,
  "mode": "demo",
  "role": "buyer",
  "amount": 2500,
  "buyer_state": "TX",
  "transaction_type": "api_access",
  "classification_basis": "data_processing",
  "total_tax": 125,
  "applied_rate": 0.0625,
  "confidence": { "score": 62, "level": "partial" }
}
```

The demo response leaves out the audit trail, the jurisdiction breakdown and advisories. It also carries an `upgrade` block with the signup body.

**What gets stored:** Demo calls store nothing. Keyed calls are saved to your own account as transaction history. Use a throwaway `counterparty_id` while testing.

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

A key is free. It unlocks the full response, your own nexus, transaction history and 1,500 calls a month. No card.

```bash
curl -X POST https://www.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,
  "message": "Account created successfully",
  "entity": { "id": "ent_abc123_def456", "email": "you@example.com", "tax_tier": "free", "gains_tier": "free" },
  "agent": { "id": "agt_abc123_def456", "name": "my-agent", "work_type": "compute" },
  "api_key": {
    "key": "atx_live_abc123xyz...",
    "prefix": "atx_live_abc1",
    "note": "Save this key — it won't be shown again."
  },
  "tier_limits": {
    "tax_engine": { "limit": 1500, "period": "month", "tier": "free" },
    "gains_tracker": { "limit": 100, "period": "month", "tier": "free" }
  },
  "next_steps": [
    "Save your API key now — it is not shown again",
    "Make your first call with the `first_call` spec below",
    "Docs: https://agenttax.io/api-docs — pricing: https://agenttax.io/pricing"
  ],
  "first_call": {
    "method": "POST",
    "endpoint": "/api/v1/calculate",
    "content_type": "application/json",
    "headers": { "X-API-Key": "<your_key>" },
    "body": { "role": "buyer", "amount": 100, "buyer_state": "IL", "buyer_zip": "60601", "transaction_type": "saas", "counterparty_id": "seller_agent_1" },
    "required": ["amount", "buyer_state", "counterparty_id"]
  }
}
```

The response also sets a session cookie for the dashboard. `first_call` is a runnable request: send it with your key and the answer is $15.00 (the Chicago lease tax on a $100 SaaS purchase by a buyer who is not exempt).

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

### 2.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://www.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.

### 3. Calculate tax with your key

```bash
curl -X POST https://www.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
  }'
```

### 4. 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": 95, "level": "complete", "factors": ["..."] },
  "resolution": {
    "location": { "status": "resolved", "basis": "zip_local_rate", "detail": "ZIP 78701 matched the local rate for Austin, TX." },
    "nexus": { "status": "resolved", "basis": "not_applicable", "detail": "Use tax is the buyer's own obligation, so seller nexus does not apply." },
    "taxability": { "status": "resolved", "basis": "category_rule", "detail": "Texas treats data_processing as taxable under its category rule." }
  },
  "intent": "record",
  "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. 10 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`, `information_service`, `content`, `consulting`, `trading`, and the classification types `payment_processing`, `web_hosting`, `software_maintenance`, `it_support`, `custom_software` |
| `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 |
| `payment_provider_type` | string | null | With `payment_processing_fee`: `bank`, `licensed_money_transmitter`, `card_network`, `processor_routing_to_bank_or_network`, `other`. See "Classification facts" below |
| `it_support_scope` | string | null | With `it_support`: `help_desk_advice`, `remote_repair_or_config`, `software_installation`, `monitoring`, `security_monitoring`, `managed_bundle` |
| `includes_prewritten_software_access` | boolean | false | With `web_hosting`: true when the plan includes vendor software beyond a control panel (site builder, CMS, email suite, managed app) |
| `custom_software_attestation` | object | null | Required with `work_type: "custom_software"` |
| `maintenance_contract` | object | null | With `software_maintenance`: `mandatory`, `includes_upgrades`, `includes_support`, `separately_itemized`, `itemized_amounts`, `update_delivery`, `support_kind`, `business_use` |
| `seller_remitting` | boolean | null | Whether seller is collecting tax |
| `nexus_override` | object | null | Override nexus states (demo/x402 only) |
| `intent` | `"estimate"` or `"record"` | `"record"` | `"estimate"` computes the same figures and saves nothing: no transaction row, no nexus revenue, and `Idempotency-Key` is ignored. It still counts toward your monthly calls. Keyless calls are always estimates. Echoed as `intent` in the response |

### 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://www.agenttax.io/classification).

### Classification facts (payment fees, web hosting, custom software, maintenance contracts, IT support)

Five kinds of sale have their own per-state rules. Every fact below is optional; without it the engine gives the conservative answer for the buyer's state and an advisory names the fact that would change it.

- **Payment processing / facilitator fees**: `transaction_type: "payment_processing_fee"`. Most states do not tax them. `payment_provider_type` matters in Texas (a §151.0035(b)(3) provider is not taxed), South Dakota (a bank is exempt) and Iowa (a non-bank provider is exempt).
- **Web hosting**: `transaction_type: "web_hosting"` for hosting the buyer's own site or app. Send `includes_prewritten_software_access: true` when the plan also gives the buyer vendor software beyond a control panel; several states then tax it like SaaS. Chicago buyers owe the city lease tax.
- **Custom software**: `work_type: "custom_software"` with `custom_software_attestation` `{ written_for_buyer, not_offered_to_others, deliverable: "source_code" | "compiled_artifact", is_modification_of_prewritten }` (plus `separately_stated_charge` for a modification, and the state facts `all_rights_transferred`, `delivery`, `il_requirements_analysis_and_adaptation`, `il_assembled_modules_50pct`). Without a complete attestation the call is answered as prewritten software or SaaS.
- **Software maintenance contracts**: `transaction_type: "software_maintenance"` with `maintenance_contract`. Missing facts are answered as a contract that includes updates (the highest leg the facts leave possible).
- **IT support / managed IT**: `transaction_type: "it_support"` (or `work_type: "it_support"`), with `it_support_scope` when the engagement is only help-desk advice, monitoring, software installation, or repair/configuration.

The declared facts are echoed in `classification_facts`, recorded with the transaction, and shown in `audit_trail.classification`; a fact that changed the answer is named in `audit_trail.taxability.fact_override` and a `CLASSIFICATION_FACT_APPLIED` advisory. They are your representation, not a state safe harbor.

### 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`, `payment_processing_fee`, `web_hosting`, `software_maintenance`, `it_support`

### 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 |
| `information_service` | information_service | Data feeds, lookups, reports (same category as `research`) |
| `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) |
| `payment_processing` | payment_processing | Payment or facilitator fees (send `transaction_type: "payment_processing_fee"`) |
| `web_hosting` | web_hosting | Hosting the buyer's own site or app |
| `software_maintenance` | software_maintenance | Maintenance contracts (with `maintenance_contract`) |
| `it_support` | it_service | Help desk, monitoring, repair, managed IT (with `it_support_scope`) |
| `custom_software` | custom_software | Software written for one buyer (with `custom_software_attestation`) |

---

## Capital Gains Tracking

For trading bots and agents that buy/sell assets:

```bash
# Log a buy
curl -X POST https://www.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://www.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 4 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`

### Resolution (typed unknowns)

`confidence` blends three questions into one score. `resolution` answers each one on its own axis, so a program can tell a confident figure from a guess. Every `/calculate` response carries it, keyed and keyless.

- `location`: did a local rate answer, or only the state rate?
- `nexus`: does the figure rest on your own nexus answer for `buyer_state`?
- `taxability`: did a researched rule answer, or a fallback, a missing fact, or a disclosed conservative hold?

Each axis is `{ status, basis, detail }`. Branch on `status` and `basis`. `detail` is one plain sentence for people; never parse it.

`status` is always one of `resolved`, `partial` or `unknown`. Handle all three on every axis, even where an axis does not use one today.

| Axis | `status` used today | `basis` values |
|------|---------------------|----------------|
| `location` | `resolved`, `partial` (`unknown` reserved) | `zip_local_rate`, `zip_not_in_db`, `zip_proxy`, `state_only`, `no_location` (reserved) |
| `nexus` | `resolved`, `unknown` | `configured`, `override`, `no_nexus_profile`, `not_applicable` |
| `taxability` | `resolved`, `partial` | `category_rule`, `state_override`, `no_sales_tax`, `simplified_flag`, `fact_not_declared`, `held_conservative`, `exemption_certificate` |

What the bases mean:
- `zip_local_rate`: the ZIP matched a local rate. `zip_not_in_db`: a ZIP was sent but no local rate for it applied, so only the state rate was used. `zip_proxy`: an origin-sourced sale with no `seller_zip`, so `buyer_zip` stood in. `state_only`: no ZIP was sent. It reads resolved only where no ZIP could change the figure. `no_location` (with `unknown`) is reserved. The API never sends it today, because a call with no valid buyer state is rejected first.
- `configured`: your account answered for this state, yes or no. `override`: `nexus_override` on this request answered. `no_nexus_profile`: nobody answered, so a seller's sales tax defaulted to $0 (see `tax_if_nexus`). `not_applicable`: a buyer call. Use tax does not depend on seller nexus.
- `category_rule`, `state_override`, `no_sales_tax` and `exemption_certificate` are resolved. `exemption_certificate`: an exemption certificate on file for the buyer's state answered, so no undeclared fact can change the figure. `simplified_flag`: no rule for this category, so the state's general rule for digital products answered. `fact_not_declared`: a request field you did not send would change or confirm the answer, and `detail` names it. `held_conservative`: the law is unsettled or an exemption is not evaluated, so AgentTax charges the higher answer on purpose.

`total_tax` is never withheld. If you want "unknown means do not charge," branch on `resolution.*.status` yourself. Keyless seller calls run on a shared demo nexus profile, so their nexus axis reads `unknown` / `no_nexus_profile` (or `resolved` / `override` when you send `nexus_override`). Keyless buyer calls read `not_applicable`.

(a) Seller, nexus set for TX, `{"role":"seller","amount":500,"buyer_state":"TX","buyer_zip":"78701","transaction_type":"compute","work_type":"compute"}`. `total_tax` is 33.

```json
"resolution": {
  "location": { "status": "resolved", "basis": "zip_local_rate", "detail": "ZIP 78701 matched the local rate for Austin, TX." },
  "nexus": { "status": "resolved", "basis": "configured", "detail": "This account has nexus set for Texas." },
  "taxability": { "status": "resolved", "basis": "category_rule", "detail": "Texas treats data_processing as taxable under its category rule." }
}
```

(b) Seller, no nexus set, `{"role":"seller","amount":100,"buyer_state":"IL","buyer_zip":"60601","transaction_type":"saas"}`. `total_tax` is 15, because the Chicago lease tax does not depend on seller nexus.

```json
"resolution": {
  "location": { "status": "resolved", "basis": "zip_local_rate", "detail": "ZIP 60601 matched the local rate for Chicago, IL." },
  "nexus": { "status": "unknown", "basis": "no_nexus_profile", "detail": "No nexus is set for Illinois, but the Chicago city tax does not depend on it and is charged." },
  "taxability": { "status": "partial", "basis": "held_conservative", "detail": "The Chicago lease tax is charged in full because its exemptions are not evaluated." }
}
```

**Pre-authorization estimate.** Send `"intent": "estimate"` to quote a price before anyone pays.
You get the same figures and the same `resolution`, and the response echoes `"intent": "estimate"`.
Nothing is saved: no transaction row and no nexus revenue.
`Idempotency-Key` is ignored on an estimate, so a paid retry is a new paid call.
An estimate still counts toward your monthly calls. Keyless calls are always estimates.

```bash
curl -X POST https://www.agenttax.io/api/v1/calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: atx_live_your_key" \
  -d '{"role":"seller","amount":100,"buyer_state":"IL","buyer_zip":"60601","transaction_type":"saas","counterparty_id":"buyer-7","intent":"estimate"}'
```

### 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://www.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
```

Quoting before you commit? Add `"intent": "estimate"` to the body. You get the same figures and nothing is saved to your history. Check `tax["resolution"]` to see which inputs were resolved.

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

```python
response = requests.post("https://www.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://www.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://www.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.
<!-- 6,636 is filled from api/_lib/coverage.js when this file is served at /api/v1/agents. The GitHub copy shows the token on purpose, so the number is never typed by hand again. -->
- **Local rates**: 6,636 zip-level local rates with city/county/district add-ons. Pass `buyer_zip` to get combined rates; a ZIP with no local row falls back to the state rate and `resolution.location` says so.
- **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) | 10/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://www.agenttax.io/api/v1/agents
- API docs: https://www.agenttax.io/api-docs
- Health check: https://www.agenttax.io/api/v1/health
- Rate data: https://www.agenttax.io/api/v1/rates