Document MPP browser purchases

docs.json

@@ -353,7 +353,8 @@
               "info/pricing",
               "info/spending-caps",
               "info/support",
-              "info/unikernels"
+              "info/unikernels",
+              "info/mpp"
             ]
           }
         ]

info/mpp.mdx

@@ -0,0 +1,83 @@
+---
+title: "Buy a Browser with MPP"
+description: "buy a KERNEL browser through mpp with link"
+---
+
+[machine payments protocol (mpp)](https://mpp.dev/) is an open protocol co-authored by stripe and tempo. it uses an http `402` challenge so an agent can pay for an api request without a checkout page. KERNEL accepts mpp payments for browser sessions: an agent pays with a stripe shared payment token, then connects to the browser over cdp. this route doesn't require a KERNEL account or api key.
+
+the mpp price is $0.50 for one stealth, headful browser for 30 minutes. read the `402` challenge to confirm the current price and duration before paying.
+
+## How the mpp payment flow works
+
+1. `link-cli mpp pay` sends `POST /mpp/browsers` without a payment credential. KERNEL returns `402 Payment Required` with the offer in `WWW-Authenticate: Payment`.
+2. the link cli gives you an approval url. after you approve the payment through link, it retries the request with `Authorization: Payment <credential>`.
+3. KERNEL verifies and charges the credential, creates the browser, and returns its connection urls in a `200` response. the `Payment-Receipt` header contains the mpp receipt.
+
+link through the link cli is the only supported payment flow for now. after approval, the cli sends a credential containing a [stripe shared payment token](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) (`spt_...`) to KERNEL.
+
+you can't send card details or a standalone card credential to this endpoint, and stablecoin payments aren't offered. the payment challenge expires after 30 minutes by default; that is the time available to approve the offer, not the browser's lifetime.
+
+## Pay with link
+
+run [stripe's link cli](https://docs.stripe.com/agentic-commerce/link-cli/machine-payments) to pay through link. the command reads the `402` challenge, gives you an approval link, and completes the payment after you approve it. you don't need to create a spend request separately.
+
+```bash
+link-cli mpp pay https://api.onkernel.com/mpp/browsers --method POST
+```
+
+to inspect the offer without paying, send an unauthenticated request:
+
+```bash
+curl -i -X POST https://api.onkernel.com/mpp/browsers
+```
+
+you can send an optional `{"email":"agent@example.com"}` json body if you want the stripe receipt sent to that address. otherwise KERNEL uses the billing email shared by the payment token, if available.
+
+the paid response includes `session_id`, `cdp_ws_url`, `webdriver_ws_url`, `browser_live_view_url` when available, and `expires_at`. `payment.amount` is in us cents, and `access.type` is `session_urls`. treat the connection urls as credentials; anyone with them can access the browser while it is active.
+
+connect playwright to the returned `cdp_ws_url`. set `CDP_WS_URL` to that value from the paid response:
+
+<Tabs>
+  <Tab title="TypeScript">
+
+```typescript
+import { chromium } from "playwright";
+
+const browser = await chromium.connectOverCDP(process.env.CDP_WS_URL!);
+const page = await browser.newPage();
+await page.goto("https://example.com");
+console.log(await page.title());
+await browser.close();
+```
+
+  </Tab>
+  <Tab title="Python">
+
+```python
+import os
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as playwright:
+    browser = playwright.chromium.connect_over_cdp(os.environ["CDP_WS_URL"])
+    page = browser.new_page()
+    page.goto("https://example.com")
+    print(page.title())
+    browser.close()
+```
+
+  </Tab>
+</Tabs>
+
+## Retry and expiration
+
+a challenge buys one browser. if the paid request times out or you lose its response, retry with the **same payment credential**. KERNEL returns the same browser without another charge while it is active. don't create a new payment to recover an uncertain purchase.
+
+the paid time starts when the charge succeeds; use `expires_at` in the response as the access deadline. after expiration, a retry returns a new `402` challenge with `code: session_expired`; paying that challenge buys a new browser. if KERNEL charges you but can't create the browser, it attempts a refund. a successful refund returns a `503` error with a `refund_id`.
+
+## When to use mpp
+
+mpp is a payment protocol, not a browser feature. when a merchant exposes an mpp endpoint, an agent can pay that merchant directly without opening a checkout page. a browser is still useful when the task requires a site's interface, login, or checkout and the site doesn't expose the needed action through mpp.
+
+KERNEL's mpp endpoint handles a different purchase: **the agent pays KERNEL for browser access**. it lets an agent using the link cli acquire one browser without account setup. the purchase returns connection urls only; it doesn't provision a vault or merchant payment credential.
+
+for merchant checkout with KERNEL's wallet integrations, use [payments for browser agents](/browsers/payments) with an account-based browser. for projects, api keys, and ongoing browser management, use [account-based browser access](/introduction/create).