{"openapi":"3.1.0","info":{"title":"AgentTax API","version":"1.5.0","summary":"Tax intelligence for AI agents — sales tax, capital gains, nexus, 1099-DA","description":"REST API for calculating US sales tax on AI agent transactions across 51 jurisdictions. Supports x402 USDC settlement, MPP (Stripe Machine Payments), and traditional API-key auth. Daily rate verification, dual-axis economic-nexus monitoring, FIFO/LIFO/Specific-ID capital gains, IRS Form 1099-DA export.\n\nSee https://agenttax.io/api-docs for the full developer guide.","contact":{"name":"AgentTax Support","url":"https://agenttax.io","email":"support@agenttax.io"},"license":{"name":"Proprietary"},"x-engine-version":"1.5"},"servers":[{"url":"https://www.agenttax.io","description":"Production"}],"tags":[{"name":"Tax Calculation","description":"Per-transaction sales tax calculation."},{"name":"Capital Gains","description":"FIFO/LIFO/Specific-ID trade tracking + wash-sale detection."},{"name":"Nexus","description":"Economic-nexus configuration + threshold monitoring."},{"name":"Transactions","description":"Read-only transaction history."},{"name":"API Keys","description":"Key lifecycle."},{"name":"Auth","description":"Account creation, session management."},{"name":"Usage","description":"Tier-limit monitoring."},{"name":"Discovery","description":"API spec + machine-readable metadata."},{"name":"Network","description":"AgentTax Network profiles + public directory."},{"name":"Wallets","description":"Wallet linkage for x402 auto-attribution."},{"name":"Onboarding","description":"Personalized post-signup onboarding guide."},{"name":"Verification","description":"Cross-check rates submitted by external agents."},{"name":"Pricing","description":"Programmatic pricing contract."},{"name":"Rates","description":"Public state, local, and capital-gains rate tables."},{"name":"Export","description":"Tax-form exports (1099-DA draft for digital-asset gains)."},{"name":"Partners","description":"Partner integration surface — provisioning, usage, rev-share, inbound webhooks. Auth: `ptx_live_*` (provisioning key) or HMAC signature (webhook)."}],"externalDocs":{"description":"AgentTax Developer Guide","url":"https://agenttax.io/api-docs"},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"atx_live_<32 hex chars>","description":"Live API key obtained via signup at /api/v1/auth/signup. Sent as `Authorization: Bearer atx_live_…`. Rate-limited per tier."},"x402":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"Per-call USDC payment via x402 protocol. Pays $0.005 USDC on Base mainnet via the configured facilitator. No signup required."},"partnerProvisioningKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner provisioning key (`ptx_live_…`). Issued out-of-band when a partner is onboarded. Used by `/api/v1/partner/provision`, `/usage`, `/revshare`. Also accepted as `Authorization: Bearer ptx_live_…`. Rate-limited per partner."},"partnerWebhookSignature":{"type":"apiKey","in":"header","name":"X-AgentTax-Signature","description":"Inbound partner webhook authentication. Carries `t=<unix-seconds>,v1=<hex>` where v1 = HMAC-SHA256(shared_secret, raw_body). ±5-minute clock skew tolerance.\n\nMUST be sent alongside three additional headers (treated as part of the auth scheme):\n- `X-AgentTax-Partner`: partner slug (e.g. `invoica`)\n- `X-AgentTax-Nonce`: 8-128 char unique-per-request token (replay-rejected within tolerance window)\n- `X-AgentTax-Event`: event type (`user.created` | `user.deleted`)\n\nApplies only to `POST /api/v1/partner/webhook`. The other partner endpoints use `partnerProvisioningKey`."}},"schemas":{"ErrorCode":{"type":"string","enum":["INVALID_INPUT","INVALID_JSON_BODY","METHOD_NOT_ALLOWED","UNAUTHORIZED","FORBIDDEN","TIER_LIMIT_REACHED","PAYMENT_REQUIRED","RATE_LIMITED","IDEMPOTENCY_KEY_INVALID","IDEMPOTENCY_KEY_CONFLICT","RESOURCE_NOT_FOUND","RESOURCE_CONFLICT","NEXUS_NOT_REACHED","WEBHOOK_SIGNATURE_INVALID","DB_UNAVAILABLE","INTERNAL"],"description":"Machine-readable error code. SDKs branch on this instead of regex-matching `error`. Frozen 16-value enum — additions require an API version bump."},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"code":{"$ref":"#/components/schemas/ErrorCode"},"error":{"type":"string","description":"Human-readable error message. Not stable for programmatic use."},"request_id":{"type":"string","description":"Echoed request id. Quote this when escalating."},"errors":{"type":"array","items":{"type":"string"},"description":"Per-field validation errors."}},"required":["success","code","error","request_id"]},"State":{"type":"string","enum":["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"],"description":"Two-letter US state code (or DC)."},"CalculateRequest":{"type":"object","properties":{"role":{"type":"string","enum":["seller","buyer"],"default":"seller"},"amount":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":100000000,"description":"USD amount, greater than 0 up to $100M. Decimal strings are normalized to numbers."},"buyer_state":{"type":"string","enum":["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"],"description":"Two-letter US state code (or DC)."},"seller_state":{"type":"string","description":"Two-letter US state code (or empty string)."},"buyer_zip":{"type":"string","pattern":"^(\\d{5})?$","description":"5-digit US zip code (empty string allowed)."},"seller_zip":{"type":"string","pattern":"^(\\d{5})?$","description":"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":{"type":"string","enum":["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"],"default":"saas"},"work_type":{"type":"string","enum":["compute","research","information_service","content","consulting","trading","payment_processing","web_hosting","software_maintenance","it_support","custom_software"],"description":"Economic classification of the agent's work. Drives per-state taxability via the engine's TAXABILITY_MATRIX.\n\n- `compute` → data_processing (TX 80% rule applies)\n- `research` → information_service (AI-generated research output)\n- `information_service` → information_service (database/data-subscription products like Westlaw/LexisNexis)\n- `content` → digital_service (writing, media generation)\n- `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)\n- `trading` → financial_service (capital-gains-tracker primary)"},"counterparty_id":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9_\\-.:@]+$","description":"Round-trips to public /api/v1/network-feed. Allowlist: alphanumeric + `_-.:@` only."},"is_b2b":{"type":"boolean","description":"Triggers state-specific B2B exemptions (IA, MD split rate)."},"use_context":{"type":"string","enum":["enterprise_system","individual","mixed"],"description":"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":{"type":"string","enum":["ebook","audio","video","art_image","photograph","printable_document","software","data","other"],"description":"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":{"type":"string","enum":["bank","licensed_money_transmitter","card_network","processor_routing_to_bank_or_network","other"],"description":"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":{"type":"string","enum":["help_desk_advice","remote_repair_or_config","software_installation","monitoring","security_monitoring","managed_bundle"],"description":"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":{"type":"boolean","description":"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":{"type":"object","description":"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":{"type":"object","description":"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":{"type":"string","enum":["seller","facilitator","direct"],"default":"direct"},"description":{"type":"string","maxLength":1000,"default":""},"exemption_certificate":{"type":"string","maxLength":200},"nexus_override":{"type":"object","description":"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":{"type":"number","minimum":0,"description":"Demo/test mode: override 1099 vendor YTD accumulation for a single calculation. Finite, non-negative; decimal strings are normalized to numbers."},"seller_remitting":{"type":"boolean","description":"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."}},"required":["amount","buyer_state","counterparty_id"],"additionalProperties":false},"CalculateLiveResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"engine_version":{"type":"string","example":"1.5"},"transaction_id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"role":{"type":"string","enum":["seller","buyer"]},"amount":{"type":"number"},"buyer_state":{"type":"string"},"buyer_zip":{"type":["string","null"]},"seller_state":{"type":["string","null"]},"seller_zip":{"type":["string","null"]},"sourcing_rule":{"type":"string","enum":["origin","destination"]},"marketplace_role":{"type":"string"},"local_rate":{"type":"number"},"combined_rate":{"type":"number"},"jurisdiction":{"type":"string"},"transaction_type":{"type":"string"},"transaction_category":{"type":"string"},"work_type":{"type":["string","null"]},"work_type_label":{"type":["string","null"]},"classification_basis":{"type":"string"},"is_b2b":{"type":"boolean"},"use_context":{"type":["string","null"],"enum":["enterprise_system","individual","mixed",null],"description":"Echoes the caller's use_context declaration (null when not provided). Maryland-only in v1 — see the request field description."},"digital_content_type":{"type":["string","null"],"enum":["ebook","audio","video","art_image","photograph","printable_document","software","data","other",null],"description":"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":{"type":"object","additionalProperties":{},"description":"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":{"type":"string"},"network_profile":{},"sales_tax":{"type":["object","null"],"properties":{"jurisdiction":{"type":"string"},"state":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"number"},"type":{"type":"string"},"reason":{"type":"string"},"exemption":{}},"required":["jurisdiction","state","rate","amount"],"additionalProperties":{}},"use_tax":{"type":["object","null"],"properties":{"jurisdiction":{"type":"string"},"state":{"type":"string"},"rate":{"type":"number"},"amount":{"type":"number"},"type":{"type":"string"},"reason":{"type":"string"},"exemption":{}},"required":["jurisdiction","state","rate","amount"],"additionalProperties":{}},"seller_remitting":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["collected","not_collected"]},"source":{"type":"string","enum":["network_verified","self_reported"]}},"required":["status","source"]},"tracking_1099":{"type":["object","null"],"properties":{"counterparty_id":{"type":"string"},"payment_this_transaction":{"type":"number"},"vendor_ytd_total":{"type":"number"},"threshold":{"type":"number"},"threshold_exceeded":{"type":"boolean"},"form_required":{"type":["string","null"]}},"required":["counterparty_id","payment_this_transaction","vendor_ytd_total","threshold","threshold_exceeded","form_required"]},"exemption":{},"confidence":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100},"level":{"type":"string","enum":["complete","high","partial","minimal"]},"factors":{"type":"array","items":{"type":"string"}}},"required":["score","level","factors"]},"advisories":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"flagged":{"type":"boolean"},"code":{"type":"string"},"state":{"type":"string"},"advisory":{"type":"string"},"confidence":{"type":"string"}},"required":["type","advisory"],"additionalProperties":{}}},"routing":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"amount":{"type":"number"},"destination":{"type":"string"},"jurisdiction":{"type":"string"}},"required":["type","amount","destination","jurisdiction"]}},"total_tax":{"type":"number","description":"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":{"type":"boolean","description":"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":{"type":"string"},"disclaimer":{"type":"string"},"collected_by_marketplace":{"type":"boolean","description":"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":{"type":"number","description":"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":{"type":"boolean","description":"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":{"type":"object","additionalProperties":{}},"nexus_alerts":{"type":"array","items":{}},"tax_if_nexus":{"type":"object","properties":{"total_tax":{"type":"number"},"combined_rate":{"type":["number","null"]},"basis":{"type":"string"}},"required":["total_tax","combined_rate","basis"],"description":"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."},"entity_id":{"type":"string"},"mode":{"type":"string","enum":["live","x402","mpp","demo"]},"api_version":{"type":"string","example":"v2"},"b2b_detection":{"type":"object","properties":{"is_b2b":{"type":"boolean"},"method":{"type":"string"},"counterparty_principal":{"type":["string","null"]},"note":{"type":"string"}},"required":["is_b2b","method","counterparty_principal","note"]},"upgrade":{"type":"object","properties":{"message":{"type":"string"},"signup":{},"free_tier":{"type":"string"}},"required":["message","free_tier"],"description":"Present on x402/MPP responses; not set on api-key calls."},"counterparty_notice":{"type":"object","properties":{"counterparty_id":{"type":"string"},"on_agenttax":{"type":"boolean","enum":[false]},"message":{"type":"string"},"forward_to_counterparty":{}},"required":["counterparty_id","on_agenttax","message"],"description":"Set when the counterparty isn't on the AgentTax network."}},"required":["success","engine_version","transaction_id","timestamp","role","amount","buyer_state","buyer_zip","seller_state","seller_zip","sourcing_rule","marketplace_role","local_rate","combined_rate","jurisdiction","transaction_type","transaction_category","work_type","work_type_label","classification_basis","is_b2b","use_context","counterparty_id","sales_tax","use_tax","seller_remitting","tracking_1099","confidence","advisories","routing","total_tax","nexus_configured","classification_note","disclaimer","collected_by_marketplace","entity_id","mode","api_version"]},"CalculateDemoResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"engine_version":{"type":"string"},"transaction_id":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"mode":{"type":"string","enum":["demo"]},"role":{"type":"string","enum":["seller","buyer"]},"amount":{"type":"number"},"buyer_state":{"type":"string"},"buyer_zip":{"type":["string","null"]},"transaction_type":{"type":"string"},"work_type":{"type":["string","null"]},"classification_basis":{"type":"string"},"is_b2b":{"type":"boolean"},"digital_content_type":{"type":["string","null"],"enum":["ebook","audio","video","art_image","photograph","printable_document","software","data","other",null]},"classification_facts":{"type":"object","additionalProperties":{}},"total_tax":{"type":"number"},"combined_rate":{"type":"number"},"confidence":{"type":"object","properties":{"score":{"type":"number"},"level":{"type":"string"}},"required":["score","level"]},"disclaimer":{"type":"string"},"upgrade":{"type":"object","properties":{"message":{"type":"string"},"signup":{},"free_tier":{"type":"string"}},"required":["message","free_tier"]}},"required":["success","engine_version","transaction_id","timestamp","mode","role","amount","buyer_state","buyer_zip","transaction_type","work_type","classification_basis","is_b2b","total_tax","combined_rate","confidence","disclaimer","upgrade"]},"CalculateResponse":{"anyOf":[{"$ref":"#/components/schemas/CalculateLiveResponse"},{"$ref":"#/components/schemas/CalculateDemoResponse"}]},"TradeRequest":{"type":"object","properties":{"asset_symbol":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[A-Za-z0-9._\\-]{1,50}$","description":"Asset ticker — equity (AAPL), crypto (BTC), or token (COMPUTE-TOKEN). Auto-uppercased."},"trade_type":{"type":"string","enum":["buy","sell"]},"quantity":{"type":"number","exclusiveMinimum":0,"maximum":1000000000000},"price_per_unit":{"type":"number","minimum":0,"maximum":1000000000},"fee_amount":{"type":"number","minimum":0,"maximum":1000000000,"default":0},"trade_date":{"type":"string","format":"date-time","description":"ISO 8601 trade timestamp. Defaults to server time when omitted."},"accounting_method":{"type":"string","enum":["fifo","lifo","specific_id"],"default":"fifo"},"specific_lot_id":{"type":"string","nullable":true,"description":"Required when accounting_method='specific_id'. Identifies which cost-basis lot to consume."},"asset_name":{"type":"string","maxLength":200},"counterparty":{"type":"string","maxLength":200},"exchange":{"type":"string","maxLength":200},"notes":{"type":"string","maxLength":1000},"resident_state":{"type":"string","enum":["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"],"description":"Two-letter resident state code used for state capital-gains estimation."},"tax_entity_type":{"type":"string","enum":["individual","c_corp","pass_through"],"description":"Entity classification for federal estimation."},"filing_status":{"type":"string","enum":["single","mfj","mfs","hoh"],"description":"Federal filing status used to pick the income-tax / LT-capital-gains bracket."},"estimated_annual_income":{"type":"number","minimum":0,"description":"Estimated annual income; enables bracket-aware federal estimation and NIIT detection."},"asset_class":{"type":"string","enum":["stock","security","securities","equity","digital_asset","crypto"],"description":"Opt into IRC §1091 wash-sale tracking. 'stock'/'security'/'securities'/'equity' enable detection; 'digital_asset'/'crypto'/omitted disable it (digital assets are not subject to §1091 under current Treasury guidance)."}},"required":["asset_symbol","trade_type","quantity","price_per_unit"],"additionalProperties":false},"NexusRequest":{"type":"object","properties":{"nexus":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/NexusStateEntry"},"description":"State-code → { hasNexus, reason } map. Keys must be two-letter US state codes (DC included); lowercase is normalized to uppercase. MERGE semantics: only the states present in the map are written — states absent from the map are left unchanged, and an empty object is a no-op (it does NOT clear the footprint). To remove a state's assertion, send it with hasNexus:false."}},"required":["nexus"],"additionalProperties":false},"NexusStateEntry":{"type":"object","properties":{"hasNexus":{"type":"boolean"},"reason":{"type":"string","maxLength":500}},"required":["hasNexus"],"additionalProperties":false,"description":"Per-state nexus flag with optional human-readable reason (e.g. 'Warehouse in Sacramento' or 'Economic nexus >$500K')."},"SignupRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"agent_name":{"type":"string","minLength":1,"maxLength":200},"agent_description":{"type":"string","maxLength":2000},"agent_work_type":{"type":"string","enum":["compute","research","information_service","content","consulting","trading","payment_processing","web_hosting","software_maintenance","it_support","custom_software"]},"company_name":{"type":"string","maxLength":200},"state":{"type":"string","description":"Two-letter US state code (or empty string)."},"ein":{"type":"string","description":"9-digit US EIN. Stored AES-256-GCM encrypted at rest."},"est_volume":{"type":"string","maxLength":100},"join_network":{"type":"boolean"},"network_visibility":{"type":"string","enum":["public","private"]},"utm":{"$ref":"#/components/schemas/UtmAttribution"}},"required":["email","password","agent_name","agent_work_type"]},"UtmAttribution":{"type":"object","properties":{"utm_source":{"type":"string","maxLength":200},"utm_medium":{"type":"string","maxLength":200},"utm_campaign":{"type":"string","maxLength":200},"utm_content":{"type":"string","maxLength":200},"utm_term":{"type":"string","maxLength":200},"landing_page":{"type":"string","maxLength":500}}},"LoginRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},"CreateAgentRequest":{"type":"object","properties":{"agent_name":{"type":"string","minLength":1,"maxLength":200},"work_type":{"type":"string","enum":["compute","research","information_service","content","consulting","trading","payment_processing","web_hosting","software_maintenance","it_support","custom_software"],"default":"compute"},"description":{"type":"string","maxLength":2000}},"required":["agent_name"]},"IngestRecord":{"type":"object","properties":{"role":{"type":"string","enum":["seller","buyer"],"default":"seller"},"amount":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":100000000,"description":"USD amount, greater than 0 up to $100M. Decimal strings are normalized to numbers."},"buyer_state":{"type":"string","enum":["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"],"description":"Two-letter US state code (or DC)."},"seller_state":{"type":"string","description":"Two-letter US state code (or empty string)."},"buyer_zip":{"type":"string","pattern":"^(\\d{5})?$","description":"5-digit US zip code (empty string allowed)."},"seller_zip":{"type":"string","pattern":"^(\\d{5})?$","description":"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":{"type":"string","enum":["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"],"default":"saas"},"work_type":{"type":"string","enum":["compute","research","information_service","content","consulting","trading","payment_processing","web_hosting","software_maintenance","it_support","custom_software"],"description":"Economic classification of the agent's work. Drives per-state taxability via the engine's TAXABILITY_MATRIX.\n\n- `compute` → data_processing (TX 80% rule applies)\n- `research` → information_service (AI-generated research output)\n- `information_service` → information_service (database/data-subscription products like Westlaw/LexisNexis)\n- `content` → digital_service (writing, media generation)\n- `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)\n- `trading` → financial_service (capital-gains-tracker primary)"},"counterparty_id":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9_\\-.:@]+$","description":"Round-trips to public /api/v1/network-feed. Allowlist: alphanumeric + `_-.:@` only."},"is_b2b":{"type":"boolean","description":"Triggers state-specific B2B exemptions (IA, MD split rate)."},"use_context":{"type":"string","enum":["enterprise_system","individual","mixed"],"description":"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":{"type":"string","enum":["ebook","audio","video","art_image","photograph","printable_document","software","data","other"],"description":"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":{"type":"string","enum":["bank","licensed_money_transmitter","card_network","processor_routing_to_bank_or_network","other"],"description":"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":{"type":"string","enum":["help_desk_advice","remote_repair_or_config","software_installation","monitoring","security_monitoring","managed_bundle"],"description":"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":{"type":"boolean","description":"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":{"type":"object","description":"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":{"type":"object","description":"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":{"type":"string","enum":["seller","facilitator","direct"],"default":"direct"},"description":{"type":"string","maxLength":1000,"default":""},"exemption_certificate":{"type":"string","maxLength":200},"nexus_override":{"type":"object","description":"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":{"type":"number","minimum":0,"description":"Demo/test mode: override 1099 vendor YTD accumulation for a single calculation. Finite, non-negative; decimal strings are normalized to numbers."},"seller_remitting":{"type":"boolean","description":"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."},"external_tx_id":{"type":"string","description":"Caller-provided idempotency key. When present, a duplicate POST returns the original record with `duplicate: true` instead of writing twice."},"transaction_id":{"type":"string","description":"Optional caller reference. It is NOT used as the record id: the `transaction_id` in the response is always server-generated. When `external_tx_id` is absent, this value takes its place: it is stored and returned as `external_tx_id`, and a retry with the same value returns the stored record with `duplicate: true`. When both are sent, `external_tx_id` wins and this value is not stored."},"metadata":{"type":"object","description":"Free-form caller metadata. Stored as-is, not interpreted."}},"required":["amount","buyer_state","counterparty_id"],"additionalProperties":false},"IngestRequest":{"anyOf":[{"$ref":"#/components/schemas/IngestRecord"},{"type":"array","items":{"$ref":"#/components/schemas/IngestRecord"},"minItems":1,"maxItems":100}],"description":"One ingest record or an array of up to 100."},"ListTransactionsQuery":{"type":"object","properties":{"role":{"type":"string","enum":["seller","buyer"]},"state":{"type":"string","enum":["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"]},"since":{"type":"string","description":"ISO 8601 date or date-time lower bound (e.g. 2026-08-01 or 2026-08-01T00:00:00Z)."},"limit":{"type":"integer","minimum":1,"maximum":1000}}},"NetworkPrincipal":{"type":"object","properties":{"legal_name":{"type":"string","maxLength":200},"entity_type":{"type":"string","maxLength":20},"state_of_incorporation":{"type":"string","enum":["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"]},"ein_last4":{"type":"string","pattern":"^\\d{4}$","description":"Last 4 digits of EIN."},"contact_email":{"type":"string","maxLength":200,"format":"email"},"is_business":{"type":"boolean"}}},"NetworkProfileRequest":{"type":"object","properties":{"agent_id":{"type":"string","minLength":1,"maxLength":200},"entity_name":{"type":"string","minLength":1,"maxLength":200},"entity_state":{"type":"string","enum":["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"],"description":"Two-letter US state code."},"visibility":{"type":"string","enum":["public","private"],"default":"public"},"description":{"type":"string","maxLength":2000},"work_type":{"type":"string","enum":["compute","research","information_service","content","consulting","trading","payment_processing","web_hosting","software_maintenance","it_support","custom_software"]},"principal":{"$ref":"#/components/schemas/NetworkPrincipal"}},"required":["agent_id","entity_name","entity_state"]},"NetworkProfileQuery":{"type":"object","properties":{"agent_id":{"type":"string","description":"Agent ID to look up. Defaults to the authenticated entity's first profile when omitted."}}},"NetworkDirectoryQuery":{"type":"object","properties":{"agent_id":{"type":"string","description":"Specific agent lookup. When provided, returns one profile (404 if not found)."},"work_type":{"type":"string","enum":["compute","research","information_service","content","consulting","trading","payment_processing","web_hosting","software_maintenance","it_support","custom_software"],"description":"Filter by work_type. Invalid values are silently ignored (no 400)."},"search":{"type":"string","description":"ILIKE search across agent_name, entity_name, description."},"page":{"type":"integer","minimum":1,"default":1,"description":"1-based page index. 20 results per page."}}},"LinkWalletRequest":{"type":"object","properties":{"wallet_address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"0x-prefixed 40-char hex (Ethereum / Base address)."},"label":{"type":["string","null"],"maxLength":128},"chain":{"type":"string","default":"base","description":"Chain identifier (default \"base\")."}},"required":["wallet_address"]},"UnlinkWalletQuery":{"type":"object","properties":{"wallet_address":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"0x-prefixed 40-char hex (Ethereum / Base address)."}},"required":["wallet_address"]},"VerifyRateEntry":{"type":"object","properties":{"rate":{"type":"number","minimum":0,"maximum":1,"description":"Decimal rate (e.g. 0.0625 for 6.25%)."},"digitalTaxable":{"type":"boolean"}}},"VerifyRatesRequest":{"type":"object","properties":{"agent_id":{"type":"string","minLength":1,"maxLength":200},"source":{"type":"string","maxLength":500},"source_date":{"type":"string","description":"Free-form date label (e.g. \"2026-01-01\"). Echoed back; not parsed."},"rates":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/VerifyRateEntry"},"description":"Map of two-letter state code → submitted rate. Unknown codes return in `unknown` array; mismatches return in `discrepancies`."}},"required":["agent_id","rates"]},"PricingTier":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"price_usd_monthly":{"type":["number","null"]},"monthly_calls_included":{"type":["number","null"]},"overage_usd_per_call":{"type":["number","null"]},"overage_policy":{"type":"string","enum":["hard_cutoff","meter","custom"]},"features":{"type":"array","items":{"type":"string"}},"stripe_price_id":{"type":["string","null"]},"contact":{"type":"string"}},"required":["id","name","price_usd_monthly","monthly_calls_included","overage_usd_per_call","overage_policy","features","stripe_price_id"]},"PricingPayPerCall":{"type":"object","properties":{"id":{"type":"string","enum":["x402"]},"name":{"type":"string"},"price_usd_per_call":{"type":"number"},"network":{"type":"string"},"payee":{"type":["string","null"]},"facilitator":{"type":"string"},"notes":{"type":"string"}},"required":["id","name","price_usd_per_call","network","payee","facilitator","notes"]},"PricingResponse":{"type":"object","properties":{"schema_version":{"type":"string","example":"1.0.0"},"updated_at":{"type":"string","description":"ISO date the contract was last revised."},"currency":{"type":"string","enum":["USD"]},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/PricingTier"}},"pay_per_call":{"$ref":"#/components/schemas/PricingPayPerCall"},"billing_provider":{"type":"string","enum":["stripe"]},"docs":{"type":"string"}},"required":["schema_version","updated_at","currency","tiers","pay_per_call","billing_provider","docs"]},"RatesQuery":{"type":"object","properties":{"state":{"type":"string","enum":["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"],"description":"Two-letter US state code. When provided, returns one state instead of the full table."},"format":{"type":"string","enum":["compact","verified"],"description":"compact = `{state: {r, d}}`; verified = full per-state verification metadata."},"explain":{"type":"string","enum":["true","false"],"description":"When `state=` is set, adds an `explanation` block (rate reason, taxability, confidence reason)."}}},"RatesLocalQuery":{"type":"object","properties":{"zip":{"type":"string","pattern":"^\\d{5}$","description":"5-digit US zip code."}},"required":["zip"]},"RatesCapitalGainsQuery":{"type":"object","properties":{"state":{"type":"string","enum":["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"],"description":"Two-letter US state code (or DC)."},"format":{"type":"string","enum":["compact"],"description":"compact = `{state: {st, lt, t}}`. Default is full per-state."},"explain":{"type":"string","enum":["true","false"],"description":"When `state=` is set, adds an `explanation` block."}}},"BlogQuery":{"type":"object","properties":{"slug":{"type":"string","description":"Article slug (filename without .md). When supplied, returns one article instead of the index."},"category":{"type":"string","description":"Case-insensitive substring match on the article's category frontmatter field."}}},"ExportFormDaQuery":{"type":"object","properties":{"year":{"type":"integer","minimum":2020,"maximum":2030,"description":"Tax year. Defaults to the current year when omitted."}}},"CreateApiKeyRequest":{"type":"object","properties":{"name":{"type":"string","default":"Default","description":"Human-readable label shown alongside the key prefix in the dashboard."},"type":{"type":"string","enum":["live","test"],"default":"live"}}},"RevokeApiKeyRequest":{"type":"object","properties":{"prefix":{"type":"string","description":"Key prefix to revoke (the first 16 chars of the original key)."}},"required":["prefix"]},"PartnerProvisionRequest":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":256,"description":"Partner-side stable identifier for the user. Idempotency key — repeat calls with the same `external_id` return the existing account without rotating credentials.","example":"invoica_user_42"},"email":{"type":"string","format":"email","example":"user@example.com"},"display_name":{"type":"string","maxLength":200}},"required":["external_id"]},"PartnerProvisionResponse":{"type":"object","properties":{"agenttax_account_id":{"type":"string"},"partner_user_id":{"type":"string"},"api_key":{"type":"string","description":"Returned ONLY on first provision (HTTP 201). Subsequent calls with the same `external_id` return 200 without `api_key`. Store securely — cannot be retrieved later, only rotated."},"claim_url":{"type":"string","format":"uri","description":"User-facing claim link. Allows the end-user to take over the account directly with AgentTax. Returned only on first provision."},"claim_expires_at":{"type":"string","format":"date-time","example":"2026-04-01T00:00:00Z"},"already_provisioned":{"type":"boolean","description":"true on repeat calls (HTTP 200), false on first provision (HTTP 201)."},"claimed":{"type":"boolean","description":"true if the user has claimed the account directly with AgentTax."}},"required":["agenttax_account_id","partner_user_id","already_provisioned"]},"PartnerUsageResponse":{"type":"object","properties":{"partner":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"}},"required":["id","slug"]},"period":{"type":"object","properties":{"from":{"type":"string","format":"date-time","example":"2026-04-01T00:00:00Z"},"to":{"type":"string","format":"date-time","example":"2026-04-01T00:00:00Z"}},"required":["from","to"]},"totals":{"type":"object","properties":{"calls":{"type":"integer"},"free_tier_calls":{"type":"integer"},"billable_calls":{"type":"integer"},"wholesale_cost_usd":{"type":"string","description":"USD as a fixed-precision decimal string. Avoid float math in clients.","example":"12.3400"},"total_users":{"type":"integer"}},"required":["calls","free_tier_calls","billable_calls","wholesale_cost_usd","total_users"]},"per_user":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"partner_user_id":{"type":"string"},"calls":{"type":"integer"},"free":{"type":"integer"},"billable":{"type":"integer"},"cost_usd":{"type":"string","description":"USD as a fixed-precision decimal string. Avoid float math in clients.","example":"12.3400"}},"required":["external_id","partner_user_id","calls","free","billable","cost_usd"]}},"pagination":{"type":"object","properties":{"per_user_returned":{"type":"integer"},"per_user_cap":{"type":"integer","description":"Hard limit; defaults to 5000.","example":5000},"truncated":{"type":"boolean"},"truncation_note":{"type":["string","null"]}},"required":["per_user_returned","per_user_cap","truncated","truncation_note"]}},"required":["partner","period","totals","per_user","pagination"]},"PartnerRevshareResponse":{"type":"object","properties":{"partner":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"revshare_pct":{"type":"number"},"revshare_triggered_at":{"type":["string","null"],"format":"date-time","example":"2026-04-01T00:00:00Z"}},"required":["id","slug","revshare_pct","revshare_triggered_at"]},"period":{"type":"object","properties":{"from":{"type":"string","format":"date-time","example":"2026-04-01T00:00:00Z"},"to":{"type":"string","format":"date-time","example":"2026-04-01T00:00:00Z"}},"required":["from","to"]},"totals":{"type":"object","properties":{"attributed_entities":{"type":"integer"},"attributed_mrr_usd":{"type":"string","description":"USD as a fixed-precision decimal string. Avoid float math in clients.","example":"12.3400"},"payout_usd":{"type":"string","description":"USD as a fixed-precision decimal string. Avoid float math in clients.","example":"12.3400"}},"required":["attributed_entities","attributed_mrr_usd","payout_usd"]},"per_entity":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"partner_user_id":{"type":"string"},"entity_id":{"type":"string"},"revshare_pct":{"type":"number","example":0.1,"description":"Locked at first upgrade. Forward-looking only."},"mrr_usd":{"type":"string","description":"USD as a fixed-precision decimal string. Avoid float math in clients.","example":"12.3400"},"payout_usd":{"type":"string","description":"USD as a fixed-precision decimal string. Avoid float math in clients.","example":"12.3400"},"window_ends_at":{"type":"string","format":"date-time","example":"2026-04-01T00:00:00Z","description":"first_upgrade_at + 12 months. Attribution stops contributing to payouts after this date."}},"required":["external_id","partner_user_id","entity_id","revshare_pct","mrr_usd","payout_usd","window_ends_at"]}}},"required":["partner","period","totals","per_entity"]},"PartnerWebhookUserCreatedBody":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":256},"email":{"type":"string","format":"email"},"display_name":{"type":"string","maxLength":200}},"required":["external_id"]},"PartnerWebhookUserDeletedBody":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":256}},"required":["external_id"]},"PartnerWebhookRequest":{"anyOf":[{"$ref":"#/components/schemas/PartnerWebhookUserCreatedBody"},{"$ref":"#/components/schemas/PartnerWebhookUserDeletedBody"}]},"PartnerWebhookResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"event":{"type":"string","enum":["user.created","user.deleted"],"description":"Inbound event type. Carried in `X-AgentTax-Event` header. Body is event-specific; see request schemas below."},"partner_user_id":{"type":"string"},"agenttax_account_id":{"type":"string"},"already_provisioned":{"type":"boolean"},"found":{"type":"boolean"},"already_deleted":{"type":"boolean"},"entity_id":{"type":"string"}},"required":["ok","event"]}},"parameters":{}},"paths":{"/api/v1/calculate":{"post":{"operationId":"calculateTax","summary":"Calculate sales tax for an agent transaction","description":"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.\n\nAuthentication: 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.","tags":["Tax Calculation"],"security":[{"apiKey":[]},{"x402":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateRequest"},"examples":{"NJ SaaS (exempt post-merge per TB-72)":{"value":{"role":"seller","amount":1000,"buyer_state":"NJ","transaction_type":"saas","work_type":"content","counterparty_id":"agent_acme_42"}},"NJ database subscription (taxable as info service)":{"value":{"role":"seller","amount":1000,"buyer_state":"NJ","transaction_type":"saas","work_type":"information_service","counterparty_id":"agent_westlaw_clone"}},"MD declared-solely-enterprise SaaS (3%, declaration-recorded)":{"value":{"role":"seller","amount":1000,"buyer_state":"MD","transaction_type":"saas","is_b2b":true,"use_context":"enterprise_system","counterparty_id":"agent_enterprise_buyer"}},"MD declared-not-solely SaaS (6% despite is_b2b, TB-56 higher-rate mandate)":{"value":{"role":"seller","amount":1000,"buyer_state":"MD","transaction_type":"saas","is_b2b":true,"use_context":"individual","counterparty_id":"agent_mixed_use_buyer"}},"Printable PDF planner declared as printable_document (digital_good)":{"value":{"role":"seller","amount":12,"buyer_state":"MN","buyer_zip":"55401","transaction_type":"digital_good","digital_content_type":"printable_document","counterparty_id":"shop_buyer_7"}},"Downloaded photograph declared as photograph (digital_good)":{"value":{"role":"seller","amount":8,"buyer_state":"NC","buyer_zip":"27601","transaction_type":"digital_good","digital_content_type":"photograph","counterparty_id":"shop_buyer_8"}},"TX intrastate compute with origin sourcing":{"value":{"role":"seller","amount":500,"buyer_state":"TX","seller_state":"TX","seller_zip":"78701","buyer_zip":"75001","transaction_type":"compute","work_type":"compute","counterparty_id":"agent_dallas_buyer"}}}}}},"responses":{"200":{"description":"Tax calculation succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateResponse"}}}},"400":{"description":"Validation failure — see `errors` array.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"x402 payment required. Response includes `PAYMENT-REQUIRED` header with quote."},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/trades":{"post":{"operationId":"logTrade","summary":"Log a capital-gains trade","description":"Records a buy/sell with FIFO/LIFO/Specific-ID cost basis. Wash-sale detection runs automatically (api/_lib/wash-sale.js). Also discoverable via x402 (POST without auth + X-PAYMENT header returns a preview without writing).","tags":["Capital Gains"],"security":[{"apiKey":[]},{"x402":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TradeRequest"}}}},"responses":{"200":{"description":"Trade logged with realized gain/loss if SELL."},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required"},"402":{"description":"x402 payment required for unauthenticated callers"}}},"get":{"operationId":"listTrades","summary":"List trades for the authenticated entity","tags":["Capital Gains"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Trade history."},"401":{"description":"Authentication required"}}}},"/api/v1/nexus":{"post":{"operationId":"configureNexus","summary":"Configure economic-nexus footprint","description":"Sets the states the entity collects/reports tax in. Used by the daily nexus-monitor to compute approaching-threshold alerts (80% of revenue OR 200 tx).","tags":["Nexus"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NexusRequest"}}}},"responses":{"200":{"description":"Nexus footprint updated."},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required"}}}},"/api/v1/auth/signup":{"post":{"operationId":"signup","summary":"Create an AgentTax account + agent","description":"Creates an entity, an agent, and an API key in one call. Returns the API key once — save it. Cookie-based session also issued (HttpOnly atx_session + readable atx_csrf).","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}}},"responses":{"201":{"description":"Account created.","headers":{"Set-Cookie":{"description":"atx_session (HttpOnly, Secure, SameSite=Lax) + atx_csrf (readable)","schema":{"type":"string"}}}},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Email already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"EIN provided but encryption misconfigured (fail-closed)"}}}},"/api/v1/auth/login":{"post":{"operationId":"login","summary":"Authenticate with email + password","description":"Returns a session token + Sets atx_session (HttpOnly) + atx_csrf cookies. argon2id password hashing with legacy PBKDF2 dual-read for older accounts. Account-lockout after 5 consecutive failures.","tags":["Auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Login succeeded — session cookie set."},"401":{"description":"Invalid email or password"},"429":{"description":"Account locked — Retry-After header indicates cooldown seconds"}}}},"/api/v1/auth/logout":{"post":{"operationId":"logout","summary":"End the current session","description":"Clears atx_session + atx_csrf cookies and deletes the session row. CSRF-protected on cookie-authenticated requests.","tags":["Auth"],"responses":{"200":{"description":"Logged out (idempotent — always returns 200 to avoid leaking session validity)."},"403":{"description":"CSRF verification failed"}}}},"/api/v1/auth/me":{"get":{"operationId":"me","summary":"Hydrate the dashboard for the authenticated user","description":"Returns the entity, organization, agents, network profiles, API keys (prefixes only), monthly usage, tier limits, recent transactions, recent trades, and current-year gains summary.","tags":["Auth"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Account snapshot."},"401":{"description":"Missing or invalid session"}}}},"/api/v1/auth/agents":{"post":{"operationId":"createAgent","summary":"Add an agent to the authenticated entity","description":"Creates an additional agent under the calling entity. Requires a session (cookie or Bearer). CSRF-protected when the session was carried by a cookie.","tags":["Auth"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentRequest"}}}},"responses":{"201":{"description":"Agent created."},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required"},"403":{"description":"CSRF verification failed (cookie sessions only)"}}}},"/api/v1/transactions/ingest":{"post":{"operationId":"ingestTransactions","summary":"Bulk-log x402 purchases into transaction history","description":"Authenticated bulk endpoint for agents that buy from third-party x402 sellers and want the resulting transactions in their AgentTax history with one call. Accepts a single record or array (max 100). Idempotent on (entity_id, external_tx_id) when provided.\n\nReturns 201 if all records ingest cleanly, 207 if some succeed and some fail (partial), 400 if every record fails.","tags":["Transactions"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRequest"}}}},"responses":{"201":{"description":"All records ingested."},"207":{"description":"Partial success — some records ingested, some failed (`results` + `errors` arrays)."},"400":{"description":"All records failed validation, batch size exceeded, or empty body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required (demo mode rejected).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/transactions":{"get":{"operationId":"listTransactions","summary":"List the authenticated entity's transactions","description":"Paginated transaction history with optional `role`, `state`, `since`, `limit` query params. Returns running summary (seller_count, buyer_count, total_taxable, total_tax_collected).","tags":["Transactions"],"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["seller","buyer"]},"required":false,"name":"role","in":"query"},{"schema":{"type":"string","enum":["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":false,"name":"state","in":"query"},{"schema":{"type":"string","description":"ISO 8601 date or date-time lower bound (e.g. 2026-08-01 or 2026-08-01T00:00:00Z)."},"required":false,"description":"ISO 8601 date or date-time lower bound (e.g. 2026-08-01 or 2026-08-01T00:00:00Z).","name":"since","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Transaction list with summary."},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/network":{"post":{"operationId":"createOrUpdateNetworkProfile","summary":"Create or update an agent's AgentTax Network profile","description":"Upserts a network profile keyed on agent_id. IDOR-safe — the supplied agent_id must be owned by the authenticated entity. Public profiles surface in /api/v1/network-directory; private profiles are visible only to the owner.","tags":["Network"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkProfileRequest"}}}},"responses":{"200":{"description":"Profile created or updated."},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent not found or not owned by caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"getNetworkProfile","summary":"Get the authenticated entity's network profile","description":"Returns the profile for the supplied agent_id (when caller owns it) or for the authenticated entity. Private profiles owned by other entities return 404 (not 403) so existence isn't leaked.","tags":["Network"],"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Agent ID to look up. Defaults to the authenticated entity's first profile when omitted."},"required":false,"description":"Agent ID to look up. Defaults to the authenticated entity's first profile when omitted.","name":"agent_id","in":"query"}],"responses":{"200":{"description":"Profile snapshot."},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No profile found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/network-directory":{"get":{"operationId":"browseNetworkDirectory","summary":"Browse the public AgentTax Network directory","description":"Public, no auth required. Returns paginated public profiles with optional filters. Private profiles return a slimmed snapshot (id + verified + remitting_status only).","tags":["Network"],"parameters":[{"schema":{"type":"string","description":"Specific agent lookup. When provided, returns one profile (404 if not found)."},"required":false,"description":"Specific agent lookup. When provided, returns one profile (404 if not found).","name":"agent_id","in":"query"},{"schema":{"type":"string","enum":["compute","research","information_service","content","consulting","trading","payment_processing","web_hosting","software_maintenance","it_support","custom_software"],"description":"Filter by work_type. Invalid values are silently ignored (no 400)."},"required":false,"description":"Filter by work_type. Invalid values are silently ignored (no 400).","name":"work_type","in":"query"},{"schema":{"type":"string","description":"ILIKE search across agent_name, entity_name, description."},"required":false,"description":"ILIKE search across agent_name, entity_name, description.","name":"search","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"1-based page index. 20 results per page."},"required":false,"description":"1-based page index. 20 results per page.","name":"page","in":"query"}],"responses":{"200":{"description":"Paginated directory listing."},"404":{"description":"agent_id provided but no matching profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/wallets":{"post":{"operationId":"linkWallet","summary":"Link a wallet to the authenticated entity","description":"Records that the calling entity owns the supplied wallet. Future x402 payments from this wallet to /calculate or /trades will auto-log against the entity. **Session auth only** — API keys are rejected with 403 SESSION_AUTH_REQUIRED until ECDSA signed-message proof ships in V2.","tags":["Wallets"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkWalletRequest"}}}},"responses":{"201":{"description":"Wallet linked."},"400":{"description":"Validation failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Session auth required (API key rejected for wallet writes).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Wallet already linked to a different entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listWallets","summary":"List wallets linked to the authenticated entity","tags":["Wallets"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Wallet list."},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"unlinkWallet","summary":"Unlink a wallet from the authenticated entity","description":"Removes the link between the wallet and the entity. Session auth only (same V1 guardrail as linking).","tags":["Wallets"],"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"0x-prefixed 40-char hex (Ethereum / Base address)."},"required":true,"description":"0x-prefixed 40-char hex (Ethereum / Base address).","name":"wallet_address","in":"query"}],"responses":{"200":{"description":"Wallet unlinked."},"400":{"description":"Validation failure (missing or malformed wallet_address).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Session auth required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Wallet not linked to caller's entity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/onboarding":{"get":{"operationId":"getOnboardingGuide","summary":"Personalized post-signup onboarding guide","description":"Returns numbered onboarding steps with code examples (curl/javascript/python) pre-filled with the caller's API key + work-type-appropriate transaction. Includes progress flags (first_call_made, nexus_configured) derived from DB state. Demo mode (no auth) returns a generic guide with placeholder credentials.","tags":["Onboarding"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Onboarding guide payload."},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/verify":{"post":{"operationId":"verifyRates","summary":"Cross-check submitted state sales-tax rates against the engine","description":"Public, no-auth verification endpoint. Submit a set of state→rate entries; the response classifies each as match / discrepancy / unknown and returns an accuracy score. Rates come from tax-engine.js (canonical), so the comparison stays in sync with whatever the engine currently uses.","tags":["Verification"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRatesRequest"}}}},"responses":{"200":{"description":"Comparison report with summary, discrepancies, matches, unknown."},"400":{"description":"Validation failure (missing agent_id or empty/malformed rates).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/pricing":{"get":{"operationId":"getPricing","summary":"Structured pricing contract for programmatic callers","description":"Stable, versioned JSON contract. Agents can poll this to compute cost/margin before selecting a tier. `schema_version` follows semver — additive changes bump minor; breaking changes bump major and ship with a migration window.","tags":["Pricing"],"responses":{"200":{"description":"Pricing contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingResponse"}}}},"405":{"description":"Method not allowed (GET only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/rates":{"get":{"operationId":"listStateRates","summary":"Transparent state sales-tax rate data with verification","description":"Public, no-auth read of the engine's TAX_RATES table. Adds saasNotes, confidence scoring, and source attribution on top of the raw rate values. State-level only — combined local rates are at /api/v1/rates/local.","tags":["Rates"],"parameters":[{"schema":{"type":"string","enum":["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"],"description":"Two-letter US state code. When provided, returns one state instead of the full table."},"required":false,"description":"Two-letter US state code. When provided, returns one state instead of the full table.","name":"state","in":"query"},{"schema":{"type":"string","enum":["compact","verified"],"description":"compact = `{state: {r, d}}`; verified = full per-state verification metadata."},"required":false,"description":"compact = `{state: {r, d}}`; verified = full per-state verification metadata.","name":"format","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"When `state=` is set, adds an `explanation` block (rate reason, taxability, confidence reason)."},"required":false,"description":"When `state=` is set, adds an `explanation` block (rate reason, taxability, confidence reason).","name":"explain","in":"query"}],"responses":{"200":{"description":"Rate table or single-state record."},"404":{"description":"Unknown state code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/rates/local":{"get":{"operationId":"lookupLocalRate","summary":"Combined state + local rate lookup by zip code","description":"Returns the combined sales tax rate for a US zip code, broken down into state + local components, with self-administered locality flags (e.g. CO home-rule cities). Public; no auth required.","tags":["Rates"],"parameters":[{"schema":{"type":"string","pattern":"^\\d{5}$","description":"5-digit US zip code."},"required":true,"description":"5-digit US zip code.","name":"zip","in":"query"}],"responses":{"200":{"description":"Combined rate breakdown."},"400":{"description":"Missing or malformed zip param.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Zip not in the local rate table.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/rates/capital-gains":{"get":{"operationId":"listCapitalGainsRates","summary":"State capital-gains rates (short + long term)","description":"Public read of STATE_CAPITAL_GAINS with confidence scoring, federal-rate context, and per-state caveats for nuanced regimes (MA split, OK 5-year deduction, AR 50% LT exclusion, etc.).","tags":["Rates"],"parameters":[{"schema":{"type":"string","enum":["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"],"description":"Two-letter US state code (or DC)."},"required":false,"description":"Two-letter US state code (or DC).","name":"state","in":"query"},{"schema":{"type":"string","enum":["compact"],"description":"compact = `{state: {st, lt, t}}`. Default is full per-state."},"required":false,"description":"compact = `{state: {st, lt, t}}`. Default is full per-state.","name":"format","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"When `state=` is set, adds an `explanation` block."},"required":false,"description":"When `state=` is set, adds an `explanation` block.","name":"explain","in":"query"}],"responses":{"200":{"description":"Capital-gains table or single-state record."},"404":{"description":"Unknown state code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/blog":{"get":{"operationId":"listOrGetBlogArticle","summary":"Blog index or single article","description":"Public, cached for 5 minutes browser / 10 minutes CDN. Returns the article index by default, or a single article (with body) when `slug` is supplied.","tags":["Discovery"],"parameters":[{"schema":{"type":"string","description":"Article slug (filename without .md). When supplied, returns one article instead of the index."},"required":false,"description":"Article slug (filename without .md). When supplied, returns one article instead of the index.","name":"slug","in":"query"},{"schema":{"type":"string","description":"Case-insensitive substring match on the article's category frontmatter field."},"required":false,"description":"Case-insensitive substring match on the article's category frontmatter field.","name":"category","in":"query"}],"responses":{"200":{"description":"Article list, filtered list, or single article."},"404":{"description":"slug provided but no matching article.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/agents":{"get":{"operationId":"getAgentsGuide","summary":"Fetch the AGENTS.md integration guide","description":"Returns AgentTax's AGENTS.md as `text/markdown`. Designed for AI-agent discovery (Cursor, Codex, Jules, Claude Code) — they fetch this URL to learn how to integrate the API. HEAD is supported for content-length probing.","tags":["Discovery"],"responses":{"200":{"description":"AGENTS.md content.","content":{"text/markdown":{"schema":{"type":"string"}}}},"500":{"description":"AGENTS.md not bundled with the deploy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/export/1099-da":{"get":{"operationId":"exportForm1099Da","summary":"Draft IRS Form 1099-DA export for realized digital-asset gains","description":"Returns a JSON payload mirroring the 2026 draft Form 1099-DA box layout — payer + recipient blocks, per-trade transaction lines (box_1a through box_5), and short/long-term summary. Auth required (API key). DRAFT — wash-sale adjustments not yet included; field layout will move to the IRS final regs (T.D. 10000) before TY2026 filings.","tags":["Export"],"security":[{"apiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":2020,"maximum":2030,"description":"Tax year. Defaults to the current year when omitted."},"required":false,"description":"Tax year. Defaults to the current year when omitted.","name":"year","in":"query"}],"responses":{"200":{"description":"1099-DA draft payload with summary."},"400":{"description":"year out of supported range (2020-2030).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error generating export.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/keys":{"post":{"operationId":"createApiKey","summary":"Create an API key","description":"Returns the raw key ONCE in the response — save it. Hashed with API_KEY_HMAC_KEY pepper before storage; a DB leak is useless without the server-side pepper (Wave 5.8).","tags":["API Keys"],"security":[{"apiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"Key created — `key` field is shown once and never again."},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listApiKeys","summary":"List API keys (prefixes only)","tags":["API Keys"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Key prefixes + metadata; full keys never returned post-creation."},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key by prefix","tags":["API Keys"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeApiKeyRequest"}}}},"responses":{"200":{"description":"Key revoked (or `revoked: false` if no matching key)."},"400":{"description":"Missing prefix in body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/usage":{"get":{"operationId":"getUsage","summary":"Current monthly usage for the authenticated entity","description":"Returns calls-this-month and percent-of-tier-limit per product, plus an upgrade_prompt block when the entity is at or approaching its tier limit. Demo mode returns a free-tier stub with usage: 0.","tags":["Usage"],"security":[{"apiKey":[]},{}],"responses":{"200":{"description":"Usage summary."},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/partner/provision":{"post":{"operationId":"partnerProvision","summary":"Provision a partner-linked AgentTax account","description":"Creates a linked AgentTax account on behalf of a partner-tenant user and returns a scoped API key. **Idempotent on `(partner_id, external_id)`** — repeat calls return the existing account without rotating credentials.\n\n**Auth:** Partner provisioning key (`ptx_live_…`) sent as `X-API-Key` or `Authorization: Bearer`.\n\n**Rate limit:** 600/min per partner key.","tags":["Partners"],"security":[{"partnerProvisioningKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerProvisionRequest"},"examples":{"minimal":{"value":{"external_id":"invoica_user_42"}},"with email + display name":{"value":{"external_id":"invoica_user_42","email":"user@example.com","display_name":"Acme AI"}}}}}},"responses":{"200":{"description":"Account already provisioned. `api_key` and `claim_url` are NOT returned — those are first-call only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerProvisionResponse"}}}},"201":{"description":"New account created. `api_key` is returned ONCE — store securely.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerProvisionResponse"}}}},"400":{"description":"Missing or invalid `external_id` / `email`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid partner provisioning key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited (600/min per partner key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Provisioning failed (DB or downstream).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/partner/usage":{"get":{"operationId":"partnerUsage","summary":"Aggregated wholesale usage for a date range","description":"Per-user call counts + wholesale cost for the given period. Used by partners to reconcile their monthly invoice.\n\nDefault period: current calendar month. `per_user` array is capped at 5000 rows ordered by cost descending — `pagination.truncated` flags when totals exceed that. Totals row is unaffected by truncation.\n\n**Auth:** `ptx_live_…` provisioning key. **Rate limit:** 30/min per partner key.","tags":["Partners"],"security":[{"partnerProvisioningKey":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"ISO date-time. Defaults to start of current calendar month (usage) / previous month (revshare)."},"required":false,"description":"ISO date-time. Defaults to start of current calendar month (usage) / previous month (revshare).","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO date-time. Must be after `from`. Exclusive upper bound."},"required":false,"description":"ISO date-time. Must be after `from`. Exclusive upper bound.","name":"to","in":"query"}],"responses":{"200":{"description":"Aggregated usage and per-user breakdown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerUsageResponse"}}}},"400":{"description":"Invalid date range (`to` must be after `from`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid partner provisioning key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Database unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/partner/revshare":{"get":{"operationId":"partnerRevshare","summary":"Rev-share attribution + payout reconciliation","description":"Joins partner_revshare_attributions (who qualifies, with locked rev-share %) against entity_mrr_snapshots (Stripe-sourced) to compute payouts for the period.\n\nDefault period: previous calendar month. If no MRR snapshots exist for the period (Stripe webhook not wired yet), payouts come back as 0 with the attribution list still populated for audit.\n\n**Auth:** `ptx_live_…` provisioning key. **Rate limit:** 30/min per partner key.","tags":["Partners"],"security":[{"partnerProvisioningKey":[]}],"parameters":[{"schema":{"type":"string","format":"date-time","description":"ISO date-time. Defaults to start of current calendar month (usage) / previous month (revshare)."},"required":false,"description":"ISO date-time. Defaults to start of current calendar month (usage) / previous month (revshare).","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"ISO date-time. Must be after `from`. Exclusive upper bound."},"required":false,"description":"ISO date-time. Must be after `from`. Exclusive upper bound.","name":"to","in":"query"}],"responses":{"200":{"description":"Attribution list + computed payouts. Sorted by payout descending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerRevshareResponse"}}}},"400":{"description":"Invalid date range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid partner provisioning key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Database unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/partner/webhook":{"post":{"operationId":"partnerInboundWebhook","summary":"Inbound event from partner (user.created, user.deleted)","description":"Partner-to-AgentTax event channel. Body is JSON; the event type is carried in `X-AgentTax-Event`.\n\n**Authentication is HMAC over the raw body** (the partnerProvisioningKey scheme does NOT apply here):\n\n- `X-AgentTax-Partner`: partner slug (e.g. `invoica`).\n- `X-AgentTax-Signature`: `t=<unix-seconds>,v1=<hex>`. v1 = HMAC-SHA256(secret, body). ±5 min clock skew tolerance.\n- `X-AgentTax-Nonce`: 8-128 char unique-per-request token. Replay-rejected if seen within the tolerance window.\n- `X-AgentTax-Event`: one of `user.created`, `user.deleted`.\n\nThe response NEVER returns the API key — partner must call `/partner/provision` directly to obtain credentials. This prevents credential leakage via webhook replay attacks.","tags":["Partners"],"security":[{"partnerWebhookSignature":[]}],"parameters":[{"schema":{"type":"string","example":"invoica"},"required":true,"name":"x-agenttax-partner","in":"header"},{"schema":{"type":"string","example":"t=1714060800,v1=4f2e3d…","description":"HMAC-SHA256 of the raw body, formatted as `t=<unix-seconds>,v1=<hex>`."},"required":true,"description":"HMAC-SHA256 of the raw body, formatted as `t=<unix-seconds>,v1=<hex>`.","name":"x-agenttax-signature","in":"header"},{"schema":{"type":"string","minLength":8,"maxLength":128,"description":"Unique per-request nonce. Replay-rejected if seen within the 5-minute tolerance window."},"required":true,"description":"Unique per-request nonce. Replay-rejected if seen within the 5-minute tolerance window.","name":"x-agenttax-nonce","in":"header"},{"schema":{"type":"string","enum":["user.created","user.deleted"],"description":"Inbound event type. Carried in `X-AgentTax-Event` header. Body is event-specific; see request schemas below."},"required":true,"description":"Inbound event type. Carried in `X-AgentTax-Event` header. Body is event-specific; see request schemas below.","name":"x-agenttax-event","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerWebhookRequest"},"examples":{"user.created":{"value":{"external_id":"invoica_user_42","email":"user@example.com","display_name":"Acme AI"}},"user.deleted":{"value":{"external_id":"invoica_user_42"}}}}}},"responses":{"200":{"description":"Event processed. Body never returns an `api_key` — call /partner/provision for credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerWebhookResponse"}}}},"400":{"description":"Missing required header, malformed body, or unsupported event.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid HMAC signature OR nonce replay rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Partner slug not found or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server misconfiguration (e.g. webhook secret undecryptable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"openapiSpec","summary":"Fetch this OpenAPI spec","description":"Public, cacheable. The spec is auto-generated from the zod schemas in api/_lib/schemas/ via api/_lib/schemas/_registry.js — adding a new endpoint there propagates here automatically.","tags":["Discovery"],"responses":{"200":{"description":"OpenAPI 3.1 document."}}}}}}