{
  "openapi": "3.1.0",
  "info": {
    "title": "TaxPulse API",
    "description": "Global tax intelligence API. AI-synthesized tax guidance for 195 countries: income tax rates, VAT/GST, corporate tax, capital gains, crypto tax treatment, expat tax obligations, digital nomad tax structures, tax treaty analysis, entity structure comparison, and cross-border compliance. Tax software, crypto tax tools (Koinly, TaxBit), and expat tax service affiliates included. All endpoints support any language via ?lang=. Pricing: $0.08\u2013$0.15 USDC/call for tax intelligence endpoints; crypto wallet suite priced per-endpoint (wallet-guard $0.50, wallet-sleuth $1.50, wallet-review $12) \u2014 all via x402 micropayment.",
    "version": "1.3.0",
    "contact": {
      "url": "https://taxpulse.theaslangroupllc.com"
    }
  },
  "servers": [
    {
      "url": "https://taxpulse.theaslangroupllc.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 micropayment signature. Omit to receive 402 with payment requirements. Sign and retry to receive data."
      }
    }
  },
  "paths": {
    "/api/tax/country": {
      "get": {
        "summary": "Country tax system overview",
        "description": "Full tax system overview for any country \u2014 income brackets, corporate rate, capital gains, crypto treatment, VAT/GST, residency rules, special programs (NHR, HNWI, territorial systems), and verdict by taxpayer type.",
        "operationId": "taxCountry",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country name \u2014 e.g. Germany, UAE, Portugal, Singapore"
          },
          {
            "name": "scenario",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Profile of interest \u2014 e.g. expat individual, digital nomad, holding company, crypto investor"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Comprehensive country tax overview"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Start here for any country tax overview; chain to /api/tax/treaty for bilateral tax treatment; pairs with WealthPulse for tax-optimized investment allocation"
      }
    },
    "/api/tax/compare": {
      "get": {
        "summary": "Multi-country tax comparison",
        "description": "Side-by-side tax comparison of 2\u20133 countries for a specific scenario. Returns comparison matrix, country profiles, winner by use case, and optimal structure recommendation.",
        "operationId": "taxCompare",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "countries",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated list \u2014 e.g. Germany,UAE,Portugal"
          },
          {
            "name": "country1",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country2",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country3",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scenario",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "digital nomad | individual relocation | entrepreneur | holding company | crypto investor | retiree"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Multi-country tax comparison with winner by use case"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Run before relocation decision; pairs with RiskPulse /api/risk/country for full country due diligence; pairs with ImmigrationPulse for visa + tax combined analysis"
      }
    },
    "/api/tax/nomad": {
      "get": {
        "summary": "Digital nomad tax optimization",
        "description": "Comprehensive nomad tax strategy \u2014 territorial vs worldwide systems, top jurisdictions (UAE, Georgia, Paraguay, Portugal NHR/IFICI, etc.), 183-day traps, home country obligations by nationality, and practical action plan.",
        "operationId": "taxNomad",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "nationality",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "e.g. American, British, Canadian, German \u2014 affects home country obligations"
          },
          {
            "name": "income_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "remote employee | freelancer | entrepreneur | investor | content creator"
          },
          {
            "name": "income_level",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "focus",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Digital nomad tax optimization report"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Pairs with RiskPulse /api/risk/nomad for full nomad country profile; pairs with RemittancePulse for cross-border banking; pairs with ImmigrationPulse for digital nomad visas"
      }
    },
    "/api/tax/treaty": {
      "get": {
        "summary": "Tax treaty analysis",
        "description": "Bilateral DTT/DTA analysis \u2014 withholding rates for dividends/interest/royalties, capital gains rules, residency tiebreaker, MLI/BEPS modifications, and practical transaction scenarios. Covers no-treaty scenarios too.",
        "operationId": "taxTreaty",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "country1",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Resident country"
          },
          {
            "name": "country2",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Source country (where income arises)"
          },
          {
            "name": "transaction_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "dividends | interest | royalties | capital_gains | employment | pension | all"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tax treaty analysis with withholding rates and practical scenarios"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Run for any cross-border income situation; pairs with /api/tax/expat for dual-citizen scenarios; pairs with WealthPulse for treaty-optimized pension/retirement withdrawal"
      }
    },
    "/api/tax/structure": {
      "get": {
        "summary": "Corporate tax structuring",
        "description": "International corporate tax structures \u2014 holding company jurisdictions, IP box regimes (Netherlands 9%, Ireland KDB, Luxembourg, Malta), BEPS substance requirements, CFC rule analysis, transfer pricing, and Pillar Two implications.",
        "operationId": "taxStructure",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "objective",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "e.g. IP holding for SaaS, holding company for investments, minimize corporate tax"
          },
          {
            "name": "business_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "technology | ecommerce | financial | media | manufacturing | consulting"
          },
          {
            "name": "annual_revenue",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "shareholders",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Shareholder nationalities \u2014 affects CFC rules"
          },
          {
            "name": "jurisdictions",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Preferred jurisdictions \u2014 e.g. Netherlands,Luxembourg,UAE"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Corporate tax structuring recommendations with implementation roadmap"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Run before entity formation; entity formation affiliates (ZenBusiness, Stripe Atlas) auto-included; pairs with TradePulse /api/trade/compliance for international business structures"
      }
    },
    "/api/tax/crypto": {
      "get": {
        "summary": "Cryptocurrency tax by jurisdiction",
        "description": "Crypto tax treatment across 15+ key jurisdictions \u2014 capital gains rates, holding period benefits, staking/mining income treatment, DeFi/NFT treatment, CARF/DAC8 reporting obligations, and most favorable jurisdictions.",
        "operationId": "taxCrypto",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Specific country focus \u2014 or omit for global comparison"
          },
          {
            "name": "activity",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "trading | hodling | staking | mining | DeFi | NFT | all"
          },
          {
            "name": "assets",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Crypto tax intelligence by jurisdiction"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Highest-demand endpoint \u2014 crypto tax tool affiliates (Koinly, TaxBit) auto-included; pairs with OnchainPulse for DeFi tax edge cases; pairs with WealthPulse for capital gains optimization"
      }
    },
    "/api/tax/expat": {
      "get": {
        "summary": "Expat tax obligations",
        "description": "Cross-border tax compliance by nationality \u2014 FBAR/FATCA/FEIE for Americans, UK non-dom rules (post-2025 reform), Canadian departure returns, Australian CGT departure events, exit taxes, and practical compliance action plan.",
        "operationId": "taxExpat",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "nationality",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "e.g. American, British, Canadian, Australian, German"
          },
          {
            "name": "destination",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "situation",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "remote work | retirement | entrepreneur | investor | employment"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expat tax compliance intelligence with action plan"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Chain after /api/tax/country for source country context; pairs with ImmigrationPulse for visa + tax combined view; expat tax service affiliates auto-included"
      }
    },
    "/api/tax/vat": {
      "get": {
        "summary": "Global VAT/GST intelligence",
        "description": "VAT/GST rates and compliance across 170+ jurisdictions \u2014 registration thresholds, digital services rules, EU OSS/IOSS, marketplace platform obligations, and e-invoicing mandates. Critical for SaaS, e-commerce, and digital businesses selling globally.",
        "operationId": "taxVAT",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sector",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "digital_services | SaaS | ecommerce | physical_goods | professional_services"
          },
          {
            "name": "business_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "marketplace | direct_seller | subscription | agency"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "VAT/GST intelligence with compliance guidance"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "VAT compliance tools (TaxJar, Avalara) auto-included; pairs with TradePulse for import/export VAT; pairs with /api/tax/country for country VAT context"
      }
    },
    "/api/crypto/wallet-review": {
      "get": {
        "summary": "Citation-verified crypto wallet tax review",
        "description": "Citation-verified crypto wallet tax review: submit wallet addresses + jurisdiction, get a professional report grounded in primary tax law (statutes, rulings, case law) with machine-verified citations a CPA can check and sign. Law-synthesis layer, not a cost-basis calculator. Covers US, UK, Germany, India, Canada, Australia, Japan, Brazil, Singapore.",
        "operationId": "cryptoWalletReview",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "addresses",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "description": "Comma-separated wallet addresses (EVM 0x\u2026 and/or Solana), max 5"
          },
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "US"
            },
            "description": "Jurisdiction: US | UK | DE | IN | CA | AU | JP | BR | SG"
          },
          {
            "name": "chains",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "EVM chains to scan (CSV). Default: ethereum,base,arbitrum,optimism,polygon,gnosis"
          },
          {
            "name": "tax_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Focus tax year (e.g. 2025). Default: all activity"
          }
        ],
        "responses": {
          "200": {
            "description": "Citation-verified wallet tax review with per-finding verification status"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Highest-fidelity crypto tax artifact \u2014 chain from /api/tax/crypto for jurisdiction context; pairs with /api/crypto/wallet-sleuth for on-chain provenance and /api/crypto/wallet-guard for wallet safety before filing"
      }
    },
    "/api/crypto/wallet-sleuth": {
      "get": {
        "summary": "On-chain wallet investigation",
        "description": "On-chain wallet investigation: resolve a wallet to its identity (ENS, public labels), trace its funding path to origin, surface top counterparties with entity labels, find sibling wallets funded by the same source, and screen for sanction/phishing/mixer risk. Every finding carries an explorer evidence link.",
        "operationId": "cryptoWalletSleuth",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "description": "EVM wallet address (0x\u2026)"
          },
          {
            "name": "chain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Chain to investigate: ethereum | base | arbitrum | optimism | polygon | gnosis. Default ethereum"
          },
          {
            "name": "depth",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Funding-trace depth (1-5). Default 3"
          }
        ],
        "responses": {
          "200": {
            "description": "Entity resolution, funding trace, counterparties, sibling wallets and risk screening with evidence links"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 1.5,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Companion to /api/crypto/wallet-review (tax) and /api/crypto/wallet-guard (safety); run before large counterparty transactions or KYC/AML review"
      }
    },
    "/api/crypto/wallet-guard": {
      "get": {
        "summary": "Wallet drainer-protection scan",
        "description": "Wallet drainer-protection scan: enumerates every live token approval (ERC-20, ERC-721, ERC-1155) your wallet has granted across major EVM chains, risk-ranks each spender (malicious flags, unverified contracts, unlimited allowances, EOA spenders), and returns a prioritized revocation action list. Deterministic security scan.",
        "operationId": "cryptoWalletGuard",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "description": "EVM wallet address (0x\u2026)"
          },
          {
            "name": "chains",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "CSV of chains. Default: all (ethereum,base,arbitrum,optimism,polygon)"
          }
        ],
        "responses": {
          "200": {
            "description": "Risk-ranked live token approvals with prioritized revocation action list"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.5,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Deterministic, no LLM \u2014 run before signing anything new or periodically as wallet hygiene; companion to /api/crypto/wallet-review (tax) and /api/crypto/wallet-sleuth (forensics)"
      }
    },
    "/api/crypto/verification-stats": {
      "get": {
        "summary": "Citation-gate live track record (free)",
        "description": "Aggregate production totals for the wallet-review citation gate: findings generated vs. blocked by machine citation-verification across all paid reviews. Blocked findings are removed from reports rather than shown unverified \u2014 this endpoint is the public proof that the gate is real.",
        "operationId": "cryptoVerificationStats",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Live counters: reports_run, findings_generated, findings_blocked, findings_delivered, block_rate."
          }
        },
        "x-agent-chaining": "Check before buying /api/crypto/wallet-review to see the verification gate's live track record"
      }
    },
    "/api/crypto/wallet-watch": {
      "get": {
        "summary": "Whale-watch \u2014 standing 30-day wallet monitor ($5)",
        "description": "Register a 30-day watch on one EVM wallet: sweeps every 15 minutes across 6 chains, alerts when a transfer at or above your USD threshold moves in or out \u2014 POSTed to your webhook and/or polled from the free status endpoint. Fully anonymous: the returned watch_id + read_token are the only credentials that exist.",
        "operationId": "cryptoWalletWatch",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "description": "EVM wallet address to watch (0x\u2026)"
          },
          {
            "name": "threshold_usd",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "10000"
            },
            "description": "Alert on transfers \u2265 this USD value. Default 10000"
          },
          {
            "name": "webhook",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional public https webhook \u2014 alerts POSTed as JSON"
          },
          {
            "name": "chains",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "CSV of chains. Default: all (ethereum,base,arbitrum,optimism,polygon,gnosis)"
          }
        ],
        "responses": {
          "200": {
            "description": "watch_id, read_token, status_url, expiry \u2014 save them; they cannot be recovered."
          }
        },
        "x-price": "$5.00",
        "x-agent-chaining": "Register after /api/crypto/wallet-sleuth flags a wallet worth following, or after /api/crypto/wallet-guard on your own wallet; poll /api/crypto/wallet-watch-status for alerts"
      }
    },
    "/api/crypto/wallet-watch-status": {
      "get": {
        "summary": "Whale-watch status + alerts (free)",
        "description": "Poll a registered whale-watch: config, sweep health (provider failures shown loudly \u2014 degraded coverage is never an all-clear), and the last 100 alerts. Auth = watch_id + read_token from registration.",
        "operationId": "cryptoWalletWatchStatus",
        "parameters": [
          {
            "name": "watch_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "UUID from registration"
          },
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "read_token from registration"
          }
        ],
        "responses": {
          "200": {
            "description": "Watch status, sweep health, alert history."
          }
        },
        "x-agent-chaining": "The poll half of /api/crypto/wallet-watch"
      }
    }
  }
}