AgentTax Python SDK

Sales tax, use tax, and capital gains for AI agents. Full docs at agenttax.io/api-docs.

Install

pip install agenttax

Quickstart — no signup required

from agenttax import AgentTaxClient

client = AgentTaxClient()          # keyless: demo mode, 10 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. The response also carries resolution (a resolved, partial or unknown status for location, nexus and taxability) and intent, which is always "estimate" on a keyless call.

API Key

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

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:

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.

Estimate without saving (since 0.3.0)

Pass intent="estimate" on a keyed call to price a purchase before you commit to it. You get the same figures, and nothing is saved: no transaction row, no nexus revenue, and the Idempotency-Key header is ignored (a paid retry is a new paid call). An estimate still counts toward your monthly calls. "record" is the default on keyed calls; keyless calls are always estimates.

quote = client.calculate(
    role="buyer",
    amount=1000.00,
    buyer_state="TX",
    transaction_type="compute",
    counterparty_id="agent_seller_001",
    intent="estimate",
)

print(quote["intent"])                            # "estimate"
print(quote["resolution"]["taxability"]["status"])  # "resolved" | "partial" | "unknown"

Every response carries resolution: a typed status (resolved, partial or unknown) and a basis for each of location, nexus and taxability. total_tax is never withheld, so if you want "unknown means don't charge", branch on resolution[...]["status"] yourself.

Classification facts (since 0.3.0)

Some products are taxed differently depending on facts only you know. Send them and the API uses them. Leave them out and you get the conservative answer. The SDK checks no values. The API does, and a bad value raises ValidationError. Dict facts are sent unchanged, so their inner keys use the API's snake_case names. Each fact is your representation, recorded with the transaction. It is not a state safe harbor.

# A printable planner sold as a download
client.calculate(
    role="seller",
    amount=12.00,
    buyer_state="NY",
    transaction_type="digital_good",
    counterparty_id="buyer_001",
    digital_content_type="printable_document",
)

# Custom software written for one buyer
client.calculate(
    role="seller",
    amount=5000.00,
    buyer_state="TX",
    transaction_type="service",
    work_type="custom_software",
    counterparty_id="buyer_002",
    custom_software_attestation={
        "written_for_buyer": True,
        "not_offered_to_others": True,
        "deliverable": "source_code",           # or "compiled_artifact"; "hosted" is SaaS
        "is_modification_of_prewritten": False,
    },
)

# A software maintenance contract with itemized parts
client.calculate(
    role="seller",
    amount=1000.00,
    buyer_state="PA",
    transaction_type="software_maintenance",
    counterparty_id="buyer_003",
    maintenance_contract={
        "includes_upgrades": True,
        "includes_support": True,
        "separately_itemized": True,
        "itemized_amounts": {"updates": 600, "support": 400},  # sums to amount
    },
)

The optional state facts inside custom_software_attestation and maintenance_contract are listed at agenttax.io/api-docs.

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, buyer_state=..., role=..., since=...)

Fetch transaction history — the newest limit rows (max 1000). Filters: buyer_state, role, since (ISO date), passed as keywords. Auth required. The endpoint has no offset or transaction-type filter: passing offset or transaction_type raises ValidationError rather than being silently ignored. Page with since.

log_trade(**kwargs) / get_trades(**kwargs)

Capital gains trade tracking (FIFO/LIFO/Specific ID). Auth required. log_trade takes fee_amount, accounting_method ("fifo", "lifo", "specific_id"), specific_lot_id (required with "specific_id") and resident_state (the taxpayer's state of residence, for the state estimate). The 0.1.0 names fees, cost_basis_method and buyer_state are still accepted and sent under the canonical names.

Error Handling

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.