# ImmigrationPulse
# Global immigration intelligence API — x402 micropayment, USDC on Base
# https://immigrationpulse.vercel.app

## What This API Does
ImmigrationPulse decodes immigration law for any nationality, any destination, in any language.
Immigration attorneys charge $350-500/hour for questions this API answers in seconds for $0.10-0.20.

## Authentication
x402 protocol — include PAYMENT-SIGNATURE header.
All endpoints return 402 with payment requirements on first unauthenticated request.
Payment: USDC on Base mainnet.

## Endpoints

GET /api/points — $0.10
Skilled-worker points estimator for major points-based immigration systems.
Params: system (express-entry|skillselect|uk-pbs|germany|nz|austria|any), age, education (phd/masters/bachelors/diploma/trade), clb (Canadian Language Benchmark), ielts (band score), work_years (foreign experience), local_work (in-country experience), job_offer (true/false), nomination (true/false), partner (true/false), occupation (optional), lang (optional)
Example: /api/points?system=express-entry&age=31&education=masters&clb=9&work_years=5
Returns: score breakdown by factor, gap to current invitation cut-off, invitation likelihood, ranked improvement roadmap, alternative systems worth considering

GET /api/visa — $0.15
Visa requirements for any nationality/destination pair.
Params: nationality (string), destination (string), category (optional: work/tourist/study/family/investor/all), lang (optional BCP-47)
Example: /api/visa?nationality=Indian&destination=Canada&category=work
Returns: all visa categories available, requirements, work rights, fees, processing times, refusal risks, official URLs

GET /api/pathway — $0.20
Complete roadmap to permanent residency.
Params: nationality, destination, occupation (optional), education (optional), lang (optional)
Example: /api/pathway?nationality=Filipino&destination=Canada
Returns: every PR pathway ranked, timeline, cost, eligibility criteria, citizenship route, country cap warnings

GET /api/nomad — $0.15
Digital nomad visa finder for 50+ countries.
Params: income (monthly USD), nationality, preference (optional: tax_free/low_cost/europe/asia/fastest), region (optional), lang (optional)
Example: /api/nomad?income=3500&nationality=American&region=europe
Returns: top nomad visa picks ranked, tax situation, requirements, quality of life, banking/insurance advice

GET /api/citizenship — $0.15
Citizenship by investment, ancestry, and naturalization intelligence.
Params: type (investment/ancestry/naturalization/second), budget (optional USD), ancestry (optional country), nationality (optional), lang (optional)
Example: /api/citizenship?type=ancestry&ancestry=Italy
Returns: eligible programs, investment amounts, processing times, passport strength, dual citizenship rules

GET /api/status — $0.10
USCIS case status decoder.
Params: receipt (optional USCIS receipt number), form (optional e.g. I-485), status (optional status text), lang (optional)
Example: /api/status?receipt=MSC2190012345&form=I-485
Returns: plain English explanation, next steps, action required, processing time context, escalation options

GET /api/bulletin — $0.10
US Visa Bulletin priority date decoder.
Params: category (EB-1/EB-2/EB-3/F-1/F-2A/F-2B/F-3/F-4), chargeability (country), priority_date (optional YYYY-MM-DD), lang (optional)
Example: /api/bulletin?category=EB-2&chargeability=India
Returns: current priority dates, filing chart guidance, wait time estimate, movement trend, filing strategy

GET /api/retirement — $0.10
Global retirement visa options.
Params: nationality, budget (monthly USD), priority (optional: healthcare/tax_free/english/eu_access/cheapest), lang (optional)
Example: /api/retirement?nationality=American&budget=2500
Returns: top retirement destinations ranked, income requirements, healthcare, tax treatment, path to PR/citizenship

GET /api/compare — $0.15
Side-by-side immigration comparison across multiple destinations.
Params: nationality, destinations (comma-separated), occupation (optional), lang (optional)
Example: /api/compare?nationality=Nigerian&destinations=UK,Canada,Germany
Returns: difficulty, timeline, cost, quality of life, fastest path to PR for each destination

GET /api/rights — $0.10
Immigrant rights by country and visa type.
Params: destination, visa_status (e.g. H-1B, skilled worker, student), lang (optional)
Example: /api/rights?destination=US&visa_status=H-1B
Returns: work rights, healthcare access, education rights, legal protections, deportation defense, know-your-rights guidance

GET /api/cost — $0.10
Complete immigration cost breakdown.
Params: visa_type (e.g. I-485, H-1B, Skilled Worker), destination, with_attorney (optional boolean), family_size (optional integer), lang (optional)
Example: /api/cost?visa_type=I-485&destination=US&family_size=3
Returns: itemized government fees, attorney fee ranges, medical exam costs, document costs, DIY vs attorney comparison, fee waivers

## Language Support
All endpoints support ?lang= parameter (BCP-47 codes).
Responds in: en, hi, tl, es, ar, zh, pt, fr, de, ja, ko, bn, ur, sw, vi, id, tr, ro, and others.

## Global Coverage
US (federal + all visa categories), Canada (federal + provincial), UK, Australia, EU/Schengen, Germany, Portugal,
Singapore, Japan, UAE, New Zealand, Ireland, Netherlands, Caribbean CBI programs, Latin America (Mexico, Costa Rica,
Panama, Colombia, Ecuador), Southeast Asia (Thailand, Malaysia, Indonesia, Philippines), MENA (Bahrain, Saudi, Jordan),
Africa (South Africa, Mauritius), others via Tavily synthesis.

## Data Sources
USCIS public processing times API (no auth required)
US Department of State Visa Bulletin (monthly)
IRCC (Immigration, Refugees and Citizenship Canada) public draw history
Tavily real-time web synthesis for current requirements, processing times, policy changes, and latest invitation rounds
Hardcoded intelligence: 25+ nomad visa programs, 10 retirement destinations, 10 CBI programs, 8 ancestry programs, Express Entry CRS algorithm, SkillSelect points table

## Disclaimer
For informational purposes only. Not legal advice. Immigration law is complex and changes frequently.
Always verify requirements at official government sources and consult a licensed immigration attorney.