Transaction Structures Reference

Transaction Structures

Complete reference for AgentTax API request/response schemas, transaction types, and data models. Everything an AI agent needs to integrate.

How AgentTax Works

Step through the complete transaction flow — from agent request to tax calculation to payment settlement.

When your AI agent sells services, AgentTax calculates and routes the correct sales tax before settlement.

⚡ KEY: AgentTax never holds funds

1

Buyer Agent Calls Seller Agent

An external AI agent sends a purchase request to your seller agent's endpoint — product, amount, and buyer jurisdiction. Your agent responds with availability, pricing, and terms.

⚡

AgentTax is software, not a payment processor. Funds always flow through your existing payment rails (Stripe, bank transfers, smart contracts). AgentTax calculates obligations and instructs routing — it never holds, transfers, or escrows money.

Transaction Types

AgentTax classifies AI-to-AI transactions into 6 types. Each maps to a tax category that determines taxability per state.

🔌

API Access

Category: digital_service

"api_access"

Examples: OpenAI API calls, inference endpoints, model serving

Tax treatment: Taxable as a digital service in states that tax SaaS/digital services. Exempt in states that only tax tangible goods.

Request Schema

POST /api/v1/calculate — the core endpoint. Send one of these for every AI-to-AI transaction.

POST /api/v1/calculate

rolestringREQMust be "seller" or "buyer". Determines which tax obligations are returned.

amountnumberREQTransaction amount in USD. Must be positive.

buyer_statestringREQTwo-letter US state code of the buyer's jurisdiction (e.g. "TX", "CA"). Determines applicable tax rates.

transaction_typestringREQOne of: compute, api_access, data_purchase, saas, ai_labor, storage

counterparty_idstringREQUnique identifier for the other party. Used for 1099 tracking and network profile lookup.

Auth: Include X-API-Key: your_key header, or omit for demo mode (rate limited).

Live Request / Response

Select a transaction type above and toggle seller/buyer to see exactly what the API returns.

Type: API Access

Request

{
  "role": "seller",
  "amount": 2500.00,
  "buyer_state": "TX",
  "transaction_type": "api_access",
  "counterparty_id": "agent_buyer_001"
}

Response

{
  "success": true,
  "transaction_id": "txn_m3k8x_a7f2p1",
  "timestamp": "2026-02-25T14:30:00.000Z",
  "role": "seller",
  "amount": 2500.00,
  "buyer_state": "TX",
  "jurisdiction": "Texas",
  "transaction_type": "api_access",
  "transaction_category": "API Access",
  "counterparty_id": "agent_buyer_001",
  "sales_tax": {
    "jurisdiction": "Texas",
    "state": "TX",
    "rate": 0.0625,
    "amount": 156.25,
    "type": "Digital Services Tax",
    "reason": "Texas 6.25% rate applied to API Access."
  },
  "total_tax": 156.25,
  "routing": [
    {
      "type": "sales_tax",
      "amount": 156.25,
      "destination": "TX_tax_reserve",
      "jurisdiction": "Texas"
    }
  ],
  "exemption": null
}

Seller Response Fields

When role = 'seller', the response focuses on sales tax collection obligations.

sales_taxobjectThe sales tax calculation result

.jurisdictionstringState name (e.g. 'Texas')

.statestringTwo-letter state code

.ratenumberApplied tax rate (e.g. 0.0625)

.amountnumberTax amount in USD

.typestring'Digital Services Tax', 'Sales Tax', 'No Collection Obligation', or 'Exempt'

.reasonstringHuman-readable explanation

exemptionobject|nullIf exempt: type (no_nexus, buyer_certificate, digital_exempt), state, certificate info

routingarrayPayment split instructions — where to route tax amounts

[].typestring'sales_tax'

[].amountnumberAmount to route

[].destinationstringReserve account label (e.g. 'TX_tax_reserve')

total_taxnumberTotal tax across all jurisdictions

Buyer Response Fields

When role = 'buyer', the response covers use tax, seller verification, and 1099 tracking.

seller_remittingobjectWhether the seller collected and is remitting sales tax

.statusstring'collected' or 'not_collected'

.sourcestring'network_verified' or 'self_reported'

.detailstringExplanation

use_taxobjectUse tax obligation (if seller didn't collect)

.jurisdictionstringState name

.ratenumberUse tax rate

.amountnumberUse tax amount owed

.reasonstringExplanation

tracking_1099objectIRS 1099-NEC threshold tracking

.vendor_ytd_totalnumberCumulative payments to this vendor YTD

.thresholdnumber$2,000 federal threshold (OBBBA, TY 2026)

.threshold_exceededbooleanTrue if cumulative > $2,000

.form_requiredstring|null'1099-NEC' if threshold exceeded, null otherwise

routingarrayPayment routing — where to send use tax amounts

total_taxnumberTotal use tax owed

Exemption Types

Three ways a transaction can result in zero tax.

no_nexus

No Nexus

Seller has no nexus (physical presence or economic threshold) in the buyer's state. No obligation to collect.

Example: Seller is only in CA; buyer is in FL. No nexus in FL.

buyer_certificate

Buyer Exemption

Buyer has a valid exemption certificate on file — resale cert, nonprofit, government entity.

Example: Buyer has a resale certificate in CA. Tax exempt.

digital_exempt

Digital Exempt

The buyer's state does not tax digital services or SaaS. Transaction type matters.

Example: Buyer in CA purchasing SaaS. CA doesn't tax SaaS.

Supporting Endpoints

Beyond /calculate — the full AgentTax API surface.

GET/api/v1/ratesAll tax rates with sourcing metadata. No auth required.PUBLIC

GET/api/v1/rates?state=TXSingle state rate lookup with SaaS taxability note.PUBLIC

POST/api/v1/verifySubmit independently researched rates for comparison. AI verification.PUBLIC

GET/api/v1/providersActive rate provider, configuration status, upgrade path.PUBLIC

GET/api/v1/transactionsTransaction history with summary stats.AUTH

POST/api/v1/nexusRegister nexus in one or more states.AUTH

GET/api/v1/nexusGet current nexus configuration.AUTH

POST/api/v1/networkRegister or update AgentTax Network profile.AUTH

GET/api/v1/network?id=agent_xyzLook up counterparty network profiles.AUTH

GET/api/v1/healthHealth check and endpoint directory.PUBLIC

Data Model Overview

How AgentTax structures data internally.

🏢 Entity (Your Business)

{
  "entity_id": "novamind_ai",
  "entity_name": "NovaMind AI",
  "entity_state": "CA",
  "nexus_states": {
    "TX": { "hasNexus": true, "why": "Economic nexus — $500K+" },
    "CA": { "hasNexus": true, "why": "Physical presence" },
    "NY": { "hasNexus": true, "why": "Economic nexus — $500K+" }
  },
  "api_key": "atx_live_..."
}

🌐 Network Profile

{
  "agent_id": "agent_openai_research",
  "entity_name": "OpenAI Research Pool",
  "entity_state": "CA",
  "profile_type": "self_reported",
  "verified": false,
  "exemptions": [
    { "state": "CA", "type": "Resale Certificate" }
  ],
  "nexus_states": ["CA", "WA"],
  "remitting_status": true
}

📝 Transaction Record

{
  "transaction_id": "txn_m3k8x_a7f2p1",
  "timestamp": "2026-02-25T14:30:00Z",
  "role": "seller",
  "amount": 2500.00,
  "buyer_state": "TX",
  "transaction_type": "api_access",
  "counterparty_id": "agent_buyer_001",
  "total_tax": 156.25,
  "routing": [{ "type": "sales_tax", ... }]
}

💰 Tax Rate Entry

{
  "state": "TX",
  "rate": 0.0625,
  "digitalTaxable": true,
  "name": "Texas",
  "saasNote": "80% taxable as data processing",
  "source": "Tax Foundation (Jan 1, 2026)",
  "verified": "2026-02-25",
  "provider": "local"
}

Tax rates verified daily against Tax Foundation, Sales Tax Institute, state DOR websites, Anrok, TaxJar, TaxCloud, and Kintsugi · State-level rates only — local rates not included · © 2026 Agentic Tax Solutions