Hosted Gateway — zero code

The hosted Gateway is the fastest way to charge AI agents for an API you already run. AiFinPay proxies agent traffic to your upstream and handles the whole payment conversation — the HTTP 402 challenge, the on-chain settlement check, metering and receipts. Your API stays exactly as it is.

AI agent ──(pays, AIFP-1)──▶ gateway.aifinpay.io/{your-slug}/... ──▶ your API
                                        │
                          policy check · metering · receipts

Zero code

Configure everything in the dashboard: a slug and your upstream URL. No SDK in your stack, no process to host.

Non-custodial

Every batch settles on-chain straight to a wallet you own. AiFinPay never holds your funds — there is no withdraw step.

What you need

Item	Why
An email address	For your dashboard account: email and password, or a social sign-in such as Google.
A `0x` EVM address you control	Where revenue settles. One address receives on all supported EVM networks.
Your API’s base URL	The upstream the gateway forwards paid requests to. Must be public HTTPS.
Cloudflare or nginx in front of your API	Required. Without it an agent calls your API directly, gets the answer and pays nothing — the paywall is bypassed by not using it.
Access to your domain’s DNS	To verify your site’s domain with a TXT record. Agents using the AiFinPay MCP pay only verified sites.

Set it up

Go to dash.aifinpay.io, create an account and confirm your email. Create a service: pick a name and paste your payout wallet (0x…). That wallet is where every settlement lands — AiFinPay never custodies it.

Configure the Gateway

Open Site settings and press Add gateway. Choose a slug (lowercase, e.g. acme-search), enter your upstream base URL (e.g. https://api.acme.dev) and leave Enable after verification ticked. Press Review changes, then Apply changes.Your paid endpoint is:

https://gateway.aifinpay.io/acme-search/<any-path>

Requests to it are challenged with HTTP 402 until the agent pays; paid requests are forwarded to https://api.acme.dev/<any-path>.It starts forwarding once you verify the upstream’s domain. Until then it answers 403 gateway_unavailable, not a 402. The Domain verification card on Site settings shows the TXT record to add at your DNS provider (_aifp-verify.api.acme.dev); the DNS connection queue on the account Dashboard lists it too. Add it, then press Check DNS now. Leave the record in place: it is re-checked, and the gateway stops forwarding if it disappears.If your Site URL (under Profile & keys) is on the same host as the upstream, one record verifies both.

Lock your origin

Right now agents could still call api.acme.dev directly and skip the paywall — so nothing actually gets paid. Closing that hole takes one rule at your edge: see Lock your origin below for the Cloudflare WAF and nginx rules. Do not skip this step; without it the gateway is a suggestion rather than a paywall.

Verify your domain

Agents that pay through the AiFinPay MCP server do not pay a site until its domain is verified. Set Site URL under Profile & keys to your own domain (e.g. https://acme.dev). Then, on the account Dashboard, open the site’s Website domain row in the DNS connection queue and add the TXT record it shows (_aifp-verify.acme.dev) at your DNS provider.On the hosted gateway the agent calls gateway.aifinpay.io, so the MCP checks only that your domain is verified, not which host it is.

Watch the money arrive

That’s the whole setup. From here the dashboard does the reporting:

Transactions — every settled payment with its on-chain receipt.
Payout — your wallet, and every batch that settled to it.
Traffic Heatmap / Overview — which routes agents actually call.

A gated route with traffic but no payments yet shows as “Paywall on — no payments yet” — that’s agents receiving 402 challenges before the first one settles, not a misconfiguration.

Lock your origin

Without this the gateway can be bypassed: an agent that calls api.acme.dev directly gets your data for free. This rule is what makes the paywall real. Saving the Gateway config generated an origin secret (shown once — store it like a password). The gateway injects it into every forwarded request:

AIFP-Proxy-Auth: <your-origin-secret>

What you do with that header depends on what is behind the origin, and getting this wrong is the one mistake here that takes a site offline.

If the origin is an API

Already have your own API keys or sessions for developers and paying customers? Keep them — the lock composes: allow requests that carry your auth, allow requests that carry AIFP-Proxy-Auth, refuse the rest. Your existing users never touch the gateway; it is an additional door for agents you have never issued a key to. The blanket rule below is for an origin with no auth of its own.

Nothing but agents calls it, so reject everything without the header. Cloudflare — WAF custom rule, zero code:

(http.host eq "api.acme.dev" and not
  any(http.request.headers["aifp-proxy-auth"][*] eq "<your-origin-secret>"))
→ Block

nginx:

if ($http_aifp_proxy_auth != "<your-origin-secret>") { return 403; }

If the origin serves pages to people

Do not use the rule above on a site with human readers. Browsers reach your site directly, not through the gateway, so they do not carry the header — and neither does Googlebot. “Block everything without the secret” means every reader gets a 403 and the site drops out of search.Invert it: allow everyone by default, and block only AI crawlers that arrive without the secret.

Cloudflare:

(cf.verified_bot_category eq "AI Crawler"
 or any(lower(http.user_agent) contains
   {"gptbot" "claudebot" "perplexitybot" "ccbot" "bytespider" "google-extended"}))
and not any(http.request.headers["aifp-proxy-auth"][*] eq "<your-origin-secret>")
→ Block

An AI crawler that pays through the gateway arrives with the header and is let through; one that does not, is not. Human readers and search indexing are untouched. The limit worth knowing before you rely on it: this rule only catches crawlers Cloudflare classifies as AI, plus the user agents you list. A crawler that is neither reads your site for free, and the list needs revisiting as new ones appear. Blocking is only deterministic on a host with no human traffic — which is the argument for serving paid routes from an api. subdomain when the content allows it, and using the blanket rule there. Keep any genuinely private paths — /api/*, /login, admin panels — closed by their own rules as before. This rule is about crawlers, not authentication.

With the inverted rule, Verify lock in the dashboard will report the origin as open. That is correct and not a misconfiguration: the check requests your origin without the secret and expects to be refused, but it does not identify itself as an AI crawler, so your rule deliberately lets it through. Verify lock is meaningful for API origins; for a site with human traffic, test instead with a crawler user-agent.

Rotating is safe: Rotate secret in the dashboard keeps the previous secret valid for a short grace window, so there is no downtime. Then press Verify lock — AiFinPay calls your upstream without the secret and expects a 401/403. A green verdict means the only way in is through the paywall.

What your server receives

The gateway is a straight proxy, with three deliberate exceptions. Methods & body. Every HTTP method is forwarded — GET, POST, PUT, PATCH, DELETE. Request bodies are forwarded for everything except GET/HEAD. (Currently JSON bodies; raw binary uploads are not proxied yet — put file endpoints behind the middleware path if you need them today.) Headers in. The agent’s headers pass through unchanged, minus standard hop-by-hop headers and AiFinPay’s own control headers. Two are added, and neither can be forged from outside — any inbound copy is stripped before the real value is injected:

AIFP-Proxy-Auth: <your origin secret>   # proof the call came through the paid door
AIFP-Agent-Id:   <agent key|anonymous>  # who paid — attribution for your logs

Headers out. Your response returns to the agent with quota bookkeeping added (AIFP-Quota-Remaining) plus a signed per-action billing receipt. You may optionally answer with an AIFP-Billing header (JSON: action, category, execution_time_ms) — it is folded into that billing receipt so the agent’s statement names your action names, not just paths. Failure. Upstream timeout is 30 s; an unreachable upstream answers the agent 502. Today the quota unit for that attempt is still consumed — metering happens before the proxy call, and refund-on-failure is on the roadmap rather than in the code. Keep your upstream healthy; a flapping origin spends your agents’ batches on 502s.

How agents pay you

Agents using the AiFinPay SDK (Node, Python) or the MCP server handle the whole flow automatically — one agent.pay(url) call resolves the 402, pays on-chain from the agent’s own wallet and retries. The MCP server pays only once your domain is verified (see Set it up). To be discovered by agents you don’t already know, list your service on the Marketplace (dashboard → Marketplace → publish; a short review keeps spam out of the public catalog).

Gateway vs. self-hosted verification

	Hosted Gateway (this page)	Self-hosted middleware
Code changes	None	~5 lines of `@aifinpay/gate`
Traffic path	Through `gateway.aifinpay.io`	Direct to your domain
Receipt verification	Done by the gateway	Local, via JWKS — no network call
Domain to verify	Your Site URL, any host you own	Your Site URL; paid URLs must be on that host
Best for	Getting live in minutes	Full control, no proxy in the path

Both settle the same way: on-chain, straight to your wallet.

Get started

Pay for services

Charge for your API

Reference

Hosted Gateway — zero code

Zero code

Non-custodial

What you need

Set it up

Lock your origin

If the origin is an API

If the origin serves pages to people

What your server receives

How agents pay you

Gateway vs. self-hosted verification