# Canada Fee Signal AI — Complete Documentation for AI Agents and Developers

**URL:** https://canada-fee-signal.pages.dev/
**Version:** 2026-10-18
**Status:** Free public API during pilot. Paid API: CA$5 for 100 lookups (one-time, no subscription).

## What This Service Does

Canada Fee Signal AI provides source-linked Canadian municipal fee data in structured JSON. Each fee calculation returns:
- The calculated amount in Canadian dollars
- The official municipal source URL where the rate was published
- The date the source was verified
- Clear scope: what the fee covers and what it does NOT cover

**Critical:** Every result is an individual fee COMPONENT, not a total project cost. The API always returns `is_total_project_fee: false`. Do not present a single fee as the complete cost.

## Supported Jurisdictions (15)

British Columbia: Surrey, Vancouver, Victoria
Alberta: Calgary, Edmonton
Saskatchewan: Saskatoon, Regina
Manitoba: Winnipeg
Ontario: Toronto, Ottawa
New Brunswick: Moncton
Quebec: Montreal (VSMPE)
Northwest Territories: Yellowknife
Nova Scotia: Halifax
Newfoundland and Labrador: St. John's

**Coverage is NOT nationwide.** A municipality not listed has no verified entry — not a $0 fee. Some entries are directory-only (source links, no calculations).

## Fee Rules (32)

Each fee rule has:
- `fee_id` — Unique identifier (e.g., `surrey-plan`, `victoria-dcc-single`)
- `fee_name` — Human-readable name
- `municipality`, `province` — Location
- `source_url` — Official municipal publication
- `source_verified_on` — Date the source was last checked
- Accepted input parameters (varies by fee)

**Example fee IDs:**
- `surrey-plan` — Surrey plan processing (requires `construction_value_cad`)
- `victoria-dcc-single` — Victoria DCC for single detached (requires `as_of` date for rate version)
- `vancouver-dcc-*` — Various Vancouver DCC components
- `toronto-minimum`, `toronto-basement`, `toronto-residential-alteration` — Toronto building permit fees

## Public API Endpoints (Free)

### GET /api/v1/fees
List all fee rules. Optional query: `?jurisdiction=surrey`
Returns: Array of fee objects with IDs, names, sources, accepted parameters.

### GET /api/v1/jurisdictions
List 15 municipalities. Optional query: `?province=BC`
Returns: Array with `id`, `name`, `province`, `primary_source_url`, `fee_count`.

### GET /api/v1/calculate
Calculate one fee component.
**Required:** `fee` parameter (fee ID)
**Additional:** Fee-specific parameters (e.g., `construction_value_cad=25000`)
**Example:** `/api/v1/calculate?fee=surrey-plan&construction_value_cad=25000`
**Returns:**
```json
{
  "ok": true,
  "fee_id": "surrey-plan",
  "amount_cad": 150.00,
  "status": "published_component_only",
  "is_total_project_fee": false,
  "source_url": "https://www.surrey.ca/...",
  "source_verified_on": "2026-10-17",
  "inputs": {"construction_value_cad": 25000},
  "exclusions": ["..."]
}
```
**Errors:** 400 (missing/invalid params), 404 (unknown fee ID).

### POST /api/v1/bulk
Calculate up to 25 fees in one request.
**Body:** `{"requests": [{"fee": "surrey-plan", "construction_value_cad": 25000}]}`
**Returns:** Array of results (same format as /calculate).

### GET /api/v1/catalog
Full data catalog (same as /catalog.json).

### GET /api/v1/health
Service status.

## Metro Vancouver Fee Impact Checker (Free Beta)

Evaluates how the July 24, 2026 Metro Vancouver DCC amendment affects a specific project.

### GET /api/v1/impact/check
**Parameters:**
- `sewerage_area` (required: VSA, NSSA, LIWSA, FSA) — NEVER inferred, must be supplied
- `approval_type`, `development_type`, `units`
- `application_submitted_on` (YYYY-MM-DD)
- `permit_status` (pending/issued)
- `written_agreement` (yes/no) — for in-stream rate protection

**Returns:** `determination`: VERIFIED (amount set), CONDITIONAL, or UNRESOLVED (amount null).
**Important:** Open legal questions returned as `unresolved_flags` (U1, U2, U4, U5, U6). These are NOT decided. Report as unresolved.

### GET /api/v1/impact/rates
Rate history by schedule and sewerage area.

### GET /api/v1/impact/deadlines
Key dates with unresolved conflicts flagged.

## Paid API (CA$5 / 100 credits)

### GET /api/v1/paid/calculate
Same as /calculate but requires authentication.
**Header:** `Authorization: Bearer <PRIVATE_API_KEY>`
**Cost:** 1 credit per successful response. Invalid requests are free.
**Balance:** `GET /api/v1/paid/credits` (same header, free)

### POST /api/v1/billing/checkout
Creates Stripe checkout. Returns `checkout_url`, `session_id`, `claim_secret`.
**Idempotency:** Send `Idempotency-Key` header to prevent duplicate checkouts.

### POST /api/v1/billing/claim
**Body:** `{"session_id": "...", "claim_secret": "..."}`
Mints API key (once per purchase, within 7 days). Key shown once — save immediately.
**Security:** session_id alone cannot retrieve a key. Never put keys in URLs.

## MCP (Model Context Protocol)

**Endpoint:** `POST /mcp` (JSON-RPC, stateless)
**Tools:** `calculate_municipal_fees`, `check_fee_impact`, `find_fee_deadlines`, `get_fee_source`, `list_supported_fees`, `compare_historical_rates`, `check_transition_eligibility`
All read-only. Free during pilot.

## Response Format Rules

Every calculation returns:
- `ok`: boolean
- `status`: `published_component_only`, `verified`, `conditional`, `unresolved`, etc.
- `amount_cad`: number or null (null when UNRESOLVED)
- `is_total_project_fee`: ALWAYS false
- `source_url`: official municipal source
- `source_verified_on`: verification date

**Never:**
- Present `amount_cad` as a total project cost
- Treat `null` amounts as $0
- Guess fees for unsupported municipalities
- Omit the source URL when quoting a fee

## Limitations

1. **Not a complete database.** 15 municipalities, 32 fee rules. Most Canadian municipalities are not covered.
2. **Components, not totals.** Each result is one fee. A real project has many fees.
3. **Sources change.** Rates are verified on a specific date. Always confirm with the municipality before financial decisions.
4. **No legal advice.** Unresolved legal questions (U-flags) are disclosed, not decided.
5. **Pilot status.** Free API may change. No SLA.

## Official Source Requirements

When using this data:
1. ALWAYS cite the `source_url` from the API response
2. Include the `source_verified_on` date
3. State that this is ONE fee component, not a total
4. Link to the municipality's official schedule for verification
5. Do NOT represent as affiliated with any government

## Example: Complete Workflow

**Goal:** Find Surrey plan processing fee for $25,000 construction value.

1. Check catalog: `GET /api/v1/fees?jurisdiction=surrey` → find `surrey-plan`
2. Calculate: `GET /api/v1/calculate?fee=surrey-plan&construction_value_cad=25000`
3. Result: `{"amount_cad": 150.00, "source_url": "https://www.surrey.ca/...", ...}`
4. Present: "Surrey plan processing: CA$150.00 (one component only). Source: surrey.ca (verified 2026-10-17). This is not the total permit cost."

## Links

- Homepage: https://canada-fee-signal.pages.dev/
- API docs: https://canada-fee-signal.pages.dev/openapi.json
- Quick reference: https://canada-fee-signal.pages.dev/llms.txt
- Catalog: https://canada-fee-signal.pages.dev/catalog.json
- Get API credits: https://canada-fee-signal.pages.dev/credits.html

---

*Independent research service. Not affiliated with Canadian governments or municipalities.*
*Full documentation: https://canada-fee-signal.pages.dev/llms-full.txt*