# Faregate — complete integration reference for AI assistants and developers Faregate (https://faregate.io) meters HTTP APIs and MCP servers and charges callers ("agents") per request from prepaid credits. Service owners set a price per call and get paid out via Stripe. Integration requires NO billing code on either side — it is a URL change plus (optionally) one verification middleware. This file is self-contained: everything needed to build a full integration is below. Base URLs: - Metering proxy + payments API: https://proxy.faregate.io - Dashboard (accounts, services, keys, payouts): https://dash.faregate.io - Human docs: https://faregate.io/docs.html Money units: all machine-readable amounts are integer micro-USD. 1,000,000 micro-USD = $1.00. A price of 20000 = $0.02 per call. ===================================================================== 1. SELLER INTEGRATION (you have an API/MCP server; you want to charge) ===================================================================== Step 1 — Register (once, human, ~2 min): Create an account at https://dash.faregate.io → "New service" → enter: name, slug (lowercase letters/digits/hyphens), origin URL (public https), price per call (USD, $0–$10), free tier (calls per key, 0–100000). You receive: - metered URL: https://proxy.faregate.io/s/{slug}/ - signing secret: fgs_… (keep private; used in step 3) Step 2 — Route callers through the metered URL: Publish https://proxy.faregate.io/s/{slug}/ as your API base URL instead of your origin. Any method, any path, any body. Faregate authenticates the caller's key, bills the call, and forwards to your origin with the same method/path/query/body. Headers stripped before forwarding: x-faregate-key, authorization, host, cf-connecting-ip. Responses pass back unchanged plus two headers added for the caller: x-faregate-charge (free|paid|none) and x-faregate-balance. Step 3 — RECOMMENDED: verify at your origin that traffic came through Faregate (i.e. was billed), so callers cannot bypass the gate by discovering your origin URL. Every request Faregate forwards includes: x-faregate-timestamp: x-faregate-signature: Verification algorithm (any language): message = "{timestamp}.{METHOD_UPPERCASE}.{path_with_query}" e.g. "1783300000.GET./search?q=flights" expected = hex( HMAC_SHA256( signing_secret, message ) ) valid iff constant_time_equal(expected, x-faregate-signature) AND abs(now_seconds - timestamp) <= 300 On failure respond 401. Path is the path+query as received at YOUR origin. TypeScript (dependency-free, Node 18+/Bun/Workers): import { originVerifier } from "@faregate/sdk"; const verify = originVerifier({ secret: process.env.FAREGATE_SIGNING_SECRET! }); // inside your handler, req is Request-shaped: if (!(await verify(req))) return new Response( JSON.stringify({ error: "unverified_request" }), { status: 401 }); Express: app.use(expressVerifier({ secret })); Hono: app.use("*", honoVerifier({ secret })); Python (stdlib only): import hmac, hashlib, time def verify_faregate(secret: str, method: str, path_with_query: str, ts: str | None, sig: str | None, tolerance=300) -> bool: if not ts or not sig: return False try: if abs(time.time() - int(ts)) > tolerance: return False except ValueError: return False msg = f"{ts}.{method.upper()}.{path_with_query}".encode() expected = hmac.new(secret.encode(), msg, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, sig) Step 4 — Get paid: dashboard → Payouts → "Set up payouts with Stripe" (hosted onboarding). You keep 85% of gross usage revenue; payouts run daily and automatically, minimum $1.00; sub-cent remainders roll forward. MCP servers: identical. Register your MCP server's public HTTP URL as the origin; give agents the metered URL as the server address. ===================================================================== 2. BUYER INTEGRATION (your agent calls Faregate-metered services) ===================================================================== Step 1 — Get a key and credits (once, human): https://dash.faregate.io → API Keys → "Create key" (shown once; only a SHA-256 hash is stored) → "Add credits" ($5–$500 via Stripe Checkout; credits never expire; each key has its own balance). Step 2 — Call any metered service with the key: curl https://proxy.faregate.io/s/{service}/{path} \ -H "x-faregate-key: fg_your_key" Alternative header form: "Authorization: Bearer fg_your_key". Step 3 — Handle HTTP 402 (no key, or key out of credit). Response body: { "error": "payment_required", "faregate": { "version": 1, "service": "{slug}", "price_micro_usd": 20000, "price_display": "$0.0200", "free_tier": 25, "accepts": ["faregate_credits"], "topup_url": "https://dash.faregate.io/topup?service={slug}", "docs_url": "https://faregate.io/docs.html#the-402" } } Also sent: "www-authenticate: Faregate realm={slug}" and "x-faregate-price-micro-usd: {price}". Correct agent behavior: surface topup_url to the operator (or use the topup API below), then retry. TypeScript: import { faregateFetch, PaymentRequiredError } from "@faregate/sdk"; const ffetch = faregateFetch({ key: process.env.FAREGATE_KEY! }); try { const res = await ffetch("https://proxy.faregate.io/s/acme/search?q=x"); } catch (e) { if (e instanceof PaymentRequiredError) console.log(e.payload.topup_url); } Programmatic payments API (base https://proxy.faregate.io): GET /v1/balance Header: x-faregate-key. → 200 {"balance_micro_usd": 9940000, "balance_display": "$9.9400"} | 401 {"error":"missing_key"|"invalid_key"} POST /v1/topup/checkout JSON body: {"key": "fg_…", "amount_usd": 20} (integer 5–500) → 200 {"checkout_url": "https://checkout.stripe.com/…", "session_id": "cs_…"} Open checkout_url in a browser; on payment, credits land automatically (verified+idempotent Stripe webhook). No polling endpoint yet — re-check GET /v1/balance after the operator confirms payment. Success responses from metered calls include: x-faregate-charge: free | paid | none (none = zero-priced service) x-faregate-balance: $9.9400 (remaining credit, display form) ===================================================================== 3. ERRORS ===================================================================== 401 {"error":"invalid_key"} key unknown or revoked 402 payment_required see schema above — top up, retry 404 {"error":"unknown_service"} bad slug, or service paused by its owner 404 {"error":"not_found"} path didn't match /s/{slug}/… or /v1/… 429 (dashboard auth only) rate limited; retry after 60s 5xx from your call came from the service origin, not Faregate ===================================================================== 4. GUARANTEES & LIMITS ===================================================================== - Metering is atomic per key (strongly consistent single-writer state); a call is never double-billed and never passes without funds/free tier. - Raw keys and secrets are never stored by Faregate (hashes only). - Payments are processed by Stripe; Faregate never sees card numbers. - Free tier is per (key, service) pair, consumed before paid credit. - Price bounds: $0–$10/call. Topups: $5–$500 each. Payout minimum: $1. - The proxy adds one edge hop (Cloudflare, ~0ms typical added latency). Support: support@faregate.io — early access, answered by the engineers. Terms: https://faregate.io/terms.html · Privacy: https://faregate.io/privacy.html