Faregate

Documentation

Faregate puts a price on your API or MCP server. Agents pay per call from prepaid credits; you get paid out through Stripe. Integration is a URL — no billing code.

🤖 Building with an AI assistant? Point it at faregate.io/llms.txt — the entire integration (both sides, all endpoints, the signature algorithm, copy-paste code) in one plaintext file. Paste the URL into your coding session and say "integrate this."

Quickstart: monetize your API

1. Create an account at dash.faregate.io.
2. Register a service — name, slug, your origin URL, price per call, and an optional free tier. You immediately get a metered URL:

https://proxy.faregate.io/s/{your-slug}/

3. Point agents at the metered URL instead of your origin. Faregate authenticates, meters, and bills every request, then forwards it to you. Your origin never sees a request that hasn't paid (or isn't within its free tier).
4. Set up payouts in the dashboard (Stripe onboarding, ~2 minutes). Earnings transfer automatically: you keep 85% of every call, minimum payout $1, sub-cent amounts roll forward.

Quickstart: call a metered service

1. Create an API key in the dashboard (shown once — we store only a hash).
2. Add credits to the key (Stripe checkout, $5–$500; credits never expire).
3. Call any Faregate-metered service with the key header:

curl https://proxy.faregate.io/s/{service}/some/path \
  -H "x-faregate-key: fg_your_key_here"

Authorization: Bearer fg_… works too. Every response tells you what happened:

Response header	Meaning
x-faregate-charge	free (free tier), paid (credits drawn), or none (zero-priced)
x-faregate-balance	Your key's remaining credit after this call

The 402 flow

A request without credit (or without a key) gets HTTP 402 Payment Required with a machine-readable body — so an agent, or the person running it, always knows exactly how to proceed:

{
  "error": "payment_required",
  "faregate": {
    "version": 1,
    "service": "flight-search",
    "price_micro_usd": 20000,
    "price_display": "$0.0200",
    "free_tier": 25,
    "accepts": ["faregate_credits"],
    "topup_url": "https://faregate.io/topup?service=flight-search",
    "docs_url": "https://faregate.io/docs/402"
  }
}

Prices are integer micro-USD (1,000,000 µ$ = $1.00) — exact arithmetic, no floats. Handle a 402 by topping up the key, then retry.

HTTP API reference

Endpoint	Description
GET /v1/balance	Current credit for the key in x-faregate-key. Returns balance_micro_usd and balance_display.
POST /v1/topup/checkout	Body {"key": "fg_…", "amount_usd": 20} ($5–$500). Returns a Stripe checkout_url. Credits land automatically on payment.
GET /s/{slug}/*	The metered proxy itself (any method). Authenticated + billed, then forwarded to the service origin.

Base URL for all endpoints: https://proxy.faregate.io. Errors are JSON with an error field; auth failures are 401, unknown services 404, payment required 402.

Verify requests at your origin

Your metered URL forwards to your origin — so you should reject traffic that reaches the origin without going through Faregate (and its billing). Every request we forward is signed with your service's signing secret (shown when you create the service, and copyable from the Services list):

Header	Value
x-faregate-timestamp	Unix seconds when the proxy signed the request
x-faregate-signature	Hex HMAC-SHA256(secret, "{timestamp}.{METHOD}.{path+query}")

Verify by recomputing the HMAC and comparing in constant time; reject if the timestamp is more than 300 seconds off. With the SDK it's one middleware:

import { originVerifier } from "@faregate/sdk";

const verify = originVerifier({ secret: process.env.FAREGATE_SIGNING_SECRET! });

// in your handler (anything 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 })). Not on TypeScript? The algorithm above is three lines in any language — a Python reference implementation is in llms.txt.

SDK

@faregate/sdk is dependency-free TypeScript (Node 18+, Bun, Deno, Workers, browsers) covering both sides:

Export	Side	What it does
faregateFetch({ key })	Buyer	Drop-in fetch that attaches your key and throws a typed PaymentRequiredError (with the top-up URL) on 402
originVerifier({ secret })	Seller	Framework-agnostic request verification
expressVerifier / honoVerifier	Seller	One-line middleware for Express and Hono

During early access the SDK ships from the repo — email support@faregate.io for access and we'll set you up personally. The raw HTTP interface above is fully supported and identical in capability.

Using Faregate with MCP servers

MCP servers speak HTTP, so metering one is the same single step: register your MCP server's public URL as the service origin and give agents the metered URL as the server address. Calls arrive with the agent's key header; unpaid calls get the 402 payload above, which the agent can surface to its operator. Add originVerifier to the server if you want to reject unbilled direct traffic.

Security model

• Raw API keys are never stored — only SHA-256 hashes.
• Credit balances live in strongly-consistent, single-writer storage (Cloudflare Durable Objects); every spend is atomic.
• Payments are processed entirely by Stripe; Faregate never sees card numbers.
• Webhooks are signature-verified with replay protection; credits are idempotent per payment.
• Your origin URL is never exposed to callers, and credential headers are stripped before forwarding.

Support

Email support@faregate.io — during early access you're talking directly to the engineers.