# TradeDataHub — Full Agent Guide (llms-full.txt)

## Identity
- TradeDataHub sells downloadable CSV datasets of verified US contractor and trade-business listings.
- Canonical site: https://www.tradedatahub.net/
- Developer docs: https://www.tradedatahub.net/developers/ | OpenAPI: https://www.tradedatahub.net/openapi.json | Machine catalog (this guide's companion): https://www.tradedatahub.net/llms.txt

## Coverage
- 33,753 protected records across 7 live states; ~50 trade categories; v1 catalog version.
- Product types: `state` (whole-state CSV), `state_trade` (one state x one trade), `city_trade` (one city x one trade), `mega_pack` (all live states).

## Buyer fields (delivered in the purchased CSV)
- Name, Phone, Website, Address, Category, City, State, last_verified_date.
- Email and authoritative license fields are NOT currently available. Counts describe field presence, not licensing or consent to contact.

## Format and verification
- Delivery format: one CSV file per product, UTF-8, one row per business record.
- Each record carries `last_verified_date` from the source pipeline. Verification dates describe source processing only — not licensing, active business status, or consent to contact.
- Methodology and limitations: https://www.tradedatahub.net/data-quality/

## Pricing model
- One-time purchase per dataset (no subscription): city+trade $9.99; state $29.99; seven-state pack $99.00.
- Authoritative per-product price: GET https://www.tradedatahub.net/api/v1/datasets/{product_id}/price

## Human purchasing path
- Each product page offers a secure one-time Stripe checkout; after payment the buyer receives a signed, time-limited download link. This human path is unchanged and separate from agent access.

## Agent / API discovery path
The complete inventory is machine-readable through the public API — do NOT scrape thousands of HTML pages.

Discovery flow:
1. /llms-full.txt (this file)
2. GET https://www.tradedatahub.net/api/v1/coverage — totals, currency, price model
3. GET https://www.tradedatahub.net/api/v1/states — purchasable states with record counts and prices
4. GET https://www.tradedatahub.net/api/v1/trades — trade list with aggregate record counts
5. GET https://www.tradedatahub.net/api/v1/cities?state=Texas — cities within a state
6. GET https://www.tradedatahub.net/api/v1/datasets — the deterministic product catalog (filterable, paginated)
7. GET https://www.tradedatahub.net/api/v1/datasets/{product_id} — one product's public metadata
8. GET https://www.tradedatahub.net/api/v1/datasets/{product_id}/price — exact price
9. GET https://www.tradedatahub.net/api/v1/datasets/{product_id}/preview — masked availability preview (no contact values)
10. GET https://www.tradedatahub.net/api/v1/datasets/{product_id}/download — paid retrieval; unpaid requests receive HTTP 402 TESTNET challenge

### Enumerating the COMPLETE catalog
- GET https://www.tradedatahub.net/api/v1/datasets supports filters: `state` (exact name, e.g. `Texas`), `trade` (exact name, e.g. `Roofer`), `city`, `type` (`city_trade|state_trade|state|mega_pack`), and pagination `limit` (<=100) / `offset`.
- Example: https://www.tradedatahub.net/api/v1/datasets?state=Texas&trade=Roofer
- Page through with offset until `pagination.total` is reached; every purchasable product is returned by this endpoint. The OpenAPI file documents all parameters and response schemas.

### product_id formats
- `state:{state_slug}` — e.g. `state:texas`
- `state-trade:{state_slug}:{trade_slug}` — e.g. `state-trade:florida:roofer`
- `city-trade:{state_slug}:{city_slug}:{trade_slug}` — e.g. `city-trade:texas:austin:plumber`
- `mega-pack:seven-live-states`
- Always take product_id values from the API responses instead of constructing them ad hoc.

### Representative public examples
- product_id: `state:california` (records=1,000 price=$29.99 currency=USD type=state)
  detail:  https://www.tradedatahub.net/api/v1/datasets/state:california
  price:   https://www.tradedatahub.net/api/v1/datasets/state:california/price
  preview: https://www.tradedatahub.net/api/v1/datasets/state:california/preview
  paid resource (x402 TESTNET, returns HTTP 402 until paid): https://www.tradedatahub.net/api/v1/datasets/state:california/download
- product_id: `state-trade:florida:appliance-repair-technician` (records=434 price=$19.00 currency=USD type=state_trade)
  detail:  https://www.tradedatahub.net/api/v1/datasets/state-trade:florida:appliance-repair-technician
  price:   https://www.tradedatahub.net/api/v1/datasets/state-trade:florida:appliance-repair-technician/price
  preview: https://www.tradedatahub.net/api/v1/datasets/state-trade:florida:appliance-repair-technician/preview
  paid resource (x402 TESTNET, returns HTTP 402 until paid): https://www.tradedatahub.net/api/v1/datasets/state-trade:florida:appliance-repair-technician/download
- product_id: `city-trade:california:anaheim:appliance-repair-technician` (records=1 price=$9.99 currency=USD type=city_trade)
  detail:  https://www.tradedatahub.net/api/v1/datasets/city-trade:california:anaheim:appliance-repair-technician
  price:   https://www.tradedatahub.net/api/v1/datasets/city-trade:california:anaheim:appliance-repair-technician/price
  preview: https://www.tradedatahub.net/api/v1/datasets/city-trade:california:anaheim:appliance-repair-technician/preview
  paid resource (x402 TESTNET, returns HTTP 402 until paid): https://www.tradedatahub.net/api/v1/datasets/city-trade:california:anaheim:appliance-repair-technician/download
- product_id: `mega-pack:seven-live-states` (records=33,753 price=$99.00 currency=USD type=mega_pack)
  detail:  https://www.tradedatahub.net/api/v1/datasets/mega-pack:seven-live-states
  price:   https://www.tradedatahub.net/api/v1/datasets/mega-pack:seven-live-states/price
  preview: https://www.tradedatahub.net/api/v1/datasets/mega-pack:seven-live-states/preview
  paid resource (x402 TESTNET, returns HTTP 402 until paid): https://www.tradedatahub.net/api/v1/datasets/mega-pack:seven-live-states/download

## x402 agent payment access — TESTNET ONLY
- x402 paid retrieval is available for TESTNET integration and testing ONLY.
- Network: Base Sepolia (eip155:84532). Asset: testnet USDC.
- Mainnet settlement is NOT enabled. Do not treat testnet x402 as production commerce.
- With no PAYMENT-SIGNATURE header, GET /download returns HTTP 402 Payment Required including the current x402 Payment-Required challenge (generated dynamically by the server; never hardcode it). Agents may inspect the 402 challenge without making any payment.
- Human Stripe purchasing remains a separate, unchanged path.

## Data protection
- Paid contact records, phone/email values, entitlements, tokens, and secrets are not exposed in discovery files or public API responses. Previews are masked by design.