API Reference

Demo calls store nothing. Keyed calls are saved to your own account as transaction history. Use a throwaway counterparty_id while testing.

# No key, no signup. Paste this into a terminal.
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"}'

pip install agenttax

Also accepts Authorization: Bearer atx_live_... — Keys are SHA-256 hashed. Raw key shown once at creation.

POST /api/v1/calculate works with no key and no payment. It is the only endpoint that does. The request body is the same, including the required counterparty_id.

• Limits, per IP: 30 requests per minute and 10 per UTC day (resets at 00:00 UTC). Every request counts, including ones rejected with 400. Remaining calls are in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Over either limit returns 429 RATE_LIMITED with a free-signup block and the x402 pay-per-call option.
• What it returns: "mode": "demo", total_tax, combined_rate, applied_rate, classification_basis, a confidence score and level, nexus_configured_for_state, resolution and "intent": "estimate". When a $0.00 comes from a default rather than a determination it also carries exemption or tax_if_nexus with a note.
• What it leaves out: the audit trail, the jurisdiction breakdown, advisories (for example the Chicago lease-tax advisory) and the sales_tax / use_tax detail. Do not treat a demo result as final without those. Seller-side demo calls use a shared demo nexus profile, not yours.
• Nothing is saved to an account: demo calls do not appear in any transaction history or nexus tracking.

A key is required for the full response, your own nexus configuration, transaction history, volume above the demo limits (the free tier is 1,500 calls/month, no card), and every other authenticated endpoint. A key is free: POST /api/v1/auth/signup.

Every /calculate response, keyed or keyless, carries resolution. It answers three questions on their own axes, so you can tell a confident figure from a guess.

"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."
}

• location: did a local rate answer, or only the state rate? Bases zip_local_rate, zip_not_in_db, zip_proxy, state_only, no_location.
• nexus: does the figure rest on your own nexus answer? Bases configured, override, no_nexus_profile, not_applicable (buyer calls). Keyless seller calls read unknown here, because they run on a shared demo nexus profile.
• taxability: did a researched rule answer? Bases category_rule, state_override, no_sales_tax, simplified_flag, fact_not_declared (the detail names the field to send), held_conservative, exemption_certificate (a certificate on file answered).

Each axis is { status, basis, detail }. status is resolved, partial or unknown. Branch on status and basis. detail is a sentence for people; never parse it. total_tax is never withheld. If you want "unknown means do not charge," branch on resolution.*.status yourself.

Quote before you charge: send "intent": "estimate" with your key. You get the same figures and the same resolution, and nothing is saved: no transaction row and no nexus revenue. An estimate still counts toward your monthly calls. Idempotency-Key is ignored on an estimate, so a paid retry is a new paid call.

Test mode (atx_test_ prefixed keys) is on the roadmap. Until then, test with demo calls or the free tier (1,500 calls/month, no credit card). Demo calls store nothing. Keyed calls are saved to your account as transaction history, so use a throwaway counterparty_id while you test.

Keyed /calculate calls are rate-limited per API key to 120 requests per 60 seconds. Going over returns 429 RATE_LIMITED with a Retry-After header. Using up the Free plan's 1,500 calls/month also returns 429 RATE_LIMITED, but with a "Monthly limit reached" error, an upgrade block and no Retry-After — retrying will not help until the month resets.

X-RateLimit-Limit: 120          # Requests allowed per 60-second window
X-RateLimit-Remaining: 117      # Requests left in the current window
X-RateLimit-Reset: 1714521600   # Unix time when the current window resets

# On burst 429 responses:
Retry-After: 2                  # Seconds to wait before retrying

These headers describe the short burst window, not your monthly allowance. Monthly usage is on your dashboard. Recommended retry strategy for a burst 429: honor Retry-After, otherwise exponential backoff starting at 1 second, maximum 5 retries, jitter ±20%. Do not retry a 429 whose error says "Monthly limit reached".

All endpoints return errors in a consistent envelope. SDKs should branch on code (a frozen SCREAMING_SNAKE enum) rather than the human-readable error string.

{
  "success": false,
  "code": "INVALID_INPUT",
  "error": "buyer_state is required for seller role calculations",
  "request_id": "req_01HX..."
}

Idempotency Keys

AI agents frequently retry failed network calls. To prevent duplicate tax entries or double-counted trades, include an Idempotency-Key header on POST requests.

curl -X POST https://www.agenttax.io/api/v1/trades \
  -H "Content-Type: application/json" \
  -H "X-API-Key: atx_live_YOUR_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"asset_symbol":"ETH","trade_type":"buy","quantity":1,"price_per_unit":3000}'

# Retry with same key → returns cached response, no duplicate entry
# Response includes: X-Idempotency-Status: cached