---
title: "Calculate sales tax for an agent transaction"
method: POST
path: "/api/v1/calculate"
tags: ["Tax Calculation"]
---

# Calculate sales tax for an agent transaction

`POST /api/v1/calculate`

## Request

- Base URL: `https://www.agenttax.io`
- URL: `https://www.agenttax.io/api/v1/calculate`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-PAYMENT`
  - none

Computes US sales tax for a single agent-to-agent or agent-to-human transaction. Handles destination vs origin sourcing automatically (TX/UT/AZ/TN apply origin sourcing intrastate; OH applies origin sourcing intrastate ONLY to TPP/digital-goods retail sales — transaction_type license/digital_good — per R.C. 5739.033(B)(1), with services destination-sourced). Routes work_type → economic_category → state-specific taxability via TAXABILITY_MATRIX with DEFAULT_CATEGORY_RULES fallback.

Authentication: API key (Bearer) **or** x402 X-PAYMENT header. Demo mode (no auth): the same request works with no key and no payment, limited to 30 requests/minute and 50 per UTC day per IP (every request counts, including 400s; X-RateLimit-* headers report the daily window; over either limit returns 429 RATE_LIMITED with a signup block and the x402 option). The demo response carries mode "demo", total_tax, combined_rate, applied_rate, classification_basis, confidence and nexus_configured_for_state (plus exemption or tax_if_nexus when a $0.00 is a default), and omits the audit trail, jurisdiction breakdown, advisories and sales_tax/use_tax detail. Seller-side demo calls use a shared demo nexus profile. Demo calls are not saved to any account. A key (free signup) is required for the full response, your own nexus, transaction history and higher volume.

## Request body

- CalculateRequest
  - `role` 'seller' | 'buyer'
  - `amount` number, required: USD amount, greater than 0 up to $100M. Decimal strings are normalized to numbers.
  - `buyer_state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'DC', required: Two-letter US state code (or DC).
  - `seller_state` string: Two-letter US state code (or empty string).
  - `buyer_zip` string: 5-digit US zip code (empty string allowed).
  - `seller_zip` string: Required for TX/UT/AZ/TN origin-sourced intrastate sales, and for intrastate OH sales of software licenses or digital products (transaction_type license/digital_good), which are origin-sourced per Ohio R.C. 5739.033(B)(1) — seller_zip proxies the vendor's order-receipt location. Intrastate OH services remain destination-sourced.
  - `transaction_type` '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_type` 'compute' | 'research' | 'information_service' | 'content' | 'consulting' | 'trading' | 'payment_processing' | 'web_hosting' | 'software_maintenance' | 'it_support' | 'custom_software': Economic classification of the agent's work. Drives per-state taxability via the engine's TAXABILITY_MATRIX. - `compute` → data_processing (TX 80% rule applies) - `research` → information_service (AI-generated research output) - `information_service` → information_service (database/data-subscription products like Westlaw/LexisNexis) - `content` → digital_service (writing, media generation) - `consulting` → digital_service (2026-04-21 registry update: AI consulting does not qualify for professional-service exemptions — no licensed practitioner, productizable output; the TAXABILITY_MATRIX governs per-state outcome. Exception: in AZ a declared consulting work_type is an exempt professional service — A.R.S. §42-5061(A)(1), TPR 93-48 — and the response carries an AZ_CONSULTING_PROFESSIONAL_SERVICE advisory) - `trading` → financial_service (capital-gains-tracker primary)
  - `counterparty_id` string, required: Round-trips to public /api/v1/network-feed. Allowlist: alphanumeric + `_-.:@` only.
  - `is_b2b` boolean: Triggers state-specific B2B exemptions (IA, MD split rate).
  - `use_context` 'enterprise_system' | 'individual' | 'mixed': Declares the fact Maryland's TB-56 3%/6% axis actually turns on: whether this purchase is "solely for commercial purposes in an enterprise computer system" (Md. Code, Tax-Gen. §11-101(c-4)(3)(vi)). Optional; absent = unknown (status quo — the is_b2b-proxy 3%/6% split, unchanged). "enterprise_system": attests the purchase IS solely so used — MD's declared-B2B (is_b2b=true) 3% leg stands, and the response records an attestation-based advisory (Maryland prescribes no certificate or reliance mechanism for this axis; this is self-generated audit documentation, not a state safe harbor). "individual" or "mixed": declares the purchase is NOT solely so used — a declared-B2B MD buyer moves from the 3% leg to the 6% digital-product rate under §11-104(l)(2), the only direction this field can move tax. MONOTONE: use_context can never produce LESS tax than the is_b2b-only default for the same transaction. Has no effect when is_b2b is not also true, and no effect outside Maryland.
  - `digital_content_type` 'ebook' | 'audio' | 'video' | 'art_image' | 'photograph' | 'printable_document' | 'software' | 'data' | 'other': What the downloaded product is. Optional; used only with transaction_type `digital_good` (ignored, with a DIGITAL_CONTENT_TYPE_NOT_APPLIED advisory, on every other type or when an explicit work_type reclassifies the sale). Absent = the generic digital_good answer, unchanged. Several states tax only a closed list of digital products (e-books, music, video) and do not tax digital art or printable documents; the engine applies those per-state rules only when you declare the type. `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 tax photographs but not other art, or the reverse; where a state has no separate photograph rule, the art_image answer applies). `printable_document`: planners, worksheets, calendars, trackers, templates and similar printables that are not art or books. `ebook`, `audio`, `video`, `software`, `data` and `other` are accepted and recorded; today they return the generic digital_good answer. The declaration is echoed in the response and recorded with the transaction. It is your representation of the product, not a state safe harbor.
  - `payment_provider_type` 'bank' | 'licensed_money_transmitter' | 'card_network' | 'processor_routing_to_bank_or_network' | 'other': Who provides the payment processing (transaction_type payment_processing_fee). Optional; absent = the conservative answer. Changes the answer in TX (a Tax Code §151.0035(b)(3) provider — bank, licensed money transmitter, card network, or a downstream/point-of-sale processor routing to a bank or card network — is not taxed as data processing), SD (a bank subject to SDCL ch. 10-43 is exempt) and IA (a non-bank provider is exempt; a bank's checking-account charges and an unknown provider are taxed). Your representation, recorded with the transaction.
  - `it_support_scope` 'help_desk_advice' | 'remote_repair_or_config' | 'software_installation' | 'monitoring' | 'security_monitoring' | 'managed_bundle': What the remote IT support engagement is (transaction_type or work_type it_support). Optional; absent = a managed bundle, the per-state default. Some states answer specific scopes differently, e.g. help_desk_advice is exempt in KY, PA, TN, TX and UT; software_installation is taxable in KS, NE and NJ; remote_repair_or_config is taxable in NE, WI and WY.
  - `includes_prewritten_software_access` boolean: Web hosting only (transaction_type web_hosting). true when the plan gives the buyer vendor prewritten software beyond an incidental control panel or file manager — a site builder, CMS or app platform, email or office suite, or managed application. Absent or false = plain hosting of the buyer's own site or application; when absent the response carries a WEB_HOSTING_SOFTWARE_ACCESS_ASSUMED_FALSE advisory. Where a state taxes vendor software access differently from hosting, true applies that state's SaaS rule.
  - `custom_software_attestation` object: Required with work_type custom_software; without a complete attestation the call is answered as prewritten software / SaaS (CUSTOM_SOFTWARE_ATTESTATION_INCOMPLETE advisory). Complete = written_for_buyer true (designed and developed to this buyer's specifications), not_offered_to_others true, deliverable source_code or compiled_artifact (hosted access is SaaS), is_modification_of_prewritten set, and when it is true, separately_stated_charge true (the custom treatment then covers only that separately stated modification charge). State facts: separately_stated_charge (AL), all_rights_transferred (TX contract programming), delivery electronic|tangible (AR, SC tax tangible delivery), il_requirements_analysis_and_adaptation and il_assembled_modules_50pct (IL 86 Ill. Adm. Code 130.1935(c)). Maryland uses use_context: enterprise_system → 3%, otherwise 6%. Your representation, recorded with the transaction; not a state safe harbor.
  - `maintenance_contract` object: Facts about a software maintenance contract on prewritten software (transaction_type software_maintenance). Every field optional; a missing fact is answered conservatively (the contract is assumed to include updates and the highest leg the declared facts leave possible applies), with a SOFTWARE_MAINTENANCE_LEG advisory. mandatory: the buyer must buy it to get or keep using the software. includes_upgrades / includes_support: what the contract provides. separately_itemized + itemized_amounts {updates, support} (summing to amount): split the charge where the state taxes the parts differently. update_delivery: electronic (default) or tangible media. support_kind: help_desk_only releases support legs in PA, TN and NC where the state's conditions are met. business_use: the state's business-use attestation (CT 1%, IA and NJ exempt, MD 3% enterprise computer system); is_b2b alone does not apply it. seller_sold_software: accepted and recorded only; no state leg keys on it yet (a Texas contract from a provider that did not sell the program stays taxable until that leg is researched).
  - `marketplace_role` 'seller' | 'facilitator' | 'direct'
  - `description` string
  - `exemption_certificate` string
  - `nexus_override` object: Demo/test mode: per-state nexus injection (e.g. {"TX":{"hasNexus":true}}). Each value MUST carry a boolean hasNexus; extra keys pass through. Bypasses the entity's stored nexus config. Used by the public test harness and x402 inline calls.
  - `vendor_ytd_override` number: Demo/test mode: override 1099 vendor YTD accumulation for a single calculation. Finite, non-negative; decimal strings are normalized to numbers.
  - `seller_remitting` boolean: Buyer-mode use-tax flag: when role=buyer, set true to indicate the seller already collected and remitted sales tax (use_tax=$0), false when the buyer must self-assess and remit. Read by the engine via resolveSellerRemitting() and reflected in the seller_remitting block of the response. Used by the public test harness and direct buyer-mode callers.

## Response `200`

Tax calculation succeeded.

- union
  - CalculateLiveResponse
    - `success` true, required
    - `engine_version` string, required
    - `transaction_id` string, required
    - `timestamp` string, date-time, required
    - `role` 'seller' | 'buyer', required
    - `amount` number, required
    - `buyer_state` string, required
    - `buyer_zip` string, nullable, required
    - `seller_state` string, nullable, required
    - `seller_zip` string, nullable, required
    - `sourcing_rule` 'origin' | 'destination', required
    - `marketplace_role` string, required
    - `local_rate` number, required
    - `combined_rate` number, required
    - `jurisdiction` string, required
    - `transaction_type` string, required
    - `transaction_category` string, required
    - `work_type` string, nullable, required
    - `work_type_label` string, nullable, required
    - `classification_basis` string, required
    - `is_b2b` boolean, required
    - `use_context` 'enterprise_system' | 'individual' | 'mixed' | 'null', nullable, required: Echoes the caller's use_context declaration (null when not provided). Maryland-only in v1 — see the request field description.
    - `digital_content_type` 'ebook' | 'audio' | 'video' | 'art_image' | 'photograph' | 'printable_document' | 'software' | 'data' | 'other' | 'null', nullable: Echoes the caller's digital_content_type declaration (null when not provided). Consulted only for transaction_type digital_good — see the request field description and audit_trail.classification.digital_content_type_applied.
    - `classification_facts` object: Echoes the classification facts the caller declared (payment_provider_type, it_support_scope, includes_prewritten_software_access, custom.<attestation field>, maintenance.<contract field>, use_context); {} when none. Recorded with the transaction.
    - `counterparty_id` string, required
    - `network_profile` unknown
    - `sales_tax` object, nullable, required
      - `jurisdiction` string, required
      - `state` string, required
      - `rate` number, required
      - `amount` number, required
      - `type` string
      - `reason` string
      - `exemption` unknown
    - `use_tax` object, nullable, required
      - `jurisdiction` string, required
      - `state` string, required
      - `rate` number, required
      - `amount` number, required
      - `type` string
      - `reason` string
      - `exemption` unknown
    - `seller_remitting` object, nullable, required
      - `status` 'collected' | 'not_collected', required
      - `source` 'network_verified' | 'self_reported', required
    - `tracking_1099` object, nullable, required
      - `counterparty_id` string, required
      - `payment_this_transaction` number, required
      - `vendor_ytd_total` number, required
      - `threshold` number, required
      - `threshold_exceeded` boolean, required
      - `form_required` string, nullable, required
    - `exemption` unknown
    - `confidence` object, required
      - `score` number, required
      - `level` 'complete' | 'high' | 'partial' | 'minimal', required
      - `factors` string[], required
    - `advisories` object[], required
      - `type` string, required
      - `flagged` boolean
      - `code` string
      - `state` string
      - `advisory` string, required
      - `confidence` string
    - `routing` object[], required
      - `type` string, required
      - `amount` number, required
      - `destination` string, required
      - `jurisdiction` string, required
    - `total_tax` number, required: The tax YOU are responsible for on this transaction. On marketplace-seller calls in MPF states (collected_by_marketplace true) this EXCLUDES the tax the facilitator collects and remits — that amount is reported in marketplace_remitted_tax, not here, so reserve totals built from total_tax never include money the marketplace already remitted.
    - `nexus_configured` boolean, required: False when this account has never configured nexus states. A seller-role call from such an account returns total_tax 0 by DEFAULT, not by determination — read this before trusting a zero. See tax_if_nexus for the amount once nexus is set.
    - `classification_note` string, required
    - `disclaimer` string, required
    - `collected_by_marketplace` boolean, required: True when marketplace_role is "seller" and the buyer state has marketplace-facilitator law: the facilitator is the collector of record. When true, the tax due on the transaction appears in marketplace_remitted_tax and total_tax/routing report only your own obligation (0 for the facilitated sale itself).
    - `marketplace_remitted_tax` number: Marketplace-seller calls in MPF states only. Tax due on this transaction that the marketplace facilitator — the collector of record — collects and remits (e.g. RCW 82.08.0531(2)). Excluded from total_tax and routing: do not reserve or remit this amount yourself. Threshold counting is separate — see counts_toward_nexus_threshold.
    - `counts_toward_nexus_threshold` boolean: Marketplace-seller calls only. Whether this facilitated sale counts toward YOUR economic-nexus threshold in the buyer's state — a per-state rule, separate from who collects (the facilitator always does under MPF law). False only where a verified statute excludes facilitated sales (e.g. Virginia); conditional excluders (IL, PA) report true because the engine cannot verify the condition — the marketplace_facilitator advisory states the condition and authority.
    - `audit_trail` object
    - `nexus_alerts` unknown[]
      - unknown
    - `tax_if_nexus` object: Set only on seller-role calls that returned 0 solely because no nexus is configured. The hypothetical figure this transaction owes once nexus is registered for buyer_state. Never applied to total_tax.
      - `total_tax` number, required
      - `combined_rate` number, nullable, required
      - `basis` string, required
    - `entity_id` string, required
    - `mode` 'live' | 'x402' | 'mpp' | 'demo', required
    - `api_version` string, required
    - `b2b_detection` object
      - `is_b2b` boolean, required
      - `method` string, required
      - `counterparty_principal` string, nullable, required
      - `note` string, required
    - `upgrade` object: Present on x402/MPP responses; not set on api-key calls.
      - `message` string, required
      - `signup` unknown
      - `free_tier` string, required
    - `counterparty_notice` object: Set when the counterparty isn't on the AgentTax network.
      - `counterparty_id` string, required
      - `on_agenttax` false, required
      - `message` string, required
      - `forward_to_counterparty` unknown
  - CalculateDemoResponse
    - `success` true, required
    - `engine_version` string, required
    - `transaction_id` string, required
    - `timestamp` string, date-time, required
    - `mode` 'demo', required
    - `role` 'seller' | 'buyer', required
    - `amount` number, required
    - `buyer_state` string, required
    - `buyer_zip` string, nullable, required
    - `transaction_type` string, required
    - `work_type` string, nullable, required
    - `classification_basis` string, required
    - `is_b2b` boolean, required
    - `digital_content_type` 'ebook' | 'audio' | 'video' | 'art_image' | 'photograph' | 'printable_document' | 'software' | 'data' | 'other' | 'null', nullable
    - `classification_facts` object
    - `total_tax` number, required
    - `combined_rate` number, required
    - `confidence` object, required
      - `score` number, required
      - `level` string, required
    - `disclaimer` string, required
    - `upgrade` object, required
      - `message` string, required
      - `signup` unknown
      - `free_tier` string, required

## Other responses

- `400`: Validation failure — see `errors` array.
- `401`: Authentication required or invalid.
- `402`: x402 payment required. Response includes `PAYMENT-REQUIRED` header with quote.
- `429`: Rate limited.

---

[API](https://skmtc.dev/agenttax/apis/agenttax-api.md) · [All operations](https://skmtc.dev/agenttax/apis/agenttax-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agenttax/apis/agenttax-api/revisions/c4af8147c0cb?raw)