From 29e0022e75a20a7639289072caaf629dcb6530f9 Mon Sep 17 00:00:00 2001
From: enot <223016348+enot3615@users.noreply.github.com>
Date: Sun, 25 Oct 2026 06:00:22 -0700
Subject: [PATCH] docs(charge): a new hosted gateway forwards only after its
 upstream domain verifies

The Gateway and onboarding pages said a new gateway endpoint is live as soon
as it is saved. The gateway refuses a request with 403 gateway_unavailable
until the upstream host's TXT proof (_aifp-verify.<upstream-host>) is valid
and recent (gateway-routing.js selectGateway -> dns-state.js
gatewayReadiness). Say so, name where the record is shown, note that one
proof covers the Site URL when it shares the upstream's host, and call the
dashboard page Site settings, as the sidebar does.
---
 charge/gateway.mdx    | 19 ++++++++++++++++---
 charge/onboarding.mdx |  9 ++++++---
 2 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/charge/gateway.mdx b/charge/gateway.mdx
index 50eb6f0..6fd2d5f 100644
--- a/charge/gateway.mdx
+++ b/charge/gateway.mdx
@@ -45,10 +45,12 @@ AI agent ──(pays, AIFP-1)──▶ gateway.aifinpay.io/{your-slug}/... ─
   </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.
+    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 live immediately:
+    Your paid endpoint is:
 
     ```text
     https://gateway.aifinpay.io/acme-search/<any-path>
@@ -56,6 +58,17 @@ AI agent ──(pays, AIFP-1)──▶ gateway.aifinpay.io/{your-slug}/... ─
 
     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.
   </Step>
 
   <Step title="Lock your origin">
diff --git a/charge/onboarding.mdx b/charge/onboarding.mdx
index d086b82..959351b 100644
--- a/charge/onboarding.mdx
+++ b/charge/onboarding.mdx
@@ -18,9 +18,12 @@ no repository, no approval, no contract:
 1. Create an account and a service.
 2. Give it a payout address (a standard `0x…` EVM address; settlement is on
    Polygon today).
-3. On the **Gateway** page, pick a slug and enter your upstream URL. Your paid
-   endpoint is live immediately at `https://gateway.aifinpay.io/{your-slug}/…` —
-   that is the URL you hand to agents.
+3. On **Site settings**, add a gateway: pick a slug and enter your upstream URL.
+   Your paid endpoint is `https://gateway.aifinpay.io/{your-slug}/…` — that is
+   the URL you hand to agents. It starts forwarding once the upstream's domain
+   is verified: add the TXT record `_aifp-verify.<upstream-host>` that
+   **Site settings** shows under **Domain verification**. Until then it answers
+   `403 gateway_unavailable`.
 4. Lock your origin so agents cannot bypass the paywall. **Read
    [Hosted Gateway](/charge/gateway) before you do — the rule differs for an API
    and for a site with human readers, and using the API rule on a website will