> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aifinpay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted Gateway — zero code

> Put a payment gate in front of your existing API in about five minutes, entirely from the dashboard. No SDK, no bridge to host, no code changes.

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.

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

<CardGroup cols={2}>
  <Card title="Zero code" icon="wand-magic-sparkles">
    Configure everything in the dashboard: a slug and your upstream URL.
    No SDK in your stack, no process to host.
  </Card>

  <Card title="Non-custodial" icon="lock">
    Every batch settles on-chain straight to a wallet you own. AiFinPay
    never holds your funds — there is no withdraw step.
  </Card>
</CardGroup>

## What you need

| Item | Why |
| - | - |
| An email address | Dashboard sign-in is a magic link — no password. |
| 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. |

## Set it up

<Steps>
  <Step title="Sign in and create a service">
    Go to [dash.aifinpay.io](https://dash.aifinpay.io), enter your email and
    follow the magic link. Create a service: pick a name and paste your
    payout wallet (`0x…`). That wallet is where every settlement lands —
    AiFinPay never custodies it.
  </Step>

  <Step title="Configure the Gateway">
    Open the **Gateway** page. Choose a slug (lowercase, e.g. `acme-search`)
    and enter your upstream base URL (e.g. `https://api.acme.dev`). Save.

    Your paid endpoint is live immediately:

    ```text theme={null}
    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>`.
  </Step>

  <Step title="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](#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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

```text theme={null}
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

<Note>
  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.
</Note>

Nothing but agents calls it, so reject everything without the header.

**Cloudflare** — WAF custom rule, zero code:

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

**nginx**:

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

### If the origin serves pages to people

<Warning>
  **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.
</Warning>

**Cloudflare**:

```text theme={null}
(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.

<Note>
  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.
</Note>

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:

```text theme={null}
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](/pay/node), [Python](/pay/python)) or
the [MCP server](/pay/mcp) handle the whole flow automatically — one
`agent.pay(url)` call resolves the 402, pays on-chain from the agent's own
wallet and retries. 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](/integration) |
| - | - | - |
| Code changes | None | \~5 lines of [`@aifinpay/gate`](https://www.npmjs.com/package/@aifinpay/gate) |
| Traffic path | Through `gateway.aifinpay.io` | Direct to your domain |
| Receipt verification | Done by the gateway | Local, via JWKS — no network call |
| Best for | Getting live in minutes | Full control, no proxy in the path |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.