From 1d87d6d889c8246eaa9063ca12a3c11a4f0e4af3 Mon Sep 17 00:00:00 2001
From: Keysat <licensing@keysat.xyz>
Date: Wed, 17 Jun 2026 12:03:16 -0500
Subject: [PATCH] docs(agent): show the buyer-pays money path in connect-btcpay

Extend the programmatic connect snippet with the checkout + poll steps
(POST /v1/purchase, GET /v1/purchase/{id}) and note the purchased license
carries the policy entitlements, so it unlocks the same gate the worked
example builds. Ties connect, buyer-pays, and gate-unlock together in one
place; previously that money path lived only in the OpenAPI spec.
---
 agent.html | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/agent.html b/agent.html
index a6a94e2..89f872b 100644
--- a/agent.html
+++ b/agent.html
@@ -267,7 +267,18 @@ curl "$KS/v1/btcpay/authorize/callback?state=STATE&apiKey=BTCPAY_STORE_API_KEY"
 
 # 3. Confirm.
 curl $KS/v1/admin/btcpay/status -H "Authorization: Bearer ks_..."
-# -> { "connected": true, "store_id": "...", "base_url": "...", ... }</pre>
+# -> { "connected": true, "store_id": "...", "base_url": "...", ... }
+
+# 4. Create a buyer checkout for one of your paid products (public endpoint, no auth).
+curl -X POST $KS/v1/purchase -H "Content-Type: application/json" -d '{
+  "product": "acme-reports", "policy_slug": "pro", "buyer_email": "buyer@example.com"
+}'
+# -> { "invoice_id": "...", "checkout_url": "https://btcpay.example/i/...", ... }
+
+# 5. The buyer pays checkout_url; poll until settlement signs a license.
+curl $KS/v1/purchase/INVOICE_ID
+# -> { "status": "settled", "license_key": "LIC1-..." }</pre>
+    <p>The <code>license_key</code> a settled purchase returns carries the policy's entitlements, so it unlocks the same gate the <a href="#worked-example">worked example</a> builds. That is the full money path: connect once, then every buyer purchase self-issues a signed license.</p>
     <p>Scope the BTCPay key to exactly the store you want to connect: Keysat attaches the first store the key can see. If the store's network cannot be confirmed as non-mainnet (mainnet, a Lightning-only store, or any detection failure), the callback fails closed with a 4xx and nothing is persisted. Disconnect (<code>POST /v1/admin/btcpay/disconnect</code>) is always master-only.</p>
     <p><em>Scope required: <code>payment_providers:write</code>, on a sandbox daemon, for a non-mainnet store. The master key may connect any network on any daemon.</em></p>