diff --git a/docs.json b/docs.json index 156f16b3..b32ed73c 100644 --- a/docs.json +++ b/docs.json @@ -353,7 +353,8 @@ "info/pricing", "info/spending-caps", "info/support", - "info/unikernels" + "info/unikernels", + "info/mpp" ] } ] diff --git a/info/mpp.mdx b/info/mpp.mdx new file mode 100644 index 00000000..4e9cbc18 --- /dev/null +++ b/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 `. +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: + + + + +```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(); +``` + + + + +```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() +``` + + + + +## 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).