{
  "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–$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) — all via x402 micropayment.",
    "version": "1.3.0",
    "contact": {
      "name": "The Aslan Group LLC",
      "url": "https://pulsenetwork.theaslangroupllc.com",
      "email": "info@theaslangroupllc.com"
    },
    "x-guidance": "# TaxPulse API (x402 pay-per-call)\n\nGlobal tax code intelligence API. 15 endpoints: 190+ country tax overviews, citation-verified US state-tax answers (CA + NY), multi-country comparison, digital nomad optimization, bilateral tax treaty analysis, international 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, of\n\nBase URL: https://taxpulse.theaslangroupllc.com\n\n## Payment\nAll paid endpoints use the x402 protocol (HTTP 402): USDC on Base mainnet (eip155:8453). No API keys, no accounts, no subscriptions — pay per call.\n\n## Agent workflow\n1. Request the endpoint. Unpaid requests receive a 402 challenge with exact price and pay-to details (the challenge is returned before request validation).\n2. Settle with any x402 client (agentcash fetch, x402-fetch, x402-axios) and retry with the X-PAYMENT header.\n3. Responses are JSON. Prices below are fixed per call.\n\n## Paid endpoints\n- GET /api/tax/country — $0.1 — Full tax system overview for any country — income brackets, corporate rate, capital gains, crypto classification, VAT/GST, residency triggers, special programs \n- GET /api/tax/compare — $0.12 — Side-by-side tax comparison of 2–3 countries — comparison matrix across 12+ dimensions, winner by use case (nomad/entrepreneur/investor/retiree/holding_company)\n- GET /api/tax/nomad — $0.12 — Digital nomad tax optimization — territorial vs worldwide systems, top 10+ jurisdictions with program details, 183-day rule traps, home country obligations by n\n- GET /api/tax/treaty — $0.12 — Bilateral tax treaty analysis — withholding rates for dividends/interest/royalties, capital gains rules, residency tiebreaker, MLI/BEPS modifications, anti-avoi\n- GET /api/tax/structure — $0.15 — International corporate tax structuring — holding company jurisdictions, IP box regimes (Netherlands 9%, Ireland KDB, Luxembourg, Malta), BEPS substance require\n- GET /api/tax/crypto — $0.12 — Crypto tax treatment across 15+ jurisdictions — Germany 0% after 1yr, UAE 0%, Japan up to 55%, US property rules, staking/DeFi/NFT treatment, CARF/DAC8 reportin\n- GET /api/tax/expat — $0.12 — Expat tax compliance by nationality — Americans: FBAR (criminal penalties), FATCA Form 8938, FEIE ~$126k; UK: non-dom reform 2025, SRT; Canada: deemed dispositi\n- GET /api/tax/vat — $0.1 — Global VAT/GST intelligence — 170+ jurisdictions, digital services rules (non-residents often register from first sale), EU OSS/IOSS, marketplace platform oblig\n- GET /api/crypto/wallet-review — $12 — Citation-verified crypto wallet tax review — wallet addresses + jurisdiction in, a professional report grounded in primary tax law (statutes, rulings, case law)\n- GET /api/crypto/wallet-sleuth — $1.5 — On-chain wallet investigation — entity resolution, funding-path trace, top counterparties, sibling (same-funder) wallets, and sanction/phishing/mixer risk scree\n- GET /api/crypto/wallet-guard — $0.5 — Wallet drainer-protection scan — enumerates every live token approval (ERC-20/721/1155) across major EVM chains, risk-ranks each spender, returns a prioritized \n- GET /api/crypto/wallet-watch — $5 — Whale-watch — standing 30-day monitor on one EVM wallet: 15-min sweeps across 6 chains, alerts on transfers ≥ your USD threshold via webhook and/or polling. Ano\n- GET /api/tax/state — $0.5 — US STATE income-tax answers citation-verified against the actual state-law corpus — California (R&TC/18 CCR/FTB/OTA; static two-era IRC conformity, NOL suspensi\n- GET /api/tax/529-check — $0.5 — 529 withdrawal/rollover checker — K-12/credentialing/Roth gates + CA non-conformity traps (2.5%)\n- GET /api/tax/aotc-recovery — $0.5 — Missed AOTC recovery — open 1040-X window screen, up to $2,500/yr + 40% refundable\n\nMore APIs from this provider: https://pulsenetwork.theaslangroupllc.com (grouped catalog, all x402)."
  },
  "servers": [
    {
      "url": "https://taxpulse.theaslangroupllc.com"
    }
  ],
  "paths": {
    "/api/tax/country": {
      "get": {
        "summary": "Country tax system overview",
        "description": "Full tax system overview for any country — 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",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country name — e.g. Germany, UAE, Portugal, Singapore"
          },
          {
            "name": "scenario",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Profile of interest — 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",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/compare": {
      "get": {
        "summary": "Multi-country tax comparison",
        "description": "Side-by-side tax comparison of 2–3 countries for a specific scenario. Returns comparison matrix, country profiles, winner by use case, and optimal structure recommendation.",
        "operationId": "taxCompare",
        "parameters": [
          {
            "name": "countries",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated list — 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",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.120000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/nomad": {
      "get": {
        "summary": "Digital nomad tax optimization",
        "description": "Comprehensive nomad tax strategy — 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",
        "parameters": [
          {
            "name": "nationality",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "e.g. American, British, Canadian, German — 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",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.120000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/treaty": {
      "get": {
        "summary": "Tax treaty analysis",
        "description": "Bilateral DTT/DTA analysis — 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",
        "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",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.120000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/structure": {
      "get": {
        "summary": "Corporate tax structuring",
        "description": "International corporate tax structures — 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",
        "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 — affects CFC rules"
          },
          {
            "name": "jurisdictions",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Preferred jurisdictions — 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",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.150000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/crypto": {
      "get": {
        "summary": "Cryptocurrency tax by jurisdiction",
        "description": "Crypto tax treatment across 15+ key jurisdictions — capital gains rates, holding period benefits, staking/mining income treatment, DeFi/NFT treatment, CARF/DAC8 reporting obligations, and most favorable jurisdictions.",
        "operationId": "taxCrypto",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Specific country focus — 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 — crypto tax tool affiliates (Koinly, TaxBit) auto-included; pairs with OnchainPulse for DeFi tax edge cases; pairs with WealthPulse for capital gains optimization",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.120000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/expat": {
      "get": {
        "summary": "Expat tax obligations",
        "description": "Cross-border tax compliance by nationality — 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",
        "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",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.120000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/vat": {
      "get": {
        "summary": "Global VAT/GST intelligence",
        "description": "VAT/GST rates and compliance across 170+ jurisdictions — 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",
        "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",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.100000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/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",
        "parameters": [
          {
            "name": "addresses",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "description": "Comma-separated wallet addresses (EVM 0x… 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 — 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",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "12.000000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/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",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "description": "EVM wallet address (0x…)"
          },
          {
            "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",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "1.500000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/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",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "description": "EVM wallet address (0x…)"
          },
          {
            "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 — run before signing anything new or periodically as wallet hygiene; companion to /api/crypto/wallet-review (tax) and /api/crypto/wallet-sleuth (forensics)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.500000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/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 — 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",
        "x-price-usd": 0
      }
    },
    "/api/crypto/wallet-watch": {
      "get": {
        "summary": "Whale-watch — 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 — 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",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "description": "EVM wallet address to watch (0x…)"
          },
          {
            "name": "threshold_usd",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "example": "10000"
            },
            "description": "Alert on transfers ≥ this USD value. Default 10000"
          },
          {
            "name": "webhook",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional public https webhook — 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 — save them; they cannot be recovered."
          },
          "402": {
            "description": "Payment Required"
          }
        },
        "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",
        "x-price-usd": 5,
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "5.000000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/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 — 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",
        "x-price-usd": 0
      }
    },
    "/api/tax/state": {
      "get": {
        "summary": "US state income-tax answer — citation-verified (California + New York)",
        "description": "State income-tax answer grounded in the actual state-law corpus with machine-verified citations a CPA can check. California: R&TC statutes, FTB regulations/rulings/publications (incl. the Residency & Sourcing Technical Manual), OTA precedential opinions — static two-era IRC conformity (§17024.5 / SB 711), NOL suspension, residency safe harbors, nonresident sourcing. New York: Tax Law (Arts. 22/24-A/24-B/30), 20 NYCRR, DTF TSB-M/N-notices/publications (incl. the Nonresident Audit Guidelines), Tax Appeals Tribunal decisions and Gaied/Zelinsky/Tamagni court authority — rolling IRC conformity with OBBBA decoupling (N-26-1), the convenience-of-the-employer rule, statutory residency (183-day/PPA), the §620 resident-credit intangible trap, PTET, and NYC/Yonkers taxes. Findings that fail citation verification are dropped, never shown. More states as corpora ship.",
        "operationId": "taxState",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "CA",
                "NY"
              ]
            },
            "description": "State code — CA or NY (more states as corpora are ingested)",
            "example": "NY"
          },
          {
            "name": "question",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "One concrete state-tax question",
            "example": "Do I owe NY tax on days I work from home in New Jersey?"
          },
          {
            "name": "tax_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Tax year — drives the IRC-conformity era and era-gated rules (e.g. 2024 vs 2025)",
            "example": "2025"
          }
        ],
        "responses": {
          "200": {
            "description": "Citation-verified answer with findings, era notes, federal interaction, verification stats"
          },
          "402": {
            "description": "Payment required (x402 — $0.50 USDC on Base)"
          }
        },
        "x-price-usd": 0.5,
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.500000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/529-check": {
      "get": {
        "summary": "529 withdrawal & rollover checker (K-12/credentialing/Roth/nonqualified + CA traps)",
        "description": "Deterministic qualification check: OBBBA K-12 $20k cap (2026) + expanded categories, postsecondary credentialing, SECURE 2.0 Roth-rollover gates (15-yr account, 5-yr seasoning, earned-income + Roth-limit ceiling, $35k lifetime), student-loan $10k cap, nonqualified tax + 10% penalty with exception routing. California non-conformity computed: K-12, credentialing and 529-to-Roth are ALL CA-taxable + 2.5% additional tax despite federal treatment (FTB 3805P).",
        "operationId": "tax529Check",
        "parameters": [
          {
            "name": "purpose",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "college|k12|credentialing|roth_rollover|nonqualified|apprenticeship|student_loan",
            "example": "roth_rollover"
          },
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Withdrawal/rollover amount",
            "example": "15000"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "State code; CA arms non-conformity traps"
          },
          {
            "name": "tax_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Default 2026 (K-12 cap is year-dependent)"
          },
          {
            "name": "earnings_portion",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "1099-Q box 2 earnings (nonqualified math; default 40% estimate)"
          },
          {
            "name": "account_age_years",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Roth rollover: account age for this beneficiary"
          },
          {
            "name": "contributions_last_5y",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Roth rollover: contributions in the last 5 years (ineligible)"
          },
          {
            "name": "beneficiary_earned_income",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Roth rollover: beneficiary earned income"
          },
          {
            "name": "prior_roth_rollovers",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Roth rollover: lifetime amount already rolled"
          },
          {
            "name": "penalty_exception",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "none|scholarship|death|disability|military_academy|education_credit"
          },
          {
            "name": "marginal_rate",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Marginal federal rate % for nonqualified estimate (default 22)"
          }
        ],
        "responses": {
          "200": {
            "description": "Qualification verdict + federal/CA math"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.5,
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.500000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/aotc-recovery": {
      "get": {
        "summary": "Missed AOTC recovery — open-window 1040-X screen (up to $2,500/yr)",
        "description": "Per-year screen across the open amendment window (TY2023-2025): IRC §25A credit math (100% of first $2k + 25% of next $2k), MAGI phaseouts ($80-90k/$160-180k), 4-year + half-time + MFS gates, 40% refundable portion, 529-coordination and AOTC-vs-LLC traps, per-year 1040-X worksheets.",
        "operationId": "taxAotcRecovery",
        "parameters": [
          {
            "name": "tax_years",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma list, e.g. 2023,2024,2025",
            "example": "2023,2024"
          },
          {
            "name": "expenses",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Qualified expenses per year (comma list or single broadcast)",
            "example": "4000"
          },
          {
            "name": "magi",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "MAGI per year (comma list or single broadcast)",
            "example": "72000"
          },
          {
            "name": "filing_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "single|mfj|mfs|hoh (list or single)"
          },
          {
            "name": "claimed",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "true if AOTC already claimed that year (list or single)"
          },
          {
            "name": "prior_aotc_years",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "AOTC/Hope years used before the earliest input year"
          },
          {
            "name": "completed_first_4_years",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "true if first 4 postsecondary years done before these years"
          },
          {
            "name": "half_time",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "false if under half-time enrollment"
          }
        ],
        "responses": {
          "200": {
            "description": "Per-year eligibility + credit + refundable portion + total"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.5,
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.500000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/crypto/wallet-snapshot": {
      "get": {
        "summary": "Wallet snapshot (lite tier)",
        "description": "Wallet snapshot: deterministic on-chain stats for one address across major EVM chains — transaction count, token-transfer count, wallet age (first-tx date), native balance, account type, and risk-flag count. Lite-tier preview (agent-cap friendly); no investigation narrative or approval enumeration. 100% deterministic, no LLM.",
        "operationId": "cryptoWalletSnapshot",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "description": "EVM wallet address (0x…)"
          },
          {
            "name": "chains",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "CSV of chains. Default: all (ethereum,base,arbitrum,optimism,polygon,gnosis)"
          }
        ],
        "responses": {
          "200": {
            "description": "Per-chain tx counts, wallet age, native balance, account type, and risk-flag count, plus an upsell ladder to wallet-guard/wallet-sleuth/wallet-review"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.25,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Lite-tier preview for agents with small per-call spend caps; ladders up to /api/crypto/wallet-guard (safety), /api/crypto/wallet-sleuth (forensics), and /api/crypto/wallet-review (tax)",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.250000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    },
    "/api/tax/529-check-lite": {
      "get": {
        "summary": "529 withdrawal & rollover checker (lite tier)",
        "description": "529 withdrawal & rollover checker — LITE preview. Same deterministic engine as the full product: verdict + a one-line federal headline for THIS withdrawal (K-12 OBBBA cap, credentialing, SECURE 2.0 Roth rollover, student-loan cap, non-qualified) and a California-trap flag. Full federal/CA breakdown, all flags, and IRC/SECURE 2.0/OBBBA/FTB citations are in the full product. Deterministic, no LLM.",
        "operationId": "tax529CheckLite",
        "parameters": [
          {
            "name": "purpose",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "college|k12|credentialing|roth_rollover|nonqualified|apprenticeship|student_loan",
            "example": "roth_rollover"
          },
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Withdrawal/rollover amount",
            "example": "15000"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "State code; CA arms non-conformity traps"
          },
          {
            "name": "account_age_years",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Roth rollover: account age for this beneficiary"
          },
          {
            "name": "beneficiary_earned_income",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Roth rollover: beneficiary earned income"
          }
        ],
        "responses": {
          "200": {
            "description": "Verdict, one-line federal headline, and California-trap flag (full breakdown + citations are the $0.50 full product)"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.25,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Lite-tier preview for agents with small per-call spend caps; ladders up to /api/tax/529-check ($0.50) for the full breakdown + citations",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.250000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        }
      }
    }
  }
}