{
  "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 via x402 micropayment.",
    "version": "1.2.0",
    "contact": {
      "url": "https://taxpulse-phi.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://taxpulse-phi.vercel.app"
    }
  ],
  "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.15,
        "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.15,
        "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.15,
        "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.15,
        "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.15,
        "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"
      }
    }
  }
}