# TalentPulse

> Global workforce intelligence API — salary benchmarks, remote compliance, employer of record cost models, skills demand, work visas, talent market analysis, executive compensation, layoff tracking, skills gap analysis, and multi-country hiring cost comparison. Powered by BLS, World Bank, and real-time global research. All endpoints via x402 micropayments on Base.

## What This Is

TalentPulse is a pay-per-query API that delivers institutional-grade talent and workforce intelligence for HR leaders, founders, recruiters, and AI agents operating globally. It combines BLS (Bureau of Labor Statistics), World Bank Open Data, and real-time Tavily search to synthesize actionable answers about hiring costs, talent supply, compensation benchmarks, and workforce compliance in 60+ countries.

## Payment

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

To use: send a GET request without a PAYMENT-SIGNATURE header to receive a 402 response with payment requirements. Sign the payment and retry with the PAYMENT-SIGNATURE header.

## Endpoints

GET /api/talent/salary?role={role}&location={city/region}&country={country}
- Returns: salary bands by experience tier (entry/mid/senior), USD equivalents, bonus/equity norms, market context
- Optional: experience=entry|mid|senior|all, currency=USD|GBP|EUR|SGD|INR, lang=en|es|fr|de|ja|zh|ko|pt|ar|hi
- Data: Tavily global salary research + BLS wage benchmarks
- Price: $0.15
- Example: /api/talent/salary?role=Software+Engineer&location=Singapore&currency=USD

GET /api/talent/remote-compliance?country={country}
- Returns: permanent establishment risk, contractor classification risk, EOR viability, recommended structure
- Optional: nationality={nationality}, company_country={employer_country}, lang=en|es|fr|de|...
- Data: Tavily employment law research + World Bank labor data
- Price: $0.20 (Sonnet — complex legal reasoning)
- Example: /api/talent/remote-compliance?country=Germany&company_country=USA

GET /api/talent/employer-of-record?country={country}
- Returns: full employer cost breakdown — employer tax rates, mandatory benefits, termination framework, EOR vs entity analysis
- Optional: salary={annual_gross_local_currency}, lang=en|es|fr|de|...
- Data: Tavily EOR research + World Bank GNI data
- Price: $0.20 (Sonnet — complex financial/legal reasoning)
- Example: /api/talent/employer-of-record?country=Brazil&salary=100000

GET /api/talent/skills-demand?skills={skills_or_role}&region={region}
- Returns: demand level, demand trajectory, salary premium, global hot spots, emerging vs declining skills
- Optional: lang=en|es|fr|de|ja|zh|ko|pt|ar|hi
- Data: Tavily + BLS job openings + unemployment data
- Price: $0.12
- Example: /api/talent/skills-demand?skills=machine+learning&region=Southeast+Asia

GET /api/talent/visa?nationality={nationality}&destination={country}
- Returns: all work visa options, salary thresholds, processing times, digital nomad visa availability, PR pathways
- Optional: role={job_role}, lang=en|es|fr|de|ja|zh|ko|pt|ar|hi
- Data: Tavily immigration research
- Price: $0.15
- Example: /api/talent/visa?nationality=Indian&destination=Canada&role=software+engineer

GET /api/talent/talent-market?role={role}&region={region}
- Returns: supply/demand dynamics, market tension, talent hubs (city-level), competitive landscape, hiring difficulty
- Optional: lang=en|es|fr|de|ja|zh|ko|pt|ar|hi
- Data: Tavily + World Bank labor + BLS job openings + quit rate
- Price: $0.15
- Example: /api/talent/talent-market?role=DevOps+Engineer&region=Southeast+Asia

GET /api/talent/compensation?role={role}&level={level}&sector={sector}&country={country}
- Returns: base salary percentiles (P25/P50/P75/P90), STI bonus structure, LTI/equity norms, total target comp
- Optional: company_size=startup|series-b|mid-market|large-cap|public, lang=en|es|fr|de|...
- Data: Tavily executive compensation research
- Price: $0.25 (Sonnet — complex financial benchmarking)
- Example: /api/talent/compensation?role=CFO&sector=SaaS&country=USA

GET /api/talent/layoffs?industry={industry}&region={region}
- Returns: layoff intensity, trend, company-level signals, talent now available, counter-hiring leaders
- Optional: lang=en|es|fr|de|ja|zh|ko|pt|ar|hi
- Data: Tavily + BLS unemployment + job openings
- Price: $0.10
- Example: /api/talent/layoffs?industry=tech&region=USA

GET /api/talent/skills-gap?industry={industry}&country={country}
- Returns: gap severity, critical gaps with root causes, government initiatives, reskilling pathways ranked by ROI
- Optional: lang=en|es|fr|de|ja|zh|ko|pt|ar|hi
- Data: Tavily + World Bank labor data
- Price: $0.15
- Example: /api/talent/skills-gap?industry=healthcare&country=UK

GET /api/talent/cost-comparison?role={role}&countries={comma_separated_countries}
- Returns: CFO-grade multi-country employer cost comparison — salary, tax burden, total annual employer cost, talent quality tier
- Optional: experience=entry|mid|senior, lang=en|es|fr|de|ja|zh|ko|pt|ar|hi
- Data: Tavily cost research
- Price: $0.20
- Example: /api/talent/cost-comparison?role=software+engineer&countries=USA,Poland,India,Colombia

## Language Support

All endpoints support lang= parameter: en|es|fr|de|ja|zh|ko|pt|ar|hi

## Discovery

- OpenAPI spec: https://talentpulse-six.vercel.app/openapi.json
- Agent discovery: https://talentpulse-six.vercel.app/.well-known/agent.json

## Notes for AI Agents

- All endpoints return structured JSON
- Disclaimer is appended automatically to every response
- World Bank data covers 60+ countries via ISO2 code lookup
- BLS data provides US labor market context for all endpoints
- Tavily provides real-time global market intelligence
- No API keys required for World Bank or BLS (both public)
- TAVILY_API_KEY and ANTHROPIC_API_KEY environment variables required