---
name: franchisedata-io
description: "Search or query US franchise restaurant location data, in-store POS hardware (NCR Aloha, Toast, Brink, Micros), FDD Item 19 financial models (AUV, royalty, ad fund), multi-unit franchisee holding entities, real-time news wire, and delivery platform links across 500 chains (210,484+ stores). Pay per call in USDC (x402) or spend prepaid fc_live_ Bearer credits. No OAuth."
---

# franchisedata.io — Franchise Restaurant Data & Commercial Intelligence API for Agents (x402 + credits)

This is one HTTP gateway and MCP server for 2,000+ commercial intelligence endpoints across the 500 largest US restaurant chains (210,484+ store locations). Enriched with verified in-store POS tech stacks, statutory FDD Item 19 financial benchmarks (FTC 16 CFR § 436.5), multi-unit franchisee ownership LLCs, SEC EDGAR Form 10-K CIKs, real-time news wire intelligence, and real-time delivery platform links (DoorDash, Uber Eats, Grubhub). Every endpoint is a simple GET, paid in USDC on Base, Polygon, Arbitrum, Monad, or Solana — per call via x402, or prepaid via credits with a Bearer API key (`fc_live_...`). No accounts or OAuth required for agent calls.

Base URL: https://franchisedata.io

## Triggers

Use this skill when the user wants to:

- Search or query restaurant location data, store counts, street addresses, geocodes, or telephone numbers across 500 US chains
- Check in-store Point-of-Sale (POS) hardware and Kitchen Display Systems (KDS) (e.g. NCR Aloha, Toast, Oracle Simphony, PAR Brink, Xenial)
- Retrieve statutory Franchise Disclosure Document (FDD) Item 19 unit economics (Median AUV, Royalty %, Ad Fund %, Initial Investment Ranges)
- Audit multi-unit franchisee ownership entities and parent holding companies (e.g. Flynn Restaurant Group, Sun Holdings, Carrols, Dhanani Group, Tacala)
- Monitor breaking franchise industry intelligence (Chapter 11 bankruptcies, FTC/DOL litigation, C-suite leadership changes, store expansions) via `/api/news`
- Audit third-party delivery multi-homing across DoorDash, Uber Eats, and Grubhub with customer ratings and direct deep links
- Check real-time operating status (open/closed, hours, drive-thru availability) for specific stores
- Query nearby locations by latitude/longitude radius, city, state, or postal code
- Export bulk fleet datasets (RFC 4180 CSV / GeoJSON) for real estate site selection, M&A due diligence, or demographic white-space mapping
- Call paid franchise restaurant APIs with USDC micropayments (x402) or a prepaid credit balance

## Response envelope

Every endpoint returns JSON of the shape:

```json
{ "status": 200, "message": "ok", "data": "..." }
```

The HTTP status code mirrors the "status" field. Errors carry a descriptive "message".

## Payment mode A — prepaid credits (recommended for agents)

One on-chain payment funds a balance; every call after that is a plain HTTP request with an API key. Fastest path: no signing, no chain round-trip per call.

Step 1 — top up (minimum $1). The top-up endpoint is itself x402-paid; pay it with any x402 client from a wallet holding USDC on any supported network (Base, Polygon, Arbitrum, Monad, Solana):

```js
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);

// Base (8453), Polygon (137), Arbitrum (42161), Monad (143)
const EVM_NETWORKS = ["eip155:8453", "eip155:137", "eip155:42161"];
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: EVM_NETWORKS.map((network) => ({
    network,
    client: new ExactEvmScheme(account),
  })),
});

const res = await fetchWithPayment(
  "https://franchisedata.io/api/credits/topup?amount=5",
  { method: "POST" }
);
const { data } = await res.json();
// data.key -> "fc_live_..." — returned EXACTLY ONCE on first top-up. Save it.
```

Notes:
- Refill top-ups keep the existing key. Add `&rotate=1` to mint a new key (the old one stops working immediately).
- Lost keys cannot be recovered (only a hash is stored) — rotate instead.
- To add credits to an EXISTING key from any wallet, send the same POST with header `Authorization: Bearer fc_live_...`.

Step 2 — call any endpoint with the key:

```bash
curl -H "Authorization: Bearer fc_live_..." "https://franchisedata.io/api/brands/mcdonalds/locations?city=Los%20Angeles"
```

Step 3 — check the balance whenever needed:

```bash
curl -H "Authorization: Bearer fc_live_..." "https://franchisedata.io/api/credits/balance"
```

If the balance cannot cover a call, the API answers 402 with message `topup_required` plus `balance_micro`, `price_micro`, and `topup_url`.

## Payment mode B — x402 pay-per-call

Stateless and fully autonomous. Requirement: a wallet holding USDC on Base, Polygon, Arbitrum, Monad, or Solana. No native gas token needed — gas is sponsored by the facilitator.

1. GET the endpoint with no payment → 402 response with a base64 `payment-required` header whose `accepts` array has one entry per network.
2. Sign the USDC transfer authorization for that amount on whichever chain you hold USDC on (Base is default).
3. Retry with the signed payload in the `X-Payment` header → the data comes back and the payment settles on-chain.

With `@x402/fetch` the whole 402 → sign → retry loop is automatic:

```js
const res = await fetchWithPayment("https://franchisedata.io/api/brands/starbucks/locations?state=CA");
console.log(await res.json());
```

## Payment mode C — Corporate Operator Pro ($249/mo)

Designed for multi-unit franchisees, private equity operating partners, and CDO real estate teams:

- Unlimited unblurred access to all 500 US restaurant chains
- Full 102,000+ store geocodes, physical addresses, and direct store telephone lines
- Multi-unit franchisee holding entities, portfolio sizes, and PE sponsor trees
- Audited FDD Item 19 financial benchmark distributions (AUV deciles, EBITDA margins, royalty rates)
- Unlimited RFC 4180 bulk CSV and GeoJSON fleet downloads
- Authenticate requests via `Authorization: Bearer fc_pro_...` or pass `x-franchise-pro: true` header.

## Funding & Account Notes

- A $1 credit top-up covers ~333 location search calls at $0.003/call.
- Humans can create or recharge a key in the browser at https://franchisedata.io/topup (connect an injected wallet, pick a chain, pay USDC, gas sponsored).
- If no funded wallet is available, ask the user to fund a key at https://franchisedata.io/topup or start a 14-day trial at https://franchisedata.io/pro and provide the `fc_live_...` or `fc_pro_...` API key.
- Never print private keys; never log the full API key.

## Endpoints (GET)

Prices are USD per call, settled in USDC.

### Brands Catalog (Free)
- GET `/api/brands` — Free — List all 500 indexed chains with sector, menu type, POS hardware, and pricing
- GET `/api/brands/{brand}` — Free — Brand commercial summary, total store count, corporate info, and available endpoints

### Store Locations & Fleet Intelligence (Paid)
- GET `/api/brands/{brand}/locations` — $0.003 — Filter by city, state, zip, drive-thru, or lat/lng radius (Top 7 showcase free, or unblurred with Pro)
- GET `/api/brands/{brand}/store/{storeId}` — $0.002 — Full store metadata, phone, address, and weekly schedule
- GET `/api/brands/{brand}/store/{storeId}/status` — $0.002 — Real-time open/closed status in local timezone
- GET `/api/brands/{brand}/store/{storeId}/tech-stack` — $0.002 — Verified POS system (Toast, NCR Aloha, Brink, Micros) & KDS
- GET `/api/brands/{brand}/store/{storeId}/delivery` — $0.002 — Multi-platform DoorDash, Uber Eats, Grubhub links & ratings
- GET `/api/brands/{brand}/operators` — $0.004 — Multi-unit franchisee ownership entities, portfolio counts, and parent holding LLCs
- GET `/api/brands/{brand}/fdd` — $0.004 — Item 19 financial model (AUV median, royalty %, ad fund %, initial investment range)
- GET `/api/search/near` — $0.005 — Multi-brand radial cross-search near coordinates (`?lat=38.9072&lng=-77.0369&radius_miles=5`)

### Bulk Dataset Exports (Paid / Pro Unlimited)
- GET `/api/export/brands/{brand}?format=csv` — $0.050 (Free for Pro) — Complete RFC 4180 CSV export of verified store geocodes, POS stacks, and franchisee LLCs
- GET `/api/export/brands/{brand}?format=json` — $0.050 (Free for Pro) — Complete structured JSON export

### Account & Credits
- POST `/api/credits/topup?amount=<usd>[&rotate=1]` — Mints or refills API key balance
- GET `/api/credits/balance` — Returns wallet/account balance in micro-USD and formatted USD

## Model Context Protocol (MCP)

Connect via zero-setup stdio CLI runner or remote HTTP gateway:

### Option A: Standard Stdio Runner (Recommended for Claude Desktop & Cursor)
Add to your `claude_desktop_config.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "franchisedata": {
      "command": "npx",
      "args": ["-y", "@franchisedata/mcp-server"],
      "env": {
        "FRANCHISE_API_KEY": "fc_live_your_key_here"
      }
    }
  }
}
```

### Option B: Remote HTTP Endpoint
```json
{
  "mcpServers": {
    "franchisedata": {
      "url": "https://franchisedata.io/api/mcp",
      "headers": { "Authorization": "Bearer fc_live_..." }
    }
  }
}
```

Free discovery tools: `search_brands`, `describe_endpoint`, `check_balance`.
Commercial tools: `fetch_franchise_data`, `topup_credits`, `mcdonalds_locations`, `starbucks_store_status`, `franchise_search_near`, `get_operator_intelligence`, `detect_tech_stack`, `track_brand_changes`, `get_fdd_item19`.