API Reference

pip install agenttax

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

POST /api/v1/calculate also answers with no API 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 50 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, and nexus_configured_for_state. 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.

Test mode (atx_test_ prefixed keys) is on the roadmap. Until available, use the free tier (1,500 calls/month, no credit card) for integration testing. The free tier writes to live data — use a dedicated test account.

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://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