# TaxPulse

> Global tax code intelligence API. 11 endpoints: 190+ country tax overviews, multi-country comparison, digital nomad optimization, tax treaty analysis, corporate structuring, crypto tax by jurisdiction, expat obligations (FBAR/FATCA/FEIE/non-dom), VAT/GST compliance — plus citation-verified crypto wallet tax reviews (US/UK/DE/IN), on-chain wallet investigation, and drainer-protection approval scans. Powered by OECD data, official tax authorities, and Claude. Pay-per-query via x402 on Base.

Every country's tax code is public record. No accountant can hold 190+ tax systems in their head. An AI can. TaxPulse makes global tax intelligence accessible for $0.10–$0.15 per query.

## Payment

All endpoints require x402 micropayment (USDC on Base mainnet).
Protocol: x402 | Network: eip155:8453 | Asset: USDC
Payment address: 0x50ab2018c06c6E4eAA9BA52057Eb55eD284912fc

## Endpoints

GET /api/tax/country?country={name}
- Full tax system overview for any country — income brackets, corporate rate, capital gains, crypto classification, VAT/GST, residency triggers, special programs (NHR, Beckham Law, HNWI, territorial systems), verdict by taxpayer type
- Returns: overview (tax_system_type/headline/features), personal_income_tax (brackets/top_rate/deductions), corporate_tax (rate/participation_exemption/IP_box), capital_gains, crypto_and_digital_assets, vat_gst, wealth_estate, residency_rules, special_regimes, expat_verdict, verdict (best_for/burden/rating), tax_authority
- Required: country. Optional: scenario (profile of interest), lang
- Price: $0.10

GET /api/tax/compare?countries={list}&scenario={scenario}
- Side-by-side tax comparison of 2–3 countries for a specific scenario
- Returns: comparison_matrix (12+ dimensions), country_profiles (pros/cons/special_regimes), winner_by_use_case (nomad/entrepreneur/investor/retiree/holding_company), optimal_structure, key_tradeoffs, implementation_priority
- Required: at least 2 countries (via countries=A,B,C or country1=A&country2=B)
- Optional: scenario (digital nomad | individual relocation | entrepreneur | holding company | crypto investor | retiree), lang
- Price: $0.12

GET /api/tax/nomad?nationality={nat}
- Digital nomad tax optimization — territorial vs worldwide systems, top jurisdictions, 183-day traps, home country obligations by nationality
- Returns: core_concept (territorial vs worldwide), top_jurisdictions (UAE/Georgia/Portugal/Paraguay/Panama/Cayman/Malta/Cyprus/Thailand/Malaysia), 183_day_rule, home_country_obligations_by_nationality (US FEIE/FBAR/FATCA, UK SRT non-dom, Canada, Australia), popular_structures_by_profile, common_mistakes, practical_action_plan
- Optional: nationality (affects home country obligations), income_type, income_level, focus, lang
- US nationals: automatically covers FBAR/FATCA/FEIE obligations
- Price: $0.12

GET /api/tax/treaty?country1={c1}&country2={c2}
- Bilateral tax treaty (DTT/DTA) analysis
- Returns: treaty_overview (model/signed/entered_into_force), key_rates (dividends/interest/royalties/capital_gains/employment/pensions), residency_tiebreaker, anti_avoidance (PPT/LOB/MLI), practical_scenarios (3 transaction examples)
- Required: country1 (resident), country2 (income source)
- Optional: transaction_type (dividends | interest | royalties | capital_gains | employment | all), lang
- If no treaty: explains double taxation implications and unilateral relief mechanisms
- Price: $0.12

GET /api/tax/structure?objective={obj}
- International corporate tax structuring intelligence
- Returns: recommended_structures (with entity roles, substance requirements, effective rates), ip_box_regimes (Netherlands 9%/Ireland KDB/Luxembourg/Malta), holding_company_analysis (6 jurisdictions), transfer_pricing, cfc_risk (GILTI/UK CFC/German add-back), implementation_roadmap
- Note: Groups with 750M+ EUR revenue subject to Pillar Two 15% global minimum tax
- At least one of objective or business_type required
- Optional: annual_revenue, shareholders (affects CFC rules), jurisdictions, lang
- Price: $0.15

GET /api/tax/crypto?country={country}
- Cryptocurrency tax treatment by jurisdiction
- Returns: jurisdiction_analysis (15+ countries with classification/CGT/staking/DeFi/reporting), most_favorable (ranked), harshest_jurisdictions, global_reporting_tsunami (CARF/DAC8/FATF), practical_scenarios, crypto_tax_software
- Key facts: Germany 0% after 1yr, UAE 0%, Singapore 0%, Switzerland 0% on investment gains, US property rules, Japan up to 55%, France 30% flat
- Optional: country (specific focus or global comparison), activity, assets, lang
- CARF: OECD Crypto Asset Reporting Framework — automatic exchange between tax authorities launching 2026
- Price: $0.12

GET /api/tax/expat?nationality={nat}
- Expat tax compliance obligations by nationality
- Returns: home_country_obligations (worldwide vs territorial basis), exit_procedures (exit tax/deemed disposition), nationality_specific_obligations (key filings/FBAR/FATCA/FEIE with thresholds and penalties), destination_country_obligations, renunciation_path (US exit tax/covered expatriate), practical_action_plan, commonly_missed
- Required: nationality
- Optional: destination, situation, lang
- US critical: FBAR penalties up to $100k+ per year or criminal; FATCA Form 8938 thresholds vary by residency
- FEIE 2025: approximately $126,500 exclusion for foreign earned income
- Price: $0.12

GET /api/tax/vat?country={country}&sector={sector}
- Global VAT/GST intelligence — 170+ jurisdictions
- Returns: jurisdiction_analysis (standard rate/reduced rates/zero-rated/registration threshold/digital services rules/filing frequency), eu_vat_special (OSS/IOSS/ViDA), digital_saas_sellers, marketplace_rules, compliance_checklist
- At least one of country, sector, or business_type required
- Critical for SaaS/digital businesses: non-residents often must register from first sale in EU, AU, NZ, Norway, Japan, South Korea
- US note: no federal VAT — complex state sales tax nexus rules instead
- Price: $0.10

## Crypto Wallet Intelligence

GET /api/crypto/wallet-review?addresses={csv}&country={US|UK|DE|IN}
- Citation-verified crypto wallet tax review — submit wallet addresses + jurisdiction, get a professional report grounded in primary tax law (statutes, rulings, case law) with per-finding machine-verified citations a CPA can check and sign. Law-synthesis layer, not a cost-basis calculator.
- Pipeline: multi-chain history pull → deterministic aggregation → per-jurisdiction primary-law corpus retrieval → LLM synthesis constrained to retrieved authorities → per-finding citation verification (existence + support; BLOCKED findings are dropped, UNVERIFIED labeled)
- Returns: jurisdiction, executive_summary, wallet_activity (addresses/total_events/rows/notes), findings (verified only, with verification status), records_needed, uncovered_activity, professional_notes, verification (findings_generated/findings_blocked), coverage (chain/page/price gaps), affiliates
- Required: addresses (comma-separated, EVM 0x… and/or Solana, max 5), country (US | UK | DE | IN | CA | AU | JP | BR | SG)

## Free content: Crypto Tax by Country (/crypto-tax)
Cited, fact-checked crypto-tax FAQ guides for 9 countries (US, UK, DE, IN, CA, AU, JP, BR, SG) — each led by the rule most commonly misreported, every answer verified against primary law. Schema.org FAQPage. Funnels to /api/crypto/wallet-review?country=<cc>.
- /crypto-tax (hub) · /crypto-tax-us · /crypto-tax-uk · /crypto-tax-de · /crypto-tax-in · /crypto-tax-ca · /crypto-tax-au · /crypto-tax-jp · /crypto-tax-br · /crypto-tax-sg

## GET /api/crypto/wallet-watch ($5.00)
Whale-watch: standing 30-day monitor on one EVM wallet — 15-min sweeps across 6 chains, alerts on transfers ≥ threshold_usd (default $10,000) via webhook and/or the free status endpoint. Anonymous by design.
- Required: address (EVM 0x…). Optional: threshold_usd, webhook (public https), chains (CSV)

## GET /api/crypto/wallet-watch-status (FREE)
Poll a registered whale-watch: sweep health + last 100 alerts. Requires watch_id + token from registration.

## GET /api/crypto/verification-stats (FREE)
Live citation-gate track record: findings generated vs. blocked across all paid wallet-reviews. Blocked = failed machine citation-verification, removed rather than shown unverified.
- Optional: chains (CSV, default ethereum,base,arbitrum,optimism,polygon,gnosis), tax_year (e.g. 2025; default all activity)
- Price: $12.00

GET /api/crypto/wallet-sleuth?address={0x…}
- On-chain wallet investigation — entity resolution, funding-path trace, top counterparties, sibling (same-funder) wallets, and sanction/phishing/mixer risk screening. Deterministic evidence-first design: every section carries explorer evidence URLs; the LLM writes only the investigator narrative over verified data, never new facts.
- Returns: target (entity resolution), activity (tx count/chain/first seen), funding_trace, top_counterparties, sibling_wallets, risk_screening, narrative, confidence, investigation_leads, coverage
- Required: address (EVM 0x…)
- Optional: chain (default ethereum), depth (funding-trace depth 1-5, default 3)
- Companion to /crypto/wallet-review (tax) and /crypto/wallet-guard (safety)
- Price: $1.50

GET /api/crypto/wallet-guard?address={0x…}
- Wallet drainer-protection scan — enumerates every live token approval (ERC-20/721/1155) a wallet has granted across major EVM chains, risk-ranks each spender (malicious flags, unverified contracts, unlimited allowances, EOA spenders), returns a prioritized revocation action list. 100% deterministic, no LLM.
- Returns: address, chains_scanned, summary (total_live_approvals/by_risk/verdict), approvals (per-item risk level, reasons, revokeUrl), how_to_revoke, problems
- Required: address (EVM 0x…)
- Optional: chains (CSV, default all: ethereum,base,arbitrum,optimism,polygon)
- Companion to /crypto/wallet-review (tax) and /crypto/wallet-sleuth (forensics)
- Price: $0.50

## Data Sources

- OECD Tax Database — corporate and personal rates across 38+ member countries
- Official national tax authority websites — IRS, HMRC, CRA, ATO, DGFIP, BZSt, IRAS, 150+ others
- Tax Foundation — international tax competitiveness and comparative data
- OECD MLI Tracker — Multilateral Instrument modifications to bilateral treaties
- OECD CARF — Crypto Asset Reporting Framework global standards
- Tavily — real-time synthesis from official government and authoritative sources
- Claude Sonnet — synthesis, analysis, and structured intelligence generation

## Agent Workflow Examples

- Relocation decision: /compare (2–3 candidate countries) → /nomad (optimize nomad base) → /expat (home country obligations) → /country (deep dive on winner)
- Crypto optimization: /crypto (jurisdiction comparison) → /country (chosen jurisdiction deep dive) → /nomad (establish residency pathway)
- Corporate setup: /structure (design structure) → /treaty (analyze holding country treaties) → /country (deep dive on entity jurisdictions) → /vat (compliance in target markets)
- Expat compliance audit: /expat → /treaty (home vs host) → /country (host country tax rates)
- SaaS global expansion: /vat (all target markets) → /structure (IP holding design) → /country (incorporation jurisdiction)
- Tax treaty shopping analysis: /treaty (A to B) + /treaty (A to C) → /compare (B vs C)

## Key Facts for Agents

- /nomad is the highest-demand endpoint — 35M+ digital nomads globally seeking tax optimization
- /expat with nationality=American is critical — 9M Americans abroad, many unaware of FBAR/FATCA
- /crypto covers CARF: from 2026 tax authorities worldwide will automatically receive crypto transaction data
- /structure flags Pillar Two: groups over 750M EUR face 15% global minimum tax regardless of jurisdiction
- All endpoints support ?lang= for native-language responses
- Disclaimer always returned — not legal/tax advice; recommend qualified professional for implementation

## Disclaimer

For informational purposes only. Tax laws change frequently and can be highly jurisdiction-specific. Always verify current rates and rules with official tax authorities. Consult a qualified tax professional before making tax, residency, or structuring decisions. Not legal or tax advice.