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