diff --git a/.github/workflows/hosted-integration-tests.yml b/.github/workflows/hosted-integration-tests.yml
new file mode 100644
index 0000000..8408ddf
--- /dev/null
+++ b/.github/workflows/hosted-integration-tests.yml
@@ -0,0 +1,21 @@
+name: Hosted integration tests
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  hosted-integration-tests:
+    runs-on: ubuntu-latest
+    env:
+      MTA_API_KEY: ${{ secrets.MTA_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install --frozen-lockfile
+
+      - run: bun test hosted-integration.test.ts
diff --git a/README.md b/README.md
index 0726f2a..5cb5faf 100644
--- a/README.md
+++ b/README.md
@@ -350,6 +350,14 @@ mta.static.importSeed(
 );
 ```
 
+## Roadmap
+
+- Expand the package beyond NYC MTA into a normalized US metro SDK while keeping the existing MTA API stable.
+- Prioritize large systems with documented APIs and realtime data first: MBTA (Boston), WMATA (DC), CTA (Chicago), and BART (Bay Area).
+- Add adapters for mid-tier systems that expose GTFS, GTFS Realtime, or partial APIs, including SEPTA, LA Metro, and MARTA.
+- Model agency-specific quirks behind shared concepts like arrivals, vehicles, service alerts, route-aware nearby stops, static GTFS import, and hosted API access.
+- Track smaller agencies separately because support quality varies: some only publish static GTFS, some have buried realtime feeds, and some have no public API surface.
+
 ## Development
 
 ```sh
diff --git a/hosted-integration.test.ts b/hosted-integration.test.ts
new file mode 100644
index 0000000..8f8349f
--- /dev/null
+++ b/hosted-integration.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { MTA } from "./index";
+
+const apiKey = process.env.MTA_API_KEY;
+
+describe.skipIf(!apiKey)("hosted integration tests", () => {
+  test("runs the docs quickstart against the hosted API", async () => {
+    const mta = new MTA({
+      apiKey,
+    });
+
+    const arrivals = await mta.subway.arrivals({
+      stopId: "A27",
+      route: "A",
+    });
+
+    const stops = await mta.stops.near({
+      lat: 40.7356,
+      lon: -73.9804,
+      modes: ["subway", "bus"],
+      route: "M23",
+      limit: 10,
+    });
+
+    const vehicles = await mta.bus.vehicles({
+      route: "M23",
+      limit: 5,
+    });
+
+    expect(Array.isArray(arrivals)).toBe(true);
+    expect(Array.isArray(stops)).toBe(true);
+    expect(Array.isArray(vehicles)).toBe(true);
+    expect(stops.length).toBeGreaterThan(0);
+    expect(stops.every((stop) => stop.routeMatch)).toBe(true);
+  }, 30_000);
+});