diff --git a/AGENTS.md b/AGENTS.md index ec61397e..982d76be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -287,7 +287,6 @@ currency: '0x20c0000000000000000000000000000000000000', // pathUSD on Tempo 1. **Alphabetize everything** - Object properties in code examples and ### parameter headings must be alphabetically ordered 13. **Install code-groups must include npm, pnpm, and bun** - Every `:::code-group` with install commands must have all three tabs: `npm`, `pnpm`, and `bun`. Use `npm install`, `pnpm add`, and `bun add` respectively. 12. **No `// @noErrors` in twoslash** - NEVER use `// @noErrors` in twoslash code blocks. All snippets must typecheck against the installed mppx types. If a snippet fails, fix the snippet or bump the mppx version — do not suppress the error. -2. **No code-groups for variants** - Use separate ### sections under ## Usage for different usage patterns (e.g., `### With MCP Transport`), not `:::code-group` 3. **Keep descriptions concise** - One line for the intro, brief explanations for parameters 4. **Show realistic examples** - Use actual values that make sense 5. **Use `// @log:` comments** - Show expected output inline diff --git a/src/components/terminal-data.ts b/src/components/terminal-data.ts index d34b6aae..aa7987c5 100644 --- a/src/components/terminal-data.ts +++ b/src/components/terminal-data.ts @@ -148,7 +148,7 @@ export const POEM_RESULTS = [ "A stream of data onward drifts.", "No human hand to slow the pace,", "Just math and trust in empty space.", - "The escrow holds, the channel clears,", + "The reserve holds, the channel clears,", "A settlement in milliseconds, not years.", ], [ diff --git a/src/pages/_layout.tsx b/src/pages/_layout.tsx index 341a6b27..d8af440c 100644 --- a/src/pages/_layout.tsx +++ b/src/pages/_layout.tsx @@ -81,7 +81,7 @@ function MobileNav() { rel="noopener noreferrer" data-mobile-nav-item="" > - IETF Specs + IETF Specification GitHub
diff --git a/src/pages/advanced/identity.mdx b/src/pages/advanced/identity.mdx index 54cf6269..e8c4de2a 100644 --- a/src/pages/advanced/identity.mdx +++ b/src/pages/advanced/identity.mdx @@ -96,8 +96,10 @@ export async function handler(request: Request) { if (result.status === 402) return result.challenge const credential = Credential.fromRequest(request) - const pubkey = credential.source // [!code hl] - const jobId = createJob({ owner: pubkey }) // [!code hl] + // [!code hl:start] + const pubkey = credential.source + const jobId = createJob({ owner: pubkey }) + // [!code hl:end] return result.withReceipt(Response.json({ jobId })) } diff --git a/src/pages/advanced/refunds.mdx b/src/pages/advanced/refunds.mdx index 1ce77328..c2cf73f3 100644 --- a/src/pages/advanced/refunds.mdx +++ b/src/pages/advanced/refunds.mdx @@ -58,7 +58,7 @@ This gives sessions a **built-in refund mechanism**—unclaimed funds are refund participant Tempo Client->>Tempo: Deposit tokens Tempo-->>Client: Channel created - Client->>Server: Open credential + Client->>Server: Open Credential Server-->>Client: 200 OK (session established) loop Per request Client->>Server: Request + voucher diff --git a/src/pages/advanced/security.mdx b/src/pages/advanced/security.mdx index 46342a39..c9de2b53 100644 --- a/src/pages/advanced/security.mdx +++ b/src/pages/advanced/security.mdx @@ -1,9 +1,9 @@ --- -description: "Protect MPP server secrets and payment credentials. Keep MPP_SECRET_KEY server-side, never log it, and rotate it safely." +description: "Protect MPP server secrets and payment Credentials. Keep MPP_SECRET_KEY server-side, never log it, and rotate it safely." imageDescription: "Protect MPP server secrets" --- -# Security [Protect server secrets and payment credentials] +# Security [Protect server secrets and payment Credentials] The core Payment HTTP Authentication Scheme already requires TLS and treats payment Credentials and Receipts as sensitive data. This page covers the operational practices around `MPP_SECRET_KEY` and server deployments. @@ -22,7 +22,7 @@ Use your platform's secret store as the system of record—AWS Secrets Manager, Environment variables are a good delivery mechanism at runtime, but they are not a secrets management strategy by themselves. Inject `MPP_SECRET_KEY` into your process from a managed secret store instead of treating `.env` files or deployment manifests as the source of truth. -## Never log secrets or payment credentials +## Never log secrets or payment Credentials Do not log: @@ -30,7 +30,7 @@ Do not log: - `Authorization: Payment` headers - `Payment-Receipt` headers -Keep them out of error messages, debugging output, analytics, traces, and support logs. If you need observability, log stable metadata such as request IDs, challenge IDs, status codes, or payment method names instead. +Keep them out of error messages, debugging output, analytics, traces, and support logs. If you need observability, log stable metadata such as request IDs, Challenge IDs, status codes, or payment method names instead. ## Handle proxies and caches safely diff --git a/src/pages/blog/subscriptions.mdx b/src/pages/blog/subscriptions.mdx index 95816309..1a8a3b69 100644 --- a/src/pages/blog/subscriptions.mdx +++ b/src/pages/blog/subscriptions.mdx @@ -34,7 +34,7 @@ With subscriptions, the client doesn't sign every paid request, instead authoriz ## How they work -The first request activates the subscription. The server maps the request to a stable subscription key, such as a user and plan, then returns a `402` Challenge with subscription terms. The client signs a credential that authorizes a scoped access key. The server charges the first billing period, stores the subscription record, and returns the protected response with a Receipt. +The first request activates the subscription. The server maps the request to a stable subscription key, such as a user and plan, then returns a `402` Challenge with subscription terms. The client signs a Credential that authorizes a scoped access key. The server charges the first billing period, stores the subscription record, and returns the protected response with a Receipt. >Client: 200 OK + Receipt `} /> -After activation, the server can grant access without asking for another payment credential. It resolves the same subscription key, checks the stored record, validates that the request still matches the subscription terms, and returns a receipt. +After activation, the server can grant access without asking for another payment Credential. It resolves the same subscription key, checks the stored record, validates that the request still matches the subscription terms, and returns a Receipt. When a billing period ends, the server renews the subscription before granting access. You can renew during the request path, or run renewals automatically via cron or any other scheduled job. diff --git a/src/pages/extensions.mdx b/src/pages/extensions.mdx index 8d53b720..60b35e70 100644 --- a/src/pages/extensions.mdx +++ b/src/pages/extensions.mdx @@ -5,8 +5,8 @@ Third-party packages that extend MPP with new payment methods, middleware, and u | Name | Languages | Description | Link | |---|---|---|---| | `@insumermodel/mppx-condition-gate` | TypeScript, JavaScript | Condition-based access for mppx routes—free access for wallets that meet token, NFT, EAS attestation, or Farcaster ID conditions across 33 chains, returned as ECDSA-signed attestations | [npm](https://www.npmjs.com/package/@insumermodel/mppx-condition-gate) · [GitHub](https://github.com/douglasborthwick-crypto/mppx-condition-gate) | -| `mpp-inspector` | TypeScript, JavaScript | CLI toolkit to inspect, debug, and test HTTP 402 MPP endpoints—parse challenges, verify receipts, compare pricing, and dry-run payment flows | [npm](https://www.npmjs.com/package/mpp-inspector) · [GitHub](https://github.com/amgb20/MPP-Inspector) | +| `mpp-inspector` | TypeScript, JavaScript | CLI toolkit to inspect, debug, and test HTTP 402 MPP endpoints—parse Challenges, verify Receipts, compare pricing, and dry-run payment flows | [npm](https://www.npmjs.com/package/mpp-inspector) · [GitHub](https://github.com/amgb20/MPP-Inspector) | | `x402-proxy` | TypeScript, JavaScript | `curl` for MPP and x402 paid APIs—auto-pays one-shot charges and session-based streaming (per-token voucher cycling), with built-in wallet management (EVM + Solana), spend limits, and MCP stdio proxy for AI agents | [npm](https://www.npmjs.com/package/x402-proxy) · [GitHub](https://github.com/cascade-protocol/x402-proxy) | -| `@quicknode/mpp` | TypeScript, JavaScript | Extends MPP with payments on Ethereum, Base, and other EVM networks, with support for `permit2`, EIP-3009 `authorization` and `hash` credential types | [npm](https://www.npmjs.com/package/@quicknode/mpp) · [GitHub](https://github.com/quiknode-labs/mpp) | +| `@quicknode/mpp` | TypeScript, JavaScript | Extends MPP with payments on Ethereum, Base, and other EVM networks, with support for `permit2`, EIP-3009 `authorization` and `hash` Credential types | [npm](https://www.npmjs.com/package/@quicknode/mpp) · [GitHub](https://github.com/quiknode-labs/mpp) | Want to build your own? See [Custom payment methods](/payment-methods/custom). diff --git a/src/pages/guides/monetize-mcp-server.mdx b/src/pages/guides/monetize-mcp-server.mdx index e964a812..d8c112cd 100644 --- a/src/pages/guides/monetize-mcp-server.mdx +++ b/src/pages/guides/monetize-mcp-server.mdx @@ -22,7 +22,7 @@ Add per-call payments to any [MCP](https://modelcontextprotocol.io) server. When A->>S: (1) tools/call S-->>A: (2) {"error":{"code":-32042}} + Challenge Note over A: (3) Create Credential - A->>S: (4) tools/call + {"_meta":{"credential"}} + A->>S: (4) tools/call + {"_meta":{"Credential"}} S->>N: (5) Settle payment N-->>S: (6) Confirmed S-->>A: (7) {"result":{}} + Receipt @@ -36,7 +36,7 @@ Add per-call payments to any [MCP](https://modelcontextprotocol.io) server. When 6. **Network** confirms the payment 7. **Server** returns the tool result with a Receipt in `_meta` -This maps directly to the standard MPP challenge → credential → receipt flow, encoded as JSON-RPC instead of HTTP headers. See the [MCP transport spec](/protocol/transports/mcp) for the full encoding. +This maps directly to the standard MPP Challenge → Credential → Receipt flow, encoded as JSON-RPC instead of HTTP headers. See the [MCP transport spec](/protocol/transports/mcp) for the full encoding. :::info This guide uses the MCP transport, so Challenge, Credential, and Receipt data travel as native JSON in `error.data` and `_meta`. The base64url-encoded `request` and `opaque` auth-params apply to the HTTP transport. @@ -257,7 +257,7 @@ Under the hood, the MCP transport encodes MPP Challenges, Credentials, and Recei | MPP concept | MCP encoding | |---|---| -| Challenge | Error code `-32042` with challenges in `error.data` | +| Challenge | Error code `-32042` with Challenges in `error.data` | | Credential | `_meta["org.paymentauth/credential"]` on the tool call | | Receipt | `_meta["org.paymentauth/receipt"]` on the tool result | diff --git a/src/pages/guides/one-time-payments.mdx b/src/pages/guides/one-time-payments.mdx index 8de6eb25..1cc55093 100644 --- a/src/pages/guides/one-time-payments.mdx +++ b/src/pages/guides/one-time-payments.mdx @@ -144,7 +144,7 @@ $ npx mppx http://localhost:3000/api/photo ::::steps -### Install `mppx` and `hono` +## Install `mppx` and `hono` :::code-group ```bash [npm] @@ -257,7 +257,7 @@ $ npx mppx http://localhost:3000/api/photo ::::steps -### Install `mppx` +## Install `mppx` :::code-group ```bash [npm] @@ -367,7 +367,7 @@ $ npx mppx http://localhost:8787 ::::steps -### Install `mppx` and `express` +## Install `mppx` and `express` :::code-group ```bash [npm] @@ -485,7 +485,7 @@ This guide walks through using `mppx/server` directly with any [Fetch API](https ::::steps -### Install `mppx` +## Install `mppx` :::code-group ```bash [npm] diff --git a/src/pages/guides/pay-as-you-go.mdx b/src/pages/guides/pay-as-you-go.mdx index 5294da4d..fe81a114 100644 --- a/src/pages/guides/pay-as-you-go.mdx +++ b/src/pages/guides/pay-as-you-go.mdx @@ -166,7 +166,7 @@ $ npx mppx http://localhost:3000/api/sessions/photo ::::steps -### Install `mppx` and `hono` +## Install `mppx` and `hono` :::code-group ```bash [npm] @@ -296,7 +296,7 @@ $ npx mppx http://localhost:3000/api/sessions/photo ::::steps -### Install `mppx` +## Install `mppx` :::code-group ```bash [npm] @@ -420,7 +420,7 @@ $ npx mppx http://localhost:8787 ::::steps -### Install `mppx` and `express` +## Install `mppx` and `express` :::code-group ```bash [npm] @@ -555,7 +555,7 @@ This guide walks through using `mppx/server` directly with any [Fetch API](https ::::steps -### Install `mppx` +## Install `mppx` :::code-group ```bash [npm] diff --git a/src/pages/guides/split-payments.mdx b/src/pages/guides/split-payments.mdx index 748cc2f0..aa48749a 100644 --- a/src/pages/guides/split-payments.mdx +++ b/src/pages/guides/split-payments.mdx @@ -42,12 +42,14 @@ export async function handler(request: Request) { amount: '1.00', currency: '0x20c0000000000000000000000000000000000000', // pathUSD recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // seller - splits: [ // [!code hl] - { // [!code hl] - amount: '0.10', // [!code hl] - recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // platform fee // [!code hl] - }, // [!code hl] - ], // [!code hl] + // [!code hl:start] + splits: [ + { + amount: '0.10', + recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // platform fee + }, + ], + // [!code hl:end] })(request) // seller receives $0.90, platform receives $0.10 @@ -127,10 +129,12 @@ Mppx.create({ methods: [ tempo.charge({ account: provider.getAccount({ signable: true }), - expectedRecipients: [ // [!code hl] - '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // platform // [!code hl] - '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC', // referrer // [!code hl] - ], // [!code hl] + // [!code hl:start] + expectedRecipients: [ + '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // platform + '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC', // referrer + ], + // [!code hl:end] getClient: provider.getClient, }), ], @@ -150,10 +154,12 @@ Mppx.create({ methods: [ tempo.charge({ account, - expectedRecipients: [ // [!code hl] - '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // platform // [!code hl] - '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC', // referrer // [!code hl] - ], // [!code hl] + // [!code hl:start] + expectedRecipients: [ + '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // platform + '0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC', // referrer + ], + // [!code hl:end] }), ], }) diff --git a/src/pages/guides/streamed-payments.mdx b/src/pages/guides/streamed-payments.mdx index 8b566349..a8ba4f98 100644 --- a/src/pages/guides/streamed-payments.mdx +++ b/src/pages/guides/streamed-payments.mdx @@ -156,7 +156,7 @@ $ npx mppx http://localhost:3000/api/sessions/poem ::::steps -### Install `mppx` and `hono` +## Install `mppx` and `hono` :::code-group @@ -273,7 +273,7 @@ $ npx mppx http://localhost:3000/api/sessions/poem ::::steps -### Install `mppx` +## Install `mppx` :::code-group @@ -387,7 +387,7 @@ $ npx mppx http://localhost:8787 ::::steps -### Install `mppx` and `express` +## Install `mppx` and `express` :::code-group @@ -509,7 +509,7 @@ This guide walks through using `mppx/server` directly with any [Fetch API](https ::::steps -### Install `mppx` +## Install `mppx` :::code-group diff --git a/src/pages/guides/subscription-payments.mdx b/src/pages/guides/subscription-payments.mdx index 162bd88b..342edd36 100644 --- a/src/pages/guides/subscription-payments.mdx +++ b/src/pages/guides/subscription-payments.mdx @@ -218,7 +218,7 @@ export async function cancelSubscription(userId: string) { } ``` -Keep the canceled record instead of deleting it. That preserves receipts and prevents in-flight renewals from clearing the cancellation marker. +Keep the canceled record instead of deleting it. That preserves Receipts and prevents in-flight renewals from clearing the cancellation marker. ### Revoke the access key diff --git a/src/pages/guides/use-mpp-with-x402.mdx b/src/pages/guides/use-mpp-with-x402.mdx index f62e15e4..3ab01d80 100644 --- a/src/pages/guides/use-mpp-with-x402.mdx +++ b/src/pages/guides/use-mpp-with-x402.mdx @@ -303,11 +303,13 @@ const mppx = Mppx.create({ recipient: '0xYourAddress', testnet: true, }), - stripe.charge({ // [!code hl] - client: stripeClient, // [!code hl] - networkId: 'internal', // [!code hl] - paymentMethodTypes: ['card'], // [!code hl] - }), // [!code hl] + // [!code hl:start] + stripe.charge({ + client: stripeClient, + networkId: 'internal', + paymentMethodTypes: ['card'], + }), + // [!code hl:end] ], secretKey: process.env.MPP_SECRET_KEY ?? 'local-dev-secret', }) diff --git a/src/pages/intents/charge.mdx b/src/pages/intents/charge.mdx index 2080e279..5e4c62f3 100644 --- a/src/pages/intents/charge.mdx +++ b/src/pages/intents/charge.mdx @@ -11,7 +11,7 @@ import { SpecCard } from '../../components/SpecCard' # Charge [Immediate one-time payments] -The `charge` intent requests an immediate one-time payment. The client pays a fixed amount and the server settles the transaction before returning the response. This is the simplest MPP payment pattern—one request, one payment, one receipt. +The `charge` intent requests an immediate one-time payment. The client pays a fixed amount and the server settles the transaction before returning the response. This is the simplest MPP payment pattern—one request, one payment, one Receipt. ## How it works diff --git a/src/pages/overview.mdx b/src/pages/overview.mdx index 9e20af75..76b8ce8d 100644 --- a/src/pages/overview.mdx +++ b/src/pages/overview.mdx @@ -17,7 +17,7 @@ The Machine Payments Protocol (MPP) lets any client—agents, apps, or humans— MPP is built around a simple, extensible core and is neutral to the implementation of underlying payment flows and methods. - **Open standard built for the internet**—Built on an [open specification proposed to the IETF](https://paymentauth.org), not a proprietary API -- **Designed for payments**—Idempotency, security, and receipts are first-class primitives +- **Designed for payments**—Idempotency, security, and Receipts are first-class primitives - **Works with stablecoins, cards, and bank transfers**—All payment methods can be supported through one protocol and flexible control flow - **Any currency**—Transact in USD, EUR, BRL, USDC.e, BTC, or any other asset - **Composable and designed for extension**—A flexible core allows advanced flows like disputes or additional primitives like identity to be gradually introduced @@ -36,7 +36,7 @@ There is no shortage of ways to pay for things on the internet. Hundreds of paym However, the very things that make these payment flows familiar and fast for human purchasers are structural headwinds for programmatic consumption. Many have tried, but it is a consistent uphill battle to fight browser automation pipelines, visual captchas, and ever changing payment forms—all of which reduce reliability, increase latency, and bear high costs. -This is not the fault of any individual payment method or credential. This is a global problem which exists at the _interface_ level: how buyer and seller negotiate cost, supported payment methods, and ultimately transact. +This is not the fault of any individual payment method or Credential. This is a global problem which exists at the _interface_ level: how buyer and seller negotiate cost, supported payment methods, and ultimately transact. The Machine Payments Protocol addresses this gap by providing a payment interface built for programmatic access that strips away the complexity of rich checkout flows, while still providing robust security and reliability. By using MPP, you can accept payments from any client—agents, apps, or humans—and across any payment method, without complex checkout flows and integrations. diff --git a/src/pages/payment-methods/card/charge.mdx b/src/pages/payment-methods/card/charge.mdx index d23f8386..3160eaba 100755 --- a/src/pages/payment-methods/card/charge.mdx +++ b/src/pages/payment-methods/card/charge.mdx @@ -10,7 +10,7 @@ import { SpecCard } from '../../../components/SpecCard' The card implementation of the [charge](/intents/charge) intent. -The client obtains an encrypted network token from a credential issuer and sends it as a Credential. The server decrypts the token and charges the card through existing card network rails. +The client obtains an encrypted network token from a Credential issuer and sends it as a Credential. The server decrypts the token and charges the card through existing card network rails. This method is best for single API calls, content access, or one-off purchases. @@ -49,14 +49,14 @@ export async function handler(request: Request) { | --- | --- | --- | --- | | `acceptedNetworks` | `string[]` | Required | Accepted card networks | | `merchantName` | `string` | Required | Display name shown to cardholder | -| `secretKey` | `string` | Required | HMAC signing key for challenge integrity | +| `secretKey` | `string` | Required | HMAC signing key for Challenge integrity | | `gateway` | `ServerEnabler` | Required | Payment gateway for charging decrypted tokens | | `privateKey` | `string` | Required | RSA-2048 PEM for token decryption | | `billingRequired` | `boolean` | Optional | Request billing address from client | ## Client -Use `MppCard.create` to automatically handle `402` responses. The client parses the Challenge, requests an encrypted network token from the credential issuer, and retries with the Credential. +Use `MppCard.create` to automatically handle `402` responses. The client parses the Challenge, requests an encrypted network token from the Credential issuer, and retries with the Credential. For production payments, enroll a card through a tokenization provider (a secure card collection form or vault API) to obtain a `cardId`. @@ -79,7 +79,7 @@ const res = await fetch('https://api.merchant.com/data') ### Dev mode -Omit `enabler` to use the SDK's built-in dev mode. The client generates test network tokens encrypted with the server's published public key—no card enrollment or credential issuer required. +Omit `enabler` to use the SDK's built-in dev mode. The client generates test network tokens encrypted with the server's published public key—no card enrollment or Credential issuer required. ### Without polyfill diff --git a/src/pages/payment-methods/card/index.mdx b/src/pages/payment-methods/card/index.mdx index 9dc0a414..54e6f21c 100755 --- a/src/pages/payment-methods/card/index.mdx +++ b/src/pages/payment-methods/card/index.mdx @@ -37,7 +37,7 @@ $ bun add mpp-card participant SE as Server Enabler Client->>Server: (1) GET /resource Server-->>Client: (2) 402 + Challenge (amount, networks, encryption key) - Client->>CE: (3) cardId + challenge context + Client->>CE: (3) cardId + Challenge context CE-->>Client: (4) Encrypted network token (JWE) Client->>Server: (5) GET /resource + Credential (encrypted token) Server->>SE: (6) Decrypt token + charge card @@ -47,9 +47,9 @@ $ bun add mpp-card 1. **Client** requests a resource from the server. 2. **Server** responds with `402` and a Challenge containing the amount, currency, accepted card networks, and an RSA public key (`encryptionJwk`). -3. **Client** sends the card identifier and challenge context to a credential issuer. +3. **Client** sends the card identifier and Challenge context to a Credential issuer. 4. **Credential Issuer** provisions a network token, generates a cryptogram, and encrypts both as a JWE using the server's public key. The encrypted token is returned to the client. -5. **Client** retries the original request with an `Authorization: Payment` header containing the encrypted credential. +5. **Client** retries the original request with an `Authorization: Payment` header containing the encrypted Credential. 6. **Server** decrypts the token using its private key and forwards it to the payment gateway for authorization through the card network. 7. **Server** returns the resource with a `Payment-Receipt` header confirming the charge. diff --git a/src/pages/payment-methods/index.mdx b/src/pages/payment-methods/index.mdx index 9362600c..67fde61a 100644 --- a/src/pages/payment-methods/index.mdx +++ b/src/pages/payment-methods/index.mdx @@ -8,7 +8,7 @@ import { TempoMethodCard, CardMethodCard, EvmMethodCard, LightningMethodCard, Mo # Payment methods [Available methods and how to choose one] -Payment methods define how clients pay for resources protected by the Machine Payments Protocol. Each method specifies its payment rails, credential format, and verification logic. +Payment methods define how clients pay for resources protected by the Machine Payments Protocol. Each method specifies its payment rails, Credential format, and verification logic. ## Overview diff --git a/src/pages/payment-methods/lightning/charge.mdx b/src/pages/payment-methods/lightning/charge.mdx index cb4c9c4a..7b8b54b7 100644 --- a/src/pages/payment-methods/lightning/charge.mdx +++ b/src/pages/payment-methods/lightning/charge.mdx @@ -10,7 +10,7 @@ import { SpecCard } from '../../../components/SpecCard' The Lightning implementation of the [charge](/intents/charge) intent. -The server generates a fresh [BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) invoice for each request. The client pays it over the [Lightning Network](https://lightning.network) and presents the payment preimage as a credential. The server verifies `sha256(preimage) == paymentHash` locally and returns the resource with a receipt. +The server generates a fresh [BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) invoice for each request. The client pays it over the [Lightning Network](https://lightning.network) and presents the payment preimage as a Credential. The server verifies `sha256(preimage) == paymentHash` locally and returns the resource with a Receipt. This method is best for single API calls, content access, or one-off purchases. diff --git a/src/pages/payment-methods/lightning/session.mdx b/src/pages/payment-methods/lightning/session.mdx index 867bd3c8..789d44a1 100644 --- a/src/pages/payment-methods/lightning/session.mdx +++ b/src/pages/payment-methods/lightning/session.mdx @@ -33,13 +33,13 @@ Sessions fix this: one deposit, then the preimage becomes a bearer token. Every Server-->>Client: 402 + deposit invoice Client->>LN: (2) Pay deposit invoice LN-->>Client: preimage - Client->>Server: (3) GET /generate + open credential + Client->>Server: (3) GET /generate + open Credential Note over Server: Verify preimage, store session Server-->>Client: 200 OK + SSE stream - Client->>Server: (4) GET /generate + bearer credential + Client->>Server: (4) GET /generate + bearer Credential Note over Server: Verify preimage, deduct per chunk Server-->>Client: 200 OK + SSE stream - Client->>Server: (5) GET /generate + close credential + Client->>Server: (5) GET /generate + close Credential Note over Server: Refund unspent via return invoice Server-->>Client: 200 {"status":"closed"} `} /> @@ -58,11 +58,11 @@ The client authenticates subsequent requests by presenting the preimage and sess ### Top up -If the balance runs out mid-stream, the server emits a `payment-need-topup` SSE event and holds the connection open. The client pays a fresh deposit invoice and submits a `topUp` credential. The server credits the balance and resumes the stream on the original connection. The client doesn't need to replay the request. +If the balance runs out mid-stream, the server emits a `payment-need-topup` SSE event and holds the connection open. The client pays a fresh deposit invoice and submits a `topUp` Credential. The server credits the balance and resumes the stream on the original connection. The client doesn't need to replay the request. ### Close -The client submits a `close` credential. The server computes `refundSats = depositSats - spent` and pays the return invoice with the unspent balance. The session is marked closed and no further actions are accepted. +The client submits a `close` Credential. The server computes `refundSats = depositSats - spent` and pays the return invoice with the unspent balance. The session is marked closed and no further actions are accepted. :::: @@ -75,7 +75,7 @@ A typical flow for a streaming LLM API priced at 2 sats per token: 3. **Client:** pays the invoice, opens a session with the preimage + return invoice 4. **Server:** begins streaming tokens, deducting 2 sats per chunk from the session balance 5. **Server:** balance exhausted mid-stream—emits `payment-need-topup`, holds connection open -6. **Client:** pays a new deposit invoice, submits a `topUp` credential—stream resumes +6. **Client:** pays a new deposit invoice, submits a `topUp` Credential—stream resumes 7. **Client:** closes the session—server refunds unspent sats to the return invoice Everything happens locally during streaming. Verification is a single SHA-256 hash per request, and billing is an integer decrement per chunk. diff --git a/src/pages/payment-methods/monad/charge.mdx b/src/pages/payment-methods/monad/charge.mdx index 6996a0e8..ff9d8a5a 100644 --- a/src/pages/payment-methods/monad/charge.mdx +++ b/src/pages/payment-methods/monad/charge.mdx @@ -9,7 +9,7 @@ import { Cards } from 'vocs' The Monad implementation of the [charge](/intents/charge) intent. -The server issues a charge challenge describing the expected amount, currency, and recipient. The client either broadcasts an ERC-20 `transfer` and returns the transaction hash (**push** mode), or signs an ERC-3009 `transferWithAuthorization` for the server to broadcast (**pull** mode). The server verifies the transfer on-chain and returns the resource with a receipt. +The server issues a charge Challenge describing the expected amount, currency, and recipient. The client either broadcasts an ERC-20 `transfer` and returns the transaction hash (**push** mode), or signs an ERC-3009 `transferWithAuthorization` for the server to broadcast (**pull** mode). The server verifies the transfer on-chain and returns the resource with a Receipt. This method is best for fixed-price API calls, digital goods, and payments that settle directly on Monad. @@ -40,7 +40,7 @@ export async function handler(request: Request) { ### With pull mode (ERC-3009) -To accept pull mode credentials, provide an `account` so the server can broadcast `transferWithAuthorization` and pay gas: +To accept pull mode Credentials, provide an `account` so the server can broadcast `transferWithAuthorization` and pay gas: ```ts import { Mppx } from "mppx/server"; @@ -58,7 +58,7 @@ const mppx = Mppx.create({ ## Client -Use `monad.charge` with `Mppx.create` to automatically handle `402` responses. The client parses the Challenge, creates a credential (either a signed transfer or an ERC-3009 authorization), and retries with the Credential. +Use `monad.charge` with `Mppx.create` to automatically handle `402` responses. The client parses the Challenge, creates a Credential (either a signed transfer or an ERC-3009 authorization), and retries with the Credential. ```ts import { Mppx } from "mppx/client"; @@ -78,5 +78,5 @@ const response = await mppx.fetch("https://api.example.com/resource"); Monad charge supports two settlement modes: -- **Push** — the client broadcasts an ERC-20 `transfer(recipient, amount)` transaction on-chain and includes the transaction hash in the credential. The server verifies the transfer by reading `Transfer` event logs. +- **Push** — the client broadcasts an ERC-20 `transfer(recipient, amount)` transaction on-chain and includes the transaction hash in the Credential. The server verifies the transfer by reading `Transfer` event logs. - **Pull** — the client signs an ERC-3009 `transferWithAuthorization` off-chain. The server broadcasts the authorization on-chain via `transferWithAuthorization`, paying the gas. The server account does not need to match the recipient address. diff --git a/src/pages/payment-methods/solana/charge.mdx b/src/pages/payment-methods/solana/charge.mdx index 74153c83..310d4ca3 100644 --- a/src/pages/payment-methods/solana/charge.mdx +++ b/src/pages/payment-methods/solana/charge.mdx @@ -10,7 +10,7 @@ import { SpecCard } from '../../../components/SpecCard' The Solana implementation of the [charge](/intents/charge) intent. -The server issues a charge challenge describing the expected amount, currency, recipient, and Solana-specific `methodDetails`. The client either presents a signed transaction for server broadcast or presents a confirmed transaction signature. The server verifies the transfer on-chain and returns the resource with a receipt. +The server issues a charge Challenge describing the expected amount, currency, recipient, and Solana-specific `methodDetails`. The client either presents a signed transaction for server broadcast or presents a confirmed transaction signature. The server verifies the transfer on-chain and returns the resource with a Receipt. This method is best for fixed-price API calls, digital goods, and payments that settle directly on Solana. @@ -33,7 +33,7 @@ const mppx = Mppx.create({ ## Client -Use `solana.charge` with `Mppx.create` to automatically handle Solana charge challenges. +Use `solana.charge` with `Mppx.create` to automatically handle Solana charge Challenges. ```ts import { Mppx } from 'mppx/client' diff --git a/src/pages/payment-methods/solana/index.mdx b/src/pages/payment-methods/solana/index.mdx index 583155a2..b14c619b 100644 --- a/src/pages/payment-methods/solana/index.mdx +++ b/src/pages/payment-methods/solana/index.mdx @@ -38,11 +38,11 @@ Solana enables several useful capabilities for MPP: | | **Charge** | **Session** | |---|---|---| -| **Pattern** | One-time payment per request | Escrow once, pay incrementally with vouchers | +| **Pattern** | One-time payment per request | Reserve funds once, pay incrementally with vouchers | | **Latency overhead** | One transaction or confirmed signature per request | Low after open; vouchers are off-chain | | **Throughput** | Best for discrete purchases | Best for high-frequency metered usage | | **Best for** | Paid API calls, downloads, fixed-price purchases | LLM APIs, streaming, repeated calls | -| **Settlement** | Immediate on-chain transfer | Escrow on-chain, settle accepted usage later | +| **Settlement** | Immediate on-chain transfer | Reserve on-chain, settle accepted usage later | ## Intents diff --git a/src/pages/payment-methods/stellar/charge.mdx b/src/pages/payment-methods/stellar/charge.mdx index bbad1712..648bbfdc 100644 --- a/src/pages/payment-methods/stellar/charge.mdx +++ b/src/pages/payment-methods/stellar/charge.mdx @@ -12,7 +12,7 @@ The Stellar implementation of the [charge](/intents/charge) intent. The client signs a SEP-41 `transfer` invocation, and the server verifies and broadcasts the transaction on-chain. Settlement completes in ~5 seconds with deterministic finality. -Stellar charge supports two credential modes: +Stellar charge supports two Credential modes: - **Pull mode** (default): The client signs Stellar auth entries and sends the transaction XDR. The server broadcasts it. Two variants: sponsored (server holds an envelope signer and optionally wraps with a fee bump) or unsponsored (server broadcasts the transaction as-is, without modification). - **Push mode**: The client builds, signs, and broadcasts the transaction itself, then sends the transaction hash. The server polls for confirmation. @@ -101,10 +101,12 @@ const mppx = Mppx.create({ recipient: process.env.STELLAR_RECIPIENT, currency: USDC_SAC_TESTNET, network: 'stellar:testnet', - feePayer: { // [!code hl] - envelopeSigner: Keypair.fromSecret(process.env.FEE_PAYER_SECRET), // [!code hl] - feeBumpSigner: Keypair.fromSecret(process.env.FEE_BUMP_SECRET), // optional // [!code hl] - }, // [!code hl] + // [!code hl:start] + feePayer: { + envelopeSigner: Keypair.fromSecret(process.env.FEE_PAYER_SECRET), + feeBumpSigner: Keypair.fromSecret(process.env.FEE_BUMP_SECRET), // optional + }, + // [!code hl:end] }), ], }) diff --git a/src/pages/payment-methods/stellar/index.mdx b/src/pages/payment-methods/stellar/index.mdx index f6e19756..ab4734e8 100644 --- a/src/pages/payment-methods/stellar/index.mdx +++ b/src/pages/payment-methods/stellar/index.mdx @@ -86,9 +86,11 @@ const mppx = Mppx.create({ recipient: process.env.STELLAR_RECIPIENT, currency: USDC_SAC_TESTNET, network: 'stellar:testnet', - feePayer: { // [!code hl] - envelopeSigner: Keypair.fromSecret('S...'), // [!code hl] - }, // [!code hl] + // [!code hl:start] + feePayer: { + envelopeSigner: Keypair.fromSecret('S...'), + }, + // [!code hl:end] }), ], }) diff --git a/src/pages/payment-methods/stellar/session.mdx b/src/pages/payment-methods/stellar/session.mdx index 2ba381e9..8e597703 100644 --- a/src/pages/payment-methods/stellar/session.mdx +++ b/src/pages/payment-methods/stellar/session.mdx @@ -28,7 +28,7 @@ Payment channels reduce payment verification to a single contract simulation per participant Stellar Client->>Stellar: (1) Deploy channel + deposit tokens Stellar-->>Client: Channel contract created - Client->>Server: (2) Open credential (channel address) + Client->>Server: (2) Open Credential (channel address) Note over Server: Verify on-chain deposit Server-->>Client: 200 OK (session established) loop Per request diff --git a/src/pages/payment-methods/stripe/charge.mdx b/src/pages/payment-methods/stripe/charge.mdx index dd436360..36546039 100644 --- a/src/pages/payment-methods/stripe/charge.mdx +++ b/src/pages/payment-methods/stripe/charge.mdx @@ -131,10 +131,12 @@ const mppx = Mppx.create({ methods: [ stripe.charge({ client: stripeClient, - html: { // [!code hl] - createTokenUrl: '/api/create-spt', // [!code hl] - publishableKey: process.env.STRIPE_PUBLISHABLE_KEY!, // [!code hl] - }, // [!code hl] + // [!code hl:start] + html: { + createTokenUrl: '/api/create-spt', + publishableKey: process.env.STRIPE_PUBLISHABLE_KEY!, + }, + // [!code hl:end] networkId: 'internal', paymentMethodTypes: ['card'], }), diff --git a/src/pages/payment-methods/tempo/charge.mdx b/src/pages/payment-methods/tempo/charge.mdx index 7ed89830..038ac647 100644 --- a/src/pages/payment-methods/tempo/charge.mdx +++ b/src/pages/payment-methods/tempo/charge.mdx @@ -118,12 +118,14 @@ const result = await mppx.charge({ amount: "1.00", currency: "0x20c0000000000000000000000000000000000000", // pathUSD recipient: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", // seller - splits: [ // [!code hl] - { // [!code hl] - amount: "0.10", // [!code hl] - recipient: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", // platform fee // [!code hl] - }, // [!code hl] - ], // [!code hl] + // [!code hl:start] + splits: [ + { + amount: "0.10", + recipient: "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", // platform fee + }, + ], + // [!code hl:end] })(request); ``` @@ -392,11 +394,12 @@ Mppx.create({ methods: [ tempo.charge({ account: provider.getAccount({ signable: true }), + // [!code hl:start] autoSwap: { - // [!code hl] - slippage: 2, // max slippage % (default: 1) // [!code hl] - tokenIn: ["0x0000000000000000000000000000000000000001"], // [!code hl] - }, // [!code hl] + slippage: 2, // max slippage % (default: 1) + tokenIn: ["0x0000000000000000000000000000000000000001"], + }, + // [!code hl:end] getClient: provider.getClient, }), ], @@ -416,11 +419,12 @@ Mppx.create({ methods: [ tempo.charge({ account, + // [!code hl:start] autoSwap: { - // [!code hl] - slippage: 2, // max slippage % (default: 1) // [!code hl] - tokenIn: ["0x0000000000000000000000000000000000000001"], // [!code hl] - }, // [!code hl] + slippage: 2, // max slippage % (default: 1) + tokenIn: ["0x0000000000000000000000000000000000000001"], + }, + // [!code hl:end] }), ], }); diff --git a/src/pages/payment-methods/tempo/session.mdx b/src/pages/payment-methods/tempo/session.mdx index 5914c1ff..3a64c9ad 100644 --- a/src/pages/payment-methods/tempo/session.mdx +++ b/src/pages/payment-methods/tempo/session.mdx @@ -48,7 +48,7 @@ Sessions solve this by making payment a continuous, inline part of the HTTP requ participant Tempo Client->>Tempo: (1) Deposit tokens Tempo-->>Client: Session created - Client->>Server: (2) Open credential + Client->>Server: (2) Open Credential Note over Server: verify deposit Server-->>Client: 200 OK (session established) loop Per request @@ -85,7 +85,7 @@ Either party can close the channel. The server closes the precompile-backed chan :::: -## Session receipts +## Session Receipts Session Receipts differ from charge Receipts. The `reference` field contains the payment channel ID (a `bytes32` hash), not a transaction hash. The on-chain settlement transaction hash is only available after closing the channel. @@ -105,13 +105,13 @@ type SessionReceipt = { } ``` -| Field | Charge receipt | Session receipt | +| Field | Charge Receipt | Session Receipt | |-------|---------------|-----------------| | `reference` | Transaction hash | Channel ID | | `status` | `"success"` | `"success"` | | `method` | `"tempo"` | `"tempo"` | -To get the settlement transaction hash, close the channel via `session.close()` and read the `txHash` field from the returned receipt. +To get the settlement transaction hash, close the channel via `session.close()` and read the `txHash` field from the returned Receipt. ## Settlement @@ -417,11 +417,13 @@ Mppx.create({ account: provider.getAccount({ signable: true }), getClient: provider.getClient, }), - tempo.session({ // [!code hl] - account: provider.getAccount({ signable: true }), // [!code hl] - getClient: provider.getClient, // [!code hl] - maxDeposit: '1', // [!code hl] - }), // [!code hl] + // [!code hl:start] + tempo.session({ + account: provider.getAccount({ signable: true }), + getClient: provider.getClient, + maxDeposit: '1', + }), + // [!code hl:end] ], }) ``` diff --git a/src/pages/protocol/challenges.mdx b/src/pages/protocol/challenges.mdx index 098ecbdf..2ed25034 100644 --- a/src/pages/protocol/challenges.mdx +++ b/src/pages/protocol/challenges.mdx @@ -5,7 +5,7 @@ imageDescription: "Tell clients what to pay and how" # Challenges [Server-issued payment requirements] -Your server issues a **challenge** to describe the payment required for a resource. Send challenges in the `WWW-Authenticate` header using the `Payment` authentication scheme. +Your server issues a **Challenge** to describe the payment required for a resource. Send Challenges in the `WWW-Authenticate` header using the `Payment` authentication scheme. ## Structure @@ -23,7 +23,7 @@ WWW-Authenticate: Payment id="qB3wErTyU7iOpAsD9fGhJk", | Parameter | Description | |-----------|-------------| -| `id` | Unique challenge identifier, cryptographically bound to challenge parameters | +| `id` | Unique Challenge identifier, cryptographically bound to Challenge parameters | | `realm` | Protection space identifier (typically the API domain) | | `method` | Payment method identifier (such as `tempo` or `stripe`) | | `intent` | Payment intent type (such as `charge` or `session`) | @@ -33,7 +33,7 @@ WWW-Authenticate: Payment id="qB3wErTyU7iOpAsD9fGhJk", | Parameter | Description | |-----------|-------------| -| `expires` | ISO 8601 timestamp when the challenge expires | +| `expires` | ISO 8601 timestamp when the Challenge expires | | `description` | Human-readable description of what's being paid for | | `opaque` | Base64url-encoded JCS JSON for server-defined correlation data | @@ -71,7 +71,7 @@ Common fields across payment methods: | `currency` | Currency code (`usd`) or token address (`0x20c0...`) | | `recipient` | Payment destination in method-native format | -## Multiple challenges +## Multiple Challenges Servers can offer multiple payment options in a single response: @@ -81,12 +81,12 @@ WWW-Authenticate: Payment id="abc", method="tempo", ... WWW-Authenticate: Payment id="def", method="stripe", ... ``` -Clients select one based on their capabilities and submit a single credential. +Clients select one based on their capabilities and submit a single Credential. ## Challenge binding :::warning[Security requirement] -Challenges must be cryptographically bound to their parameters through the `id` field. This prevents clients from reusing a challenge ID with modified payment terms. +Challenges must be cryptographically bound to their parameters through the `id` field. This prevents clients from reusing a Challenge ID with modified payment terms. ::: Typical binding includes: @@ -99,7 +99,7 @@ Typical binding includes: For HMAC-bound IDs, the canonical input sequence is `realm | method | intent | request | expires | digest | opaque`. When `expires`, `digest`, or `opaque` is absent, use an empty string for that slot. -Use an [HMAC-bound](https://en.wikipedia.org/wiki/HMAC) challenge ID to prevent clients from reusing a challenge ID with modified payment terms. +Use an [HMAC-bound](https://en.wikipedia.org/wiki/HMAC) Challenge ID to prevent clients from reusing a Challenge ID with modified payment terms. ## Learn more diff --git a/src/pages/protocol/credentials.mdx b/src/pages/protocol/credentials.mdx index 098a5d44..8df66406 100644 --- a/src/pages/protocol/credentials.mdx +++ b/src/pages/protocol/credentials.mdx @@ -5,7 +5,7 @@ imageDescription: "Submit proof of payment with each request" # Credentials [Client-submitted payment proofs] -A **Credential** is your response to a [Challenge](/protocol/challenges), proving that you paid or authorized the payment. Send credentials in the `Authorization` header. +A **Credential** is your response to a [Challenge](/protocol/challenges), proving that you paid or authorized the payment. Send Credentials in the `Authorization` header. ## Structure @@ -13,7 +13,7 @@ A **Credential** is your response to a [Challenge](/protocol/challenges), provin Authorization: Payment eyJjaGFsbGVuZ2UiOnsiaWQiOiJxQjN3RXJUeVU3aU9wQXNEOWZHaEprIiwi... ``` -The credential is a base64url-encoded JSON object: +The Credential is a base64url-encoded JSON object: ```json { @@ -44,14 +44,14 @@ The echoed Challenge keeps the original HTTP wire values. In a Credential, `chal | `source` | Identity of the payer (address, DID, account ID) | | `payload` | Method-specific payment proof | -## Single-use credentials +## Single-use Credentials -Each credential is valid for exactly one request. When processing a credential: +Each Credential is valid for exactly one request. When processing a Credential: -1. Verify the `challenge.id` matches an outstanding challenge -2. Verify the challenge has not expired +1. Verify the `challenge.id` matches an outstanding Challenge +2. Verify the Challenge has not expired 3. Verify the payment or proof using method-specific procedures -4. Reject any replayed credentials +4. Reject any replayed Credentials ## Tempo charge payload types @@ -60,7 +60,7 @@ Tempo charge currently uses three Credential payload shapes: | `payload.type` | When the client uses it | What the server verifies | |----------------|-------------------------|--------------------------| | `transaction` | Non-zero charge in pull mode | Signed Tempo transaction before broadcast | -| `hash` | Non-zero charge in push mode | On-chain receipt for the submitted transaction | +| `hash` | Non-zero charge in push mode | On-chain Receipt for the submitted transaction | | `proof` | Zero-amount identity flow | Signed proof message over the Challenge ID with no on-chain transfer | ## Example @@ -85,7 +85,7 @@ Tempo charge currently uses three Credential payload shapes: } ``` -The server verifies the signature authorizes a transfer matching the challenge parameters, then submits the payment on-chain. +The server verifies the signature authorizes a transfer matching the Challenge parameters, then submits the payment on-chain. For zero-amount Tempo Challenges, the payload becomes `{"type":"proof","signature":"0x..."}`. The server verifies the proof against the `source` identity instead of broadcasting a transfer. diff --git a/src/pages/protocol/http-402.mdx b/src/pages/protocol/http-402.mdx index be19b9a6..84287809 100644 --- a/src/pages/protocol/http-402.mdx +++ b/src/pages/protocol/http-402.mdx @@ -12,7 +12,7 @@ MPP services return HTTP `402` Payment Required to indicate that a resource requ Respond with `402` when: - A resource requires payment as a precondition for access -- The server can provide a `Payment` challenge the client can fulfill +- The server can provide a `Payment` Challenge the client can fulfill - Payment is the primary barrier (not authentication or authorization, which would result in a `401` and then potentially an incremental `402`) ```http @@ -33,7 +33,7 @@ WWW-Authenticate: Payment id="abc123", | Client authenticated but unauthorized | `403` | | Resource doesn't exist | `404` | -MPP uses `402` consistently for all payment-related challenges, including when a credential fails validation. This differs from other HTTP authentication schemes that use `401` for failed credentials. +MPP uses `402` consistently for all payment-related Challenges, including when a Credential fails validation. This differs from other HTTP authentication schemes that use `401` for failed Credentials. ## Token authentication @@ -41,7 +41,7 @@ When a resource requires both **token** and **payment** authentication: 1. Verify authentication credentials 2. Return `401` if token authentication fails -3. Return `402` with a `Payment` challenge only after successful token authentication +3. Return `402` with a `Payment` Challenge only after successful token authentication This ordering prevents leaking payment requirements to unauthenticated clients. @@ -51,7 +51,7 @@ Store authentication tokens in an [HTTP-only cookie](https://cheatsheetseries.ow ## Error responses -Failed payment attempts return `402` with a fresh challenge and a Problem Details body: +Failed payment attempts return `402` with a fresh Challenge and a Problem Details body: ```http HTTP/1.1 402 Payment Required @@ -68,7 +68,7 @@ WWW-Authenticate: Payment id="new456", ... ``` Error types include: -- `invalid-challenge`—Unknown, expired, or already-used challenge +- `invalid-challenge`—Unknown, expired, or already-used Challenge - `malformed-credential`—Invalid base64url or bad JSON - `method-unsupported`—Method not accepted (400) - `payment-expired`—Challenge or authorization expired diff --git a/src/pages/protocol/index.mdx b/src/pages/protocol/index.mdx index d6d31814..fc4a2fb9 100644 --- a/src/pages/protocol/index.mdx +++ b/src/pages/protocol/index.mdx @@ -1,5 +1,5 @@ --- -description: "The Machine Payments Protocol standardizes HTTP 402 with an extensible challenge–credential–receipt flow that works with any payment network." +description: "The Machine Payments Protocol standardizes HTTP 402 with an extensible Challenge–Credential–Receipt flow that works with any payment network." imageDescription: "The standard for HTTP 402 machine payments" --- @@ -40,21 +40,21 @@ import { MPP uses HTTP status codes consistently to signal payment-related conditions: :::info[Consistent 402 usage] -MPP uses `402` for all payment-related challenges, including failed credential validation. This differs from other HTTP authentication schemes that use `401` for failed credentials. The distinction: +MPP uses `402` for all payment-related Challenges, including failed Credential validation. This differs from other HTTP authentication schemes that use `401` for failed Credentials. The distinction: -- **`402`** = Payment barrier (initial challenge or retry needed) +- **`402`** = Payment barrier (initial Challenge or retry needed) - **`401`** = Authentication failure unrelated to payment - **`403`** = Payment succeeded but access denied by policy ::: | Condition | Status | Response | | -------------------------------------------------- | ------------------------------------ | ------------------------------------------------ | -| Resource requires payment, no credential provided | 402 | Fresh challenge in `WWW-Authenticate` | -| Malformed credential (invalid base64url, bad JSON) | 402 | Fresh challenge + `malformed-credential` problem | -| Unknown, expired, or already-used challenge id | 402 | Fresh challenge + `invalid-challenge` problem | -| Payment proof invalid or verification failed | 402 | Fresh challenge + `verification-failed` problem | +| Resource requires payment, no Credential provided | 402 | Fresh Challenge in `WWW-Authenticate` | +| Malformed Credential (invalid base64url, bad JSON) | 402 | Fresh Challenge + `malformed-credential` problem | +| Unknown, expired, or already-used Challenge id | 402 | Fresh Challenge + `invalid-challenge` problem | +| Payment proof invalid or verification failed | 402 | Fresh Challenge + `verification-failed` problem | | Payment verified, access granted | 200 | Resource + optional `Payment-Receipt` | -| Payment verified, but policy denies access | 403 | No challenge (payment was valid) | +| Payment verified, but policy denies access | 403 | No Challenge (payment was valid) | See [HTTP 402](/protocol/http-402) for details on when to return each status code. @@ -78,8 +78,8 @@ Each payment method specifies its own `request` and `payload` schemas while shar Payment method specifications must define: 1. **Method identifier**—Unique lowercase ASCII string (for example, `tempo` or `stripe`) -2. **Request schema**—JSON structure for the `request` parameter in challenges -3. **Payload schema**—JSON structure for credential `payload` fields +2. **Request schema**—JSON structure for the `request` parameter in Challenges +3. **Payload schema**—JSON structure for Credential `payload` fields 4. **Verification procedure**—How servers validate payment proofs 5. **Settlement procedure**—How payment is finalized @@ -91,13 +91,13 @@ Payment intents describe the type of payment being requested. Common intents inc - **`session`**—Streaming payment over a payment channel - **`subscription`**—Recurring fixed payment for paid access across billing periods -Intent Specifications define: +Intent definitions in the IETF Specification define: - Required and optional `request` fields - `payload` requirements - Verification and settlement semantics -Servers can offer multiple intents in separate challenges, allowing clients to choose: +Servers can offer multiple intents in separate Challenges, allowing clients to choose: ```http WWW-Authenticate: Payment id="abc", method="tempo", intent="charge", ... @@ -107,7 +107,7 @@ WWW-Authenticate: Payment id="ghi", method="tempo", intent="subscription", ... ## Request body binding -For requests with bodies (`POST`, `PUT`, `PATCH`), servers can bind the challenge to the request body using a `digest` parameter: +For requests with bodies (`POST`, `PUT`, `PATCH`), servers can bind the Challenge to the request body using a `digest` parameter: ```http WWW-Authenticate: Payment id="...", @@ -117,13 +117,13 @@ WWW-Authenticate: Payment id="...", request="..." ``` -When a `digest` is present, clients must submit the credential with a request body whose digest matches. This prevents clients from modifying the request body after receiving the challenge. +When a `digest` is present, clients must submit the Credential with a request body whose digest matches. This prevents clients from modifying the request body after receiving the Challenge. The digest is computed per [RFC 9530](https://www.rfc-editor.org/rfc/rfc9530) Content-Digest header format. ## Error handling -Failed payment attempts return `402` with a fresh challenge and a Problem Details [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) body: +Failed payment attempts return `402` with a fresh Challenge and a Problem Details [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) body: ```json { @@ -143,7 +143,7 @@ Common error codes (full type URI: `https://paymentauth.org/problems/{code}`): | `payment-expired` | Challenge or authorization expired | | `verification-failed` | Proof invalid | | `method-unsupported` | Method not accepted | -| `malformed-credential` | Invalid credential format | +| `malformed-credential` | Invalid Credential format | | `invalid-challenge` | Challenge ID unknown, expired, or already used | Use the `Retry-After` header to indicate when clients can retry failed payments. @@ -160,7 +160,7 @@ Payment methods must provide single-use proof semantics. A payment proof can be ### Idempotency -Servers must not perform side effects (database writes, external API calls) for requests that have not been paid. The unpaid request that triggers a `402` challenge must not modify server state beyond recording the challenge itself. +Servers must not perform side effects (database writes, external API calls) for requests that have not been paid. The unpaid request that triggers a `402` Challenge must not modify server state beyond recording the Challenge itself. For non-idempotent methods (`POST`, `PUT`, `DELETE`), accept an `Idempotency-Key` header to enable safe client retries. @@ -179,11 +179,11 @@ Clients must not rely on the `description` parameter for payment verification. M ### Credential handling -Payment credentials are bearer tokens that authorize financial transactions. Servers and intermediaries must not log Payment credentials or include them in error messages, debugging output, or analytics. +Payment Credentials are bearer tokens that authorize financial transactions. Servers and intermediaries must not log Payment Credentials or include them in error messages, debugging output, or analytics. ### Caching -Payment challenges contain unique identifiers and time-sensitive payment data that must not be cached. Servers must send `Cache-Control: no-store` with `402` responses. Responses containing `Payment-Receipt` headers must include `Cache-Control: private`. +Payment Challenges contain unique identifiers and time-sensitive payment data that must not be cached. Servers must send `Cache-Control: no-store` with `402` responses. Responses containing `Payment-Receipt` headers must include `Cache-Control: private`. ## Extensibility @@ -191,7 +191,7 @@ The protocol is designed for extensibility, with simple constraints where requir ### Custom parameters -Implementations may define additional parameters in challenges: +Implementations may define additional parameters in Challenges: - Parameters must use lowercase names - Unknown parameters must be ignored by clients @@ -199,9 +199,9 @@ Implementations may define additional parameters in challenges: ### Size considerations -- Keep challenges under 8 KB -- Clients must handle challenges of at least 4 KB -- Servers must handle credentials of at least 4 KB +- Keep Challenges under 8 KB +- Clients must handle Challenges of at least 4 KB +- Servers must handle Credentials of at least 4 KB ### Internationalization @@ -220,7 +220,7 @@ import { SpecCard } from "../../components/SpecCard"; - + The full specification includes detailed ABNF grammar, security analysis, IANA considerations, and complete examples for various payment scenarios. diff --git a/src/pages/protocol/receipts.mdx b/src/pages/protocol/receipts.mdx index 31ba6cfa..9cc9a223 100644 --- a/src/pages/protocol/receipts.mdx +++ b/src/pages/protocol/receipts.mdx @@ -1,12 +1,12 @@ --- -title: "Payment receipts and verification" +title: "Payment Receipts and verification" description: "Receipts confirm successful payment in MPP. Return them in the Payment-Receipt header so clients can verify that the server accepted their Credential." -imageDescription: "Confirm payments with verifiable receipts" +imageDescription: "Confirm payments with verifiable Receipts" --- # Receipts [Server acknowledgment of successful payment] -A **Receipt** is the server's acknowledgment of successful payment. Return receipts in the `Payment-Receipt` header on successful responses. +A **Receipt** is the server's acknowledgment of successful payment. Return Receipts in the `Payment-Receipt` header on successful responses. :::info The `Payment-Receipt` header is optional. Servers typically include it for auditability, but clients don't need it for correct operation. @@ -22,7 +22,7 @@ Content-Type: application/json { "data": "Payment received." } ``` -The receipt is a base64url-encoded JSON object. +The Receipt is a base64url-encoded JSON object. ## Structure @@ -44,7 +44,7 @@ The receipt is a base64url-encoded JSON object. | Field | Description | |-------|-------------| -| `challengeId` | The challenge this receipt responds to | +| `challengeId` | The Challenge this Receipt responds to | | `method` | Payment method used | | `reference` | Method-specific payment reference (for example, transaction hash or invoice ID) | | `settlement` | Actual amount and currency settled | diff --git a/src/pages/protocol/transports/http.mdx b/src/pages/protocol/transports/http.mdx index 3851110b..90ce1c75 100644 --- a/src/pages/protocol/transports/http.mdx +++ b/src/pages/protocol/transports/http.mdx @@ -28,16 +28,16 @@ GET /api/data HTTP/1.1 Host: api.example.com ``` -###
Server
Send a payment challenge +###
Server
Send a payment Challenge -Return the `WWW-Authenticate` header with a `Payment` challenge. +Return the `WWW-Authenticate` header with a `Payment` Challenge. ```http HTTP/1.1 402 Payment Required WWW-Authenticate: Payment id="abc123", method="tempo", intent="charge", request="..." ``` -###
Client
Retry with a credential +###
Client
Retry with a Credential Send the `Authorization` header. @@ -47,9 +47,9 @@ Host: api.example.com Authorization: Payment eyJjaGFsbGVuZ2UiOnsiaWQiOiJhYmMxMjMi... ``` -###
Server
Return a receipt +###
Server
Return a Receipt -Return the `Payment-Receipt` header with a success receipt. +Return the `Payment-Receipt` header with a success Receipt. ```http HTTP/1.1 200 OK @@ -63,7 +63,7 @@ Content-Type: application/json ## Header encoding -Challenges are encoded as [auth-params](https://www.rfc-editor.org/rfc/rfc9110#section-11.2) in `WWW-Authenticate`. The `request` and `opaque` auth-params use base64url-encoded JCS JSON strings. Credentials echo those same challenge values inside the base64url-encoded `Authorization` payload, and receipts use base64url-encoded JSON in `Payment-Receipt`. +Challenges are encoded as [auth-params](https://www.rfc-editor.org/rfc/rfc9110#section-11.2) in `WWW-Authenticate`. The `request` and `opaque` auth-params use base64url-encoded JCS JSON strings. Credentials echo those same Challenge values inside the base64url-encoded `Authorization` payload, and Receipts use base64url-encoded JSON in `Payment-Receipt`. ## Full specification diff --git a/src/pages/protocol/transports/mcp.mdx b/src/pages/protocol/transports/mcp.mdx index 7aee60b3..f2954dda 100644 --- a/src/pages/protocol/transports/mcp.mdx +++ b/src/pages/protocol/transports/mcp.mdx @@ -119,7 +119,7 @@ Receipts are returned in the result `_meta`: } ``` -###
Server
Return payment challenge +###
Server
Return payment Challenge Respond with error code `-32042`: @@ -137,9 +137,9 @@ Respond with error code `-32042`: } ``` -###
Agent
Retry with credential +###
Agent
Retry with Credential -Include the credential in `_meta`: +Include the Credential in `_meta`: ```json { @@ -156,7 +156,7 @@ Include the credential in `_meta`: } ``` -###
Server
Return result with receipt +###
Server
Return result with Receipt ```json { diff --git a/src/pages/protocol/transports/websocket.mdx b/src/pages/protocol/transports/websocket.mdx index 71c71719..783702bb 100644 --- a/src/pages/protocol/transports/websocket.mdx +++ b/src/pages/protocol/transports/websocket.mdx @@ -52,18 +52,18 @@ All messages are JSON objects with an `mpp` field as a discriminator: participant S as Server C->>S: WebSocket connect C->>S: authorization (Credential) - S->>C: payment-receipt + S->>C: payment-Receipt S-->>C: message (data) S-->>C: message (data) S->>C: payment-need-voucher C->>S: authorization (top-up voucher) - S->>C: payment-receipt + S->>C: payment-Receipt S-->>C: message (data) C->>S: payment-close-request S->>C: payment-close-ready (final Receipt) `} messageColors={{ 'authorization': { light: '#16a34a', dark: '#4ade80' }, - 'payment-receipt': { light: '#16a34a', dark: '#4ade80' }, + 'payment-Receipt': { light: '#16a34a', dark: '#4ade80' }, 'payment-close-ready': { light: '#16a34a', dark: '#4ade80' }, 'payment-need-voucher': { light: '#dc2626', dark: '#f87171' }, }} /> diff --git a/src/pages/quickstart/client.mdx b/src/pages/quickstart/client.mdx index 4c9c44eb..f4d47d5d 100644 --- a/src/pages/quickstart/client.mdx +++ b/src/pages/quickstart/client.mdx @@ -74,8 +74,10 @@ const account = privateKeyToAccount('0xabc…123') ```ts twoslash import { Provider } from 'accounts' -const provider = Provider.create() // [!code hl] -await provider.request({ method: 'wallet_connect' }) // [!code hl] +// [!code hl:start] +const provider = Provider.create() +await provider.request({ method: 'wallet_connect' }) +// [!code hl:end] ``` @@ -87,9 +89,11 @@ import { Mppx, tempo } from 'mppx/client' // [!code hl] const account = privateKeyToAccount('0xabc…123') -Mppx.create({ // [!code hl] - methods: [tempo({ account })], // [!code hl] -}) // [!code hl] +// [!code hl:start] +Mppx.create({ + methods: [tempo({ account })], +}) +// [!code hl:end] ``` @@ -262,7 +266,7 @@ Use `Mppx.create` for full control over the payment flow: - Present payment UI before paying - Implement custom retry logic -- Handle credentials manually +- Handle Credentials manually @@ -330,7 +334,7 @@ if (response.status === 402) { -### Payment receipts +### Payment Receipts On success, the server returns a `Payment-Receipt` header: diff --git a/src/pages/quickstart/server.mdx b/src/pages/quickstart/server.mdx index 76858824..67d61dbc 100644 --- a/src/pages/quickstart/server.mdx +++ b/src/pages/quickstart/server.mdx @@ -29,7 +29,7 @@ Paste this into your coding agent to set up a server with `mppx` in one prompt: ## Framework mode -Use the framework-specific middleware from `mppx` to integrate payment into your server. Each middleware handles the `402` Challenge/Credential flow and attaches receipts automatically. +Use the framework-specific middleware from `mppx` to integrate payment into your server. Each middleware handles the `402` Challenge/Credential flow and attaches Receipts automatically. ::::code-group @@ -223,9 +223,9 @@ export async function handler(req: IncomingMessage, res: ServerResponse) { Non-zero Tempo charges support two transaction submission modes, determined by the client. Zero-amount charges skip transaction submission entirely and use a `proof` Credential payload instead. - **`pull` mode (default)**: the client signs the transaction and sends the serialized transaction to the server. The server broadcasts it and verifies on-chain. This enables the server to sponsor gas fees via a `feePayer`. -- **`push` mode**: the client builds, signs, and broadcasts the transaction itself (for example, via a browser wallet). It sends the transaction hash to the server, which verifies the payment by fetching the receipt. +- **`push` mode**: the client builds, signs, and broadcasts the transaction itself (for example, via a browser wallet). It sends the transaction hash to the server, which verifies the payment by fetching the Receipt. -Your server handles all three payload types automatically—no configuration required. The server inspects the credential payload type (`proof` for zero-amount Challenges, `transaction` for pull, `hash` for push) and verifies accordingly. +Your server handles all three payload types automatically—no configuration required. The server inspects the Credential payload type (`proof` for zero-amount Challenges, `transaction` for pull, `hash` for push) and verifies accordingly. If you would like to force a specific mode, you can set the `mode` parameter to `'pull'` or `'push'`. diff --git a/src/pages/sdk/go/client.mdx b/src/pages/sdk/go/client.mdx index e6199cf9..d2e7116f 100644 --- a/src/pages/sdk/go/client.mdx +++ b/src/pages/sdk/go/client.mdx @@ -49,7 +49,7 @@ When the server returns `402`, the client: - **Type:** `int64` -Explicitly set the expected chain ID. If omitted, `mpp-go` infers it from `RPCURL` when it matches a known Tempo RPC endpoint, or uses the challenge and live RPC response at runtime. +Explicitly set the expected chain ID. If omitted, `mpp-go` infers it from `RPCURL` when it matches a known Tempo RPC endpoint, or uses the Challenge and live RPC response at runtime. ### ClientID (optional) @@ -78,7 +78,7 @@ Custom RPC client instance. Takes precedence over `RPCURL`. ### RPCURL (optional) - **Type:** `string` -- **Default:** challenge chain when present, otherwise `https://rpc.tempo.xyz` +- **Default:** Challenge chain when present, otherwise `https://rpc.tempo.xyz` Tempo RPC endpoint URL. diff --git a/src/pages/sdk/index.mdx b/src/pages/sdk/index.mdx index 4a815915..d6086cd9 100644 --- a/src/pages/sdk/index.mdx +++ b/src/pages/sdk/index.mdx @@ -29,7 +29,7 @@ import { TypeScriptSdkCard, PythonSdkCard, RustSdkCard, GoSdkCard, RubySdkCard, | **Session intent** | ✓ | — | ✓ | — | — | | **Stripe method** | ✓ | ✓ | ✓ | — | ✓ | | **Fee sponsorship** | ✓ | ✓ | ✓ | ✓ | ✓ | -| **Proof credentials** | ✓ | ✓ | ✓ | ✓ | ✓ | +| **Proof Credentials** | ✓ | ✓ | ✓ | ✓ | ✓ | | **MCP support** | ✓ | ✓ | ✓ | — | ✓ | | **Framework middleware** | Next.js, Hono, Express, Elysia | FastAPI | Axum, Tower | net/http, Gin, Echo, Chi | Rack | | **HTTP transport** | fetch polyfill | httpx transport | reqwest-middleware | http.RoundTripper | async-http | diff --git a/src/pages/sdk/ruby/client.mdx b/src/pages/sdk/ruby/client.mdx index a1dd0013..832d7799 100644 --- a/src/pages/sdk/ruby/client.mdx +++ b/src/pages/sdk/ruby/client.mdx @@ -98,7 +98,7 @@ account = Mpp::Methods::Tempo::Account.from_env ## Credential modes -The Tempo method supports three credential modes: +The Tempo method supports three Credential modes: ```ruby # Pull mode (default): Server broadcasts transaction diff --git a/src/pages/sdk/ruby/index.mdx b/src/pages/sdk/ruby/index.mdx index cf6238d1..37a86177 100644 --- a/src/pages/sdk/ruby/index.mdx +++ b/src/pages/sdk/ruby/index.mdx @@ -69,7 +69,7 @@ end Set `MPP_SECRET_KEY` in your environment before you start the server, or pass `secret_key` explicitly to `Mpp.create()`. -### Client +## Client ```ruby [client.rb] require "mpp-rb" diff --git a/src/pages/sdk/rust/client.mdx b/src/pages/sdk/rust/client.mdx index ffc2b8d0..e4a9f6ae 100644 --- a/src/pages/sdk/rust/client.mdx +++ b/src/pages/sdk/rust/client.mdx @@ -115,7 +115,7 @@ let client = ClientBuilder::new(reqwest::Client::new()) ## Multiple providers -`MultiProvider` wraps multiple payment providers and picks the right one based on the challenge's `method` and `intent`: +`MultiProvider` wraps multiple payment providers and picks the right one based on the Challenge's `method` and `intent`: ```rust use mpp::client::{MultiProvider, TempoProvider}; diff --git a/src/pages/sdk/rust/core.mdx b/src/pages/sdk/rust/core.mdx index 53d4a874..e9f5d457 100644 --- a/src/pages/sdk/rust/core.mdx +++ b/src/pages/sdk/rust/core.mdx @@ -38,7 +38,7 @@ println!("Amount: {}", request.amount); ## Create a Credential -Build a `PaymentCredential` from a challenge echo and payment proof: +Build a `PaymentCredential` from a Challenge echo and payment proof: ```rust use mpp::{PaymentCredential, PaymentPayload, format_authorization}; @@ -79,11 +79,11 @@ let header = format_receipt(&receipt)?; | Type | Description | |------|-------------| -| `PaymentChallenge` | Server challenge parsed from `WWW-Authenticate` | -| `PaymentCredential` | Client credential for the `Authorization` header | +| `PaymentChallenge` | Server Challenge parsed from `WWW-Authenticate` | +| `PaymentCredential` | Client Credential for the `Authorization` header | | `PaymentPayload` | Payment proof—either `transaction` (signed tx) or `hash` (tx hash) | -| `ChallengeEcho` | Echoed challenge fields in a Credential | -| `Receipt` | Server receipt parsed from `Payment-Receipt` | +| `ChallengeEcho` | Echoed Challenge fields in a Credential | +| `Receipt` | Server Receipt parsed from `Payment-Receipt` | | `ChargeRequest` | Decoded charge intent request data | | `SessionRequest` | Decoded session intent request data | | `Base64UrlJson` | JSON value encoded as base64url | diff --git a/src/pages/sdk/rust/server.mdx b/src/pages/sdk/rust/server.mdx index b2d1ba2c..227375ab 100644 --- a/src/pages/sdk/rust/server.mdx +++ b/src/pages/sdk/rust/server.mdx @@ -180,7 +180,7 @@ Override the server-level fee sponsorship setting for this Challenge. ## Verify a Credential -`verify_credential` decodes the charge request from the echoed challenge automatically—no need to reconstruct the request: +`verify_credential` decodes the charge request from the echoed Challenge automatically—no need to reconstruct the request: ```rust let receipt = mpp.verify_credential(&credential).await?; @@ -236,7 +236,7 @@ Server handlers run inline with verification. Keep the returned subscription han ## Axum extractor -The `MppCharge` extractor handles the full `402` challenge/verify flow automatically. Requires the `axum` feature. +The `MppCharge` extractor handles the full `402` Challenge/verify flow automatically. Requires the `axum` feature. Define a `ChargeConfig` type for each price point: @@ -297,7 +297,7 @@ let challenge = mpp.session_challenge_with_details( )?; ``` -Verify session credentials (vouchers): +Verify session Credentials (vouchers): ```rust let result = mpp.verify_session(&credential).await?; diff --git a/src/pages/sdk/typescript/Html.init.mdx b/src/pages/sdk/typescript/Html.init.mdx index 5a3d4130..0eaef363 100644 --- a/src/pages/sdk/typescript/Html.init.mdx +++ b/src/pages/sdk/typescript/Html.init.mdx @@ -5,7 +5,7 @@ imageDescription: "Build custom payment UIs with typed context and theming" # `Html.init` [Initialize a payment UI context] -Sets up a context for building payment method UIs in the browser. Returns challenge data, theme tokens, and helpers for error handling and credential submission. +Sets up a context for building payment method UIs in the browser. Returns Challenge data, theme tokens, and helpers for error handling and Credential submission. For a full guide on adding HTML support to a custom payment method, see [Custom HTML](/sdk/typescript/html/custom). @@ -22,9 +22,9 @@ button.textContent = context.text.pay context.root.appendChild(button) ``` -### With credential submission +### With Credential submission -Build a complete payment form that handles errors and submits credentials. +Build a complete payment form that handles errors and submits Credentials. ```ts [example.ts] import * as Html from 'mppx/html' @@ -119,7 +119,7 @@ type Context = { - **Type:** `string` -The payment method name to initialize (for example, `'tempo'`, `'stripe'`). Matches against the challenge data the server embeds in the page. +The payment method name to initialize (for example, `'tempo'`, `'stripe'`). Matches against the Challenge data the server embeds in the page. ## Context properties @@ -127,7 +127,7 @@ The payment method name to initialize (for example, `'tempo'`, `'stripe'`). Matc - **Type:** `Challenge` -The parsed Challenge object for this payment method. Contains `intent`, `method`, `realm`, `request`, and other challenge fields. +The parsed Challenge object for this payment method. Contains `intent`, `method`, `realm`, `request`, and other Challenge fields. ### config @@ -163,7 +163,7 @@ The DOM element to mount your payment UI into. Append your form elements here. - **Type:** `(credential: string) => Promise` -Sends the credential to the server via a Service Worker, then reloads the page. Call after creating a credential from the challenge. +Sends the Credential to the server via a Service Worker, then reloads the page. Call after creating a Credential from the Challenge. ### text diff --git a/src/pages/sdk/typescript/Method.from.mdx b/src/pages/sdk/typescript/Method.from.mdx index 0877a21f..21db54a4 100644 --- a/src/pages/sdk/typescript/Method.from.mdx +++ b/src/pages/sdk/typescript/Method.from.mdx @@ -52,7 +52,7 @@ Payment method name (for example, `"tempo"`, `"stripe"`). ### schema -##### credential.payload +#### Credential.payload - **Type:** `z.ZodMiniType` diff --git a/src/pages/sdk/typescript/cli.mdx b/src/pages/sdk/typescript/cli.mdx index dbf77847..10231b2e 100644 --- a/src/pages/sdk/typescript/cli.mdx +++ b/src/pages/sdk/typescript/cli.mdx @@ -109,7 +109,7 @@ $ mppx init --force ## Sign command -Sign a payment Challenge and output the `Authorization` header value without making a request. Accepts a challenge via `--challenge` or stdin. +Sign a payment Challenge and output the `Authorization` header value without making a request. Accepts a Challenge via `--challenge` or stdin. ```bash [terminal] $ mppx sign --challenge 'Payment method="tempo-session";chain-id=4217;...' diff --git a/src/pages/sdk/typescript/client/Fetch.from.mdx b/src/pages/sdk/typescript/client/Fetch.from.mdx index 1272c26e..d1f7c9a8 100644 --- a/src/pages/sdk/typescript/client/Fetch.from.mdx +++ b/src/pages/sdk/typescript/client/Fetch.from.mdx @@ -148,4 +148,4 @@ Array of payment methods to use for `402` responses. - **Type:** `(challenge, helpers) => Promise` -Called after a `402` Challenge is selected and before the wrapper retries the request. Return a Credential string to override the default credential flow. +Called after a `402` Challenge is selected and before the wrapper retries the request. Return a Credential string to override the default Credential flow. diff --git a/src/pages/sdk/typescript/client/Method.stripe.charge.mdx b/src/pages/sdk/typescript/client/Method.stripe.charge.mdx index 2dba9b2e..55e94f4c 100644 --- a/src/pages/sdk/typescript/client/Method.stripe.charge.mdx +++ b/src/pages/sdk/typescript/client/Method.stripe.charge.mdx @@ -63,7 +63,7 @@ const method = stripe.charge({ - **Type:** `(params: OnChallengeParameters) => Promise` -Callback invoked when a Stripe challenge is received. Must return an SPT token string (`spt_...`). Typically proxied through a server endpoint since SPT creation requires a Stripe secret key. +Callback invoked when a Stripe Challenge is received. Must return an SPT token string (`spt_...`). Typically proxied through a server endpoint since SPT creation requires a Stripe secret key. The callback receives: @@ -88,7 +88,7 @@ Client reference ID included in the Credential payload. - **Type:** `string` -Default Stripe payment method ID (for example `pm_card_visa`). Overridden by `context.paymentMethod` at credential-creation time. +Default Stripe payment method ID (for example `pm_card_visa`). Overridden by `context.paymentMethod` at Credential-creation time. ```ts twoslash diff --git a/src/pages/sdk/typescript/client/Method.tempo.session-manager.mdx b/src/pages/sdk/typescript/client/Method.tempo.session-manager.mdx index 691e167e..87d4db49 100644 --- a/src/pages/sdk/typescript/client/Method.tempo.session-manager.mdx +++ b/src/pages/sdk/typescript/client/Method.tempo.session-manager.mdx @@ -526,7 +526,7 @@ type StoredSessionChannel = { | `cumulativeAmount` | Latest local cumulative voucher authorization in raw token units. | | `deposit` | Latest known deposit in raw token units. | | `descriptor` | TIP-1034 descriptor used if the server cannot provide a snapshot. | -| `escrow` | Escrow precompile address used to derive the channel ID. | +| `escrow` | Reserve precompile address used to derive the channel ID. | | `chainId` | Tempo chain ID used to derive the channel ID and voucher domain. | | `opened` | Whether the channel was open when stored. Closed channels are ignored. | | `updatedAt` | Client timestamp for debugging or app-level eviction. | @@ -577,7 +577,7 @@ type PaymentResponse = Response & { ### `SessionManagerSseOptions` -`session.sse()` accepts standard `RequestInit` fields plus receipt and cancellation hooks. +`session.sse()` accepts standard `RequestInit` fields plus Receipt and cancellation hooks. ```ts type SessionManagerSseOptions = RequestInit & { @@ -624,22 +624,22 @@ type SessionManagedWebSocket = { | Status | Meaning | |---|---| -| `idle` | No session challenge has been handled yet. | +| `idle` | No session Challenge has been handled yet. | | `challenged` | A `tempo/session` Challenge was selected. | | `hydrating` | A server snapshot is being used to restore a reusable channel. | -| `opening` | An opening channel credential is being created or submitted. | +| `opening` | An opening channel Credential is being created or submitted. | | `active` | Channel is open or hydrated and can sign vouchers. | | `voucherNeeded` | Server requested a larger voucher and no top-up is required. | | `toppingUp` | Server-requested cumulative spend exceeds current deposit. | | `settling` | Accepted voucher spend is being settled on-chain. | | `closeRequested` | Unilateral close has been requested and withdrawal is not yet available. | | `withdrawable` | Close delay elapsed and funds can be withdrawn. | -| `closing` | Cooperative close credential or close transaction is in flight. | +| `closing` | Cooperative close Credential or close transaction is in flight. | | `closed` | Channel close finalized. | ### `SessionReceipt` -The receipt returned by `session.close()` and available on `PaymentResponse.receipt`: +The Receipt returned by `session.close()` and available on `PaymentResponse.receipt`: ```ts type SessionReceipt = { @@ -658,7 +658,7 @@ type SessionReceipt = { ``` :::info -The `reference` field contains the channel ID, not a transaction hash. To get the settlement transaction hash, read `txHash` from the receipt returned by `session.close()`. +The `reference` field contains the channel ID, not a transaction hash. To get the settlement transaction hash, read `txHash` from the Receipt returned by `session.close()`. ::: ## Parameters diff --git a/src/pages/sdk/typescript/client/Method.tempo.session.mdx b/src/pages/sdk/typescript/client/Method.tempo.session.mdx index 980a1e0a..561fd217 100644 --- a/src/pages/sdk/typescript/client/Method.tempo.session.mdx +++ b/src/pages/sdk/typescript/client/Method.tempo.session.mdx @@ -269,7 +269,7 @@ Called whenever channel state changes. ## Credential context -Most clients should omit context and let `tempo.session()` open, recover, top up, and voucher automatically from server Challenges. Advanced callers can pass context to `method.createCredential()` for manual credentials or per-call overrides. +Most clients should omit context and let `tempo.session()` open, recover, top up, and voucher automatically from server Challenges. Advanced callers can pass context to `method.createCredential()` for manual Credentials or per-call overrides. ```ts type SessionContext = { @@ -288,13 +288,13 @@ type SessionContext = { | Field | Description | |---|---| -| `account` | Account override for this credential only. | -| `action` | Manual credential action. Omit for automatic session management. | +| `account` | Account override for this Credential only. | +| `action` | Manual Credential action. Omit for automatic session management. | | `channelId` | Channel ID to reuse or manually operate on. | -| `descriptor` | TIP-1034 descriptor required for recovery and manual credentials. | -| `transaction` | Signed Tempo transaction for manual `open` or `topUp` credentials. | +| `descriptor` | TIP-1034 descriptor required for recovery and manual Credentials. | +| `transaction` | Signed Tempo transaction for manual `open` or `topUp` Credentials. | | `cumulativeAmount` | Human-readable cumulative voucher authorization, parsed with `decimals`. | | `cumulativeAmountRaw` | Raw cumulative voucher authorization. Takes precedence over `cumulativeAmount`. | | `additionalDeposit` | Human-readable top-up amount, parsed with `decimals`. | | `additionalDepositRaw` | Raw top-up amount. Takes precedence over `additionalDeposit`. | -| `depositRaw` | Raw opening deposit override for automatic open credentials. | +| `depositRaw` | Raw opening deposit override for automatic open Credentials. | diff --git a/src/pages/sdk/typescript/client/Mppx.create.mdx b/src/pages/sdk/typescript/client/Mppx.create.mdx index 52dee7ef..c2d11b33 100644 --- a/src/pages/sdk/typescript/client/Mppx.create.mdx +++ b/src/pages/sdk/typescript/client/Mppx.create.mdx @@ -140,8 +140,10 @@ const mppx = Mppx.create({ polyfill: false, // [!code hl] }) -// Use the returned fetch // [!code hl] -const res = await mppx.fetch('https://mpp.dev/api/ping/paid') // [!code hl] +// [!code hl:start] +// Use the returned fetch +const res = await mppx.fetch('https://mpp.dev/api/ping/paid') +// [!code hl:end] ``` @@ -158,14 +160,16 @@ const mppx = Mppx.create({ polyfill: false, // [!code hl] }) -// Use the returned fetch // [!code hl] -const res = await mppx.fetch('https://mpp.dev/api/ping/paid') // [!code hl] +// [!code hl:start] +// Use the returned fetch +const res = await mppx.fetch('https://mpp.dev/api/ping/paid') +// [!code hl:end] ``` -### Manual credential handling +### Manual Credential handling For full control over the payment flow: @@ -368,10 +372,10 @@ Payment hooks are for logging, monitoring, tracing, and request-local context. E | `onChallengeReceived` | A `402` Challenge is selected | | `onCredentialCreated` | A Credential is created for the selected Challenge | | `onPaymentResponse` | The retry after payment returns a successful response | -| `onPaymentFailed` | Challenge parsing, credential creation, or retry handling fails | +| `onPaymentFailed` | Challenge parsing, Credential creation, or retry handling fails | | `on('*', handler)` | Any client payment event fires | -`onChallengeReceived` runs before `onChallenge`. It can return a non-empty Credential string to override the default credential flow. Other hooks are observers: thrown errors are ignored and don't change payment handling. +`onChallengeReceived` runs before `onChallenge`. It can return a non-empty Credential string to override the default Credential flow. Other hooks are observers: thrown errors are ignored and don't change payment handling. @@ -577,7 +581,7 @@ const mppx = Mppx.create({ - **Type:** `(challenge: Challenge, helpers: { createCredential: (context?) => Promise }) => Promise` -Called when a `402` challenge is received, before credential creation. Return a credential string to use it directly, or `undefined` to fall back to the default credential flow. +Called when a `402` Challenge is received, before Credential creation. Return a Credential string to use it directly, or `undefined` to fall back to the default Credential flow. @@ -818,7 +822,7 @@ const mppx = Mppx.create({ -## Manual credential options +## Manual Credential options ### acceptPayment (optional) @@ -831,7 +835,7 @@ Request-local method preference override for `mppx.createCredential(response, co - **Type:** `Transport` - **Default:** `Transport.http()` -Transport to use for extracting challenges and attaching credentials. +Transport to use for extracting Challenges and attaching Credentials. diff --git a/src/pages/sdk/typescript/client/Transport.from.mdx b/src/pages/sdk/typescript/client/Transport.from.mdx index 02fff304..da56ac9c 100644 --- a/src/pages/sdk/typescript/client/Transport.from.mdx +++ b/src/pages/sdk/typescript/client/Transport.from.mdx @@ -45,7 +45,7 @@ type Transport = { - **Type:** `(response: Response) => Challenge` -Function that extracts the challenge from a payment-required response. +Function that extracts the Challenge from a payment-required response. ### isPaymentRequired @@ -63,4 +63,4 @@ Transport name for identification. - **Type:** `(request: Request, credential: string) => Request` -Function that attaches a credential to a request. +Function that attaches a Credential to a request. diff --git a/src/pages/sdk/typescript/client/Transport.http.mdx b/src/pages/sdk/typescript/client/Transport.http.mdx index dd3344b8..79be3cd8 100644 --- a/src/pages/sdk/typescript/client/Transport.http.mdx +++ b/src/pages/sdk/typescript/client/Transport.http.mdx @@ -46,8 +46,8 @@ const mppx = Mppx.create({ ## Behavior - Detects payment required using the **`402` status code** -- Extracts challenges from the **`WWW-Authenticate` header** -- Sends credentials using the **`Authorization` header** +- Extracts Challenges from the **`WWW-Authenticate` header** +- Sends Credentials using the **`Authorization` header** ## Return type diff --git a/src/pages/sdk/typescript/client/Transport.mcp.mdx b/src/pages/sdk/typescript/client/Transport.mcp.mdx index 83e14063..a709b4de 100644 --- a/src/pages/sdk/typescript/client/Transport.mcp.mdx +++ b/src/pages/sdk/typescript/client/Transport.mcp.mdx @@ -46,8 +46,8 @@ const mppx = Mppx.create({ ## Behavior - Detects payment required using **error code `-32042`** -- Extracts challenges from **`error.data.challenges[0]`** -- Sends credentials using **`_meta["org.paymentauth/credential"]`** +- Extracts Challenges from **`error.data.challenges[0]`** +- Sends Credentials using **`_meta["org.paymentauth/credential"]`** ## Return type diff --git a/src/pages/sdk/typescript/core/Challenge.deserialize.mdx b/src/pages/sdk/typescript/core/Challenge.deserialize.mdx index 6c6a7768..022ecd9e 100644 --- a/src/pages/sdk/typescript/core/Challenge.deserialize.mdx +++ b/src/pages/sdk/typescript/core/Challenge.deserialize.mdx @@ -1,6 +1,6 @@ # `Challenge.deserialize` [Deserialize a Challenge from a header] -Deserializes a WWW-Authenticate header value to a challenge. +Deserializes a WWW-Authenticate header value to a Challenge. ## Usage diff --git a/src/pages/sdk/typescript/core/Challenge.from.mdx b/src/pages/sdk/typescript/core/Challenge.from.mdx index fce3e2c2..b3d5bca5 100644 --- a/src/pages/sdk/typescript/core/Challenge.from.mdx +++ b/src/pages/sdk/typescript/core/Challenge.from.mdx @@ -1,8 +1,8 @@ # `Challenge.from` [Create a new Challenge] -Creates a challenge from the given parameters. +Creates a Challenge from the given parameters. -If `secretKey` option is provided, the challenge ID is computed as HMAC-SHA256 over the challenge parameters (realm|method|intent|request|expires|digest|opaque), cryptographically binding the ID to its contents. When `expires`, `digest`, or `opaque` is absent, that slot is an empty string. +If `secretKey` option is provided, the Challenge ID is computed as HMAC-SHA256 over the Challenge parameters (realm|method|intent|request|expires|digest|opaque), cryptographically binding the ID to its contents. When `expires`, `digest`, or `opaque` is absent, that slot is an empty string. Load `secretKey` from your server environment or secret manager. Do not ship it to clients. @@ -27,7 +27,7 @@ const challenge = Challenge.from( ### With explicit ID -Use an explicit ID when you don't need HMAC-bound challenge verification. +Use an explicit ID when you don't need HMAC-bound Challenge verification. ```ts twoslash import { Challenge } from 'mppx' @@ -47,7 +47,7 @@ const challenge = Challenge.from({ type ReturnType = Challenge ``` -A challenge object. +A Challenge object. ## Parameters @@ -73,7 +73,7 @@ Expiration timestamp (ISO 8601). - **Type:** `string` -Explicit challenge ID. +Explicit Challenge ID. ### intent @@ -113,4 +113,4 @@ Method-specific request data. `mppx` serializes it as base64url-encoded JCS JSON - **Type:** `string` -Server secret for HMAC-bound challenge ID. Keep it server-side and load it from your environment or secret manager. +Server secret for HMAC-bound Challenge ID. Keep it server-side and load it from your environment or secret manager. diff --git a/src/pages/sdk/typescript/core/Challenge.fromHeaders.mdx b/src/pages/sdk/typescript/core/Challenge.fromHeaders.mdx index 06c8ad2a..7f460978 100644 --- a/src/pages/sdk/typescript/core/Challenge.fromHeaders.mdx +++ b/src/pages/sdk/typescript/core/Challenge.fromHeaders.mdx @@ -1,6 +1,6 @@ # `Challenge.fromHeaders` [Extract a Challenge from Headers] -Extracts the challenge from a Headers object. +Extracts the Challenge from a Headers object. ## Usage @@ -29,7 +29,7 @@ const challenge = Challenge.fromHeaders(response.headers, { methods: [Methods.ch type ReturnType = Challenge ``` -The deserialized challenge object. +The deserialized Challenge object. ## Parameters diff --git a/src/pages/sdk/typescript/core/Challenge.fromMethod.mdx b/src/pages/sdk/typescript/core/Challenge.fromMethod.mdx index f1c1ebfe..d4d4a5cb 100644 --- a/src/pages/sdk/typescript/core/Challenge.fromMethod.mdx +++ b/src/pages/sdk/typescript/core/Challenge.fromMethod.mdx @@ -59,7 +59,7 @@ Expiration timestamp (ISO 8601). - **Type:** `string` -Explicit challenge ID. +Explicit Challenge ID. ### meta (optional) @@ -93,4 +93,4 @@ Method-specific request data, validated against the method's schema. `mppx` seri - **Type:** `string` -Server secret for HMAC-bound challenge ID. Keep it server-side and load it from your environment or secret manager. +Server secret for HMAC-bound Challenge ID. Keep it server-side and load it from your environment or secret manager. diff --git a/src/pages/sdk/typescript/core/Challenge.fromResponse.mdx b/src/pages/sdk/typescript/core/Challenge.fromResponse.mdx index 0230220b..f73a1c2b 100644 --- a/src/pages/sdk/typescript/core/Challenge.fromResponse.mdx +++ b/src/pages/sdk/typescript/core/Challenge.fromResponse.mdx @@ -1,6 +1,6 @@ # `Challenge.fromResponse` [Extract a Challenge from a Response] -Extracts the challenge from a Response's WWW-Authenticate header. +Extracts the Challenge from a Response's WWW-Authenticate header. ## Usage @@ -33,7 +33,7 @@ if (response.status === 402) { type ReturnType = Challenge ``` -The deserialized challenge object. +The deserialized Challenge object. ## Parameters diff --git a/src/pages/sdk/typescript/core/Challenge.serialize.mdx b/src/pages/sdk/typescript/core/Challenge.serialize.mdx index a786cf4f..3a080ee9 100644 --- a/src/pages/sdk/typescript/core/Challenge.serialize.mdx +++ b/src/pages/sdk/typescript/core/Challenge.serialize.mdx @@ -1,6 +1,6 @@ # `Challenge.serialize` [Serialize a Challenge to a header] -Serializes a challenge to the WWW-Authenticate header format. +Serializes a Challenge to the WWW-Authenticate header format. ## Usage @@ -35,4 +35,4 @@ The serialized string includes optional fields when present: `description`, `dig - **Type:** `Challenge` -The challenge to serialize. +The Challenge to serialize. diff --git a/src/pages/sdk/typescript/core/Challenge.verify.mdx b/src/pages/sdk/typescript/core/Challenge.verify.mdx index 5bea87d5..83927ee2 100644 --- a/src/pages/sdk/typescript/core/Challenge.verify.mdx +++ b/src/pages/sdk/typescript/core/Challenge.verify.mdx @@ -1,6 +1,6 @@ # `Challenge.verify` [Verify a Challenge HMAC] -Verifies that a challenge ID matches the expected HMAC for the given parameters. +Verifies that a Challenge ID matches the expected HMAC for the given parameters. Use the same server-managed secret that produced the Challenge ID. @@ -29,7 +29,7 @@ const isValid = Challenge.verify(challenge, { secretKey }) type ReturnType = boolean ``` -`true` if the challenge ID is valid, `false` otherwise. +`true` if the Challenge ID is valid, `false` otherwise. ## Parameters @@ -37,7 +37,7 @@ type ReturnType = boolean - **Type:** `Challenge` -The challenge to verify. +The Challenge to verify. ### options @@ -45,4 +45,4 @@ The challenge to verify. - **Type:** `string` -Server secret for HMAC-bound challenge ID verification. Keep it server-side and load it from your environment or secret manager. +Server secret for HMAC-bound Challenge ID verification. Keep it server-side and load it from your environment or secret manager. diff --git a/src/pages/sdk/typescript/core/Credential.deserialize.mdx b/src/pages/sdk/typescript/core/Credential.deserialize.mdx index e8161945..20df3d76 100644 --- a/src/pages/sdk/typescript/core/Credential.deserialize.mdx +++ b/src/pages/sdk/typescript/core/Credential.deserialize.mdx @@ -1,6 +1,6 @@ # `Credential.deserialize` [Deserialize a Credential from a header] -Deserializes an Authorization header value to a credential. +Deserializes an Authorization header value to a Credential. ## Usage @@ -17,7 +17,7 @@ const credential = Credential.deserialize(header) type ReturnType = Credential ``` -The deserialized credential object. +The deserialized Credential object. `mppx` parses the echoed Challenge inside the Credential, decoding `request` and `opaque` from their base64url-encoded wire strings back to structured values for application code. diff --git a/src/pages/sdk/typescript/core/Credential.from.mdx b/src/pages/sdk/typescript/core/Credential.from.mdx index 67301408..43cb4dad 100644 --- a/src/pages/sdk/typescript/core/Credential.from.mdx +++ b/src/pages/sdk/typescript/core/Credential.from.mdx @@ -1,6 +1,6 @@ # `Credential.from` [Create a new Credential] -Creates a credential from the given parameters. +Creates a Credential from the given parameters. ## Usage @@ -27,7 +27,7 @@ const credential = Credential.from({ type ReturnType = Credential ``` -A credential object containing the challenge and payment proof. +A Credential object containing the Challenge and payment proof. ## Parameters @@ -35,7 +35,7 @@ A credential object containing the challenge and payment proof. - **Type:** `Challenge` -The challenge from the `402` response. +The Challenge from the `402` response. ### parameters diff --git a/src/pages/sdk/typescript/core/Credential.fromRequest.mdx b/src/pages/sdk/typescript/core/Credential.fromRequest.mdx index 5547810f..1201fac7 100644 --- a/src/pages/sdk/typescript/core/Credential.fromRequest.mdx +++ b/src/pages/sdk/typescript/core/Credential.fromRequest.mdx @@ -1,6 +1,6 @@ # `Credential.fromRequest` [Extract a Credential from a Request] -Extracts the credential from a Request's Authorization header. +Extracts the Credential from a Request's Authorization header. ## Usage @@ -19,7 +19,7 @@ export async function handler(request: Request) { type ReturnType = Credential ``` -The deserialized credential object. +The deserialized Credential object. ## Parameters diff --git a/src/pages/sdk/typescript/core/Credential.serialize.mdx b/src/pages/sdk/typescript/core/Credential.serialize.mdx index 6445c821..ec0958f1 100644 --- a/src/pages/sdk/typescript/core/Credential.serialize.mdx +++ b/src/pages/sdk/typescript/core/Credential.serialize.mdx @@ -1,6 +1,6 @@ # `Credential.serialize` [Serialize a Credential to a header] -Serializes a credential to the Authorization header format. +Serializes a Credential to the Authorization header format. ## Usage @@ -40,4 +40,4 @@ When the Credential includes an echoed Challenge, `mppx` keeps the HTTP wire for - **Type:** `Credential` -The credential to serialize. +The Credential to serialize. diff --git a/src/pages/sdk/typescript/core/Receipt.deserialize.mdx b/src/pages/sdk/typescript/core/Receipt.deserialize.mdx index f6c1abf7..b6588f08 100644 --- a/src/pages/sdk/typescript/core/Receipt.deserialize.mdx +++ b/src/pages/sdk/typescript/core/Receipt.deserialize.mdx @@ -1,6 +1,6 @@ # `Receipt.deserialize` [Deserialize a Receipt from a header] -Deserializes a Payment-Receipt header value to a receipt. +Deserializes a Payment-Receipt header value to a Receipt. ## Usage @@ -17,7 +17,7 @@ const receipt = Receipt.deserialize(encoded) type ReturnType = Receipt ``` -The deserialized receipt object. +The deserialized Receipt object. ## Parameters diff --git a/src/pages/sdk/typescript/core/Receipt.from.mdx b/src/pages/sdk/typescript/core/Receipt.from.mdx index a11a5f78..71e4e656 100644 --- a/src/pages/sdk/typescript/core/Receipt.from.mdx +++ b/src/pages/sdk/typescript/core/Receipt.from.mdx @@ -1,6 +1,6 @@ # `Receipt.from` [Create a new Receipt] -Creates a receipt from the given parameters. +Creates a Receipt from the given parameters. ## Usage @@ -21,7 +21,7 @@ const receipt = Receipt.from({ type ReturnType = Receipt ``` -A validated receipt object. +A validated Receipt object. ## Parameters diff --git a/src/pages/sdk/typescript/core/Receipt.fromResponse.mdx b/src/pages/sdk/typescript/core/Receipt.fromResponse.mdx index a9bd91ba..ba812d4f 100644 --- a/src/pages/sdk/typescript/core/Receipt.fromResponse.mdx +++ b/src/pages/sdk/typescript/core/Receipt.fromResponse.mdx @@ -1,6 +1,6 @@ # `Receipt.fromResponse` [Extract a Receipt from a Response] -Extracts the receipt from a Response's Payment-Receipt header. +Extracts the Receipt from a Response's Payment-Receipt header. ## Usage @@ -22,7 +22,7 @@ if (response.ok) { type ReturnType = Receipt ``` -The deserialized receipt object. +The deserialized Receipt object. ## Parameters diff --git a/src/pages/sdk/typescript/core/Receipt.serialize.mdx b/src/pages/sdk/typescript/core/Receipt.serialize.mdx index 9b496240..669bba48 100644 --- a/src/pages/sdk/typescript/core/Receipt.serialize.mdx +++ b/src/pages/sdk/typescript/core/Receipt.serialize.mdx @@ -1,6 +1,6 @@ # `Receipt.serialize` [Serialize a Receipt to a string] -Serializes a receipt to the Payment-Receipt header format. +Serializes a Receipt to the Payment-Receipt header format. ## Usage @@ -32,4 +32,4 @@ A base64url-encoded string suitable for the Payment-Receipt header value. - **Type:** `Receipt` -The receipt to serialize. +The Receipt to serialize. diff --git a/src/pages/sdk/typescript/html/custom.mdx b/src/pages/sdk/typescript/html/custom.mdx index 4b016407..e809f672 100644 --- a/src/pages/sdk/typescript/html/custom.mdx +++ b/src/pages/sdk/typescript/html/custom.mdx @@ -12,7 +12,7 @@ For the `Html.init` API reference, see [`Html.init`](/sdk/typescript/Html.init). Adding HTML support requires two pieces: 1. **Server-side handler** — provide `html` options to `Method.toServer` with a bundled script, amount formatter, and other options. -2. **Client-side script** — a script embedded in the server-rendered page that uses [`Html.init`](/sdk/typescript/Html.init) to render a payment form and submit credentials via Service Worker. +2. **Client-side script** — a script embedded in the server-rendered page that uses [`Html.init`](/sdk/typescript/Html.init) to render a payment form and submit Credentials via Service Worker. ## Server-side handler @@ -112,7 +112,7 @@ For a guide on using payment links as a consumer, see [Create a payment link](/g ## Client-side script -Create the JavaScript file that renders your payment form. Call `Html.init` to get a typed context, build your UI, and call `context.submit` with the credential. +Create the JavaScript file that renders your payment form. Call `Html.init` to get a typed context, build your UI, and call `context.submit` with the Credential. ```ts [html/main.ts] import * as Html from 'mppx/html' diff --git a/src/pages/sdk/typescript/index.mdx b/src/pages/sdk/typescript/index.mdx index 33055d12..d7d742cf 100644 --- a/src/pages/sdk/typescript/index.mdx +++ b/src/pages/sdk/typescript/index.mdx @@ -112,7 +112,7 @@ const account = privateKeyToAccount('0xabc…123') ### Create payment handler -Call `Mppx.create` at startup. This polyfills the global `fetch` to automatically handle `402` payment challenges. +Call `Mppx.create` at startup. This polyfills the global `fetch` to automatically handle `402` payment Challenges. @@ -124,12 +124,14 @@ import { Mppx, tempo } from 'mppx/client' // [!code hl] const provider = Provider.create({ mpp: false }) // Avoid double 402 handling; mppx is configured below. await provider.request({ method: 'wallet_connect' }) -Mppx.create({ // [!code hl] - methods: [tempo({ // [!code hl] - account: provider.getAccount({ signable: true }), // [!code hl] - getClient: provider.getClient, // [!code hl] - })], // [!code hl] -}) // [!code hl] +// [!code hl:start] +Mppx.create({ + methods: [tempo({ + account: provider.getAccount({ signable: true }), + getClient: provider.getClient, + })], +}) +// [!code hl:end] ``` @@ -141,9 +143,11 @@ import { Mppx, tempo } from 'mppx/client' // [!code hl] const account = privateKeyToAccount('0xabc…123') -Mppx.create({ // [!code hl] - methods: [tempo({ account })], // [!code hl] -}) // [!code hl] +// [!code hl:start] +Mppx.create({ + methods: [tempo({ account })], +}) +// [!code hl:end] ``` @@ -211,7 +215,7 @@ const response = await fetch('https://mpp.dev/api/ping/paid') ### Framework mode -Use the framework-specific middleware from `mppx` to integrate payment into your server. Each middleware handles the `402` challenge/credential flow and attaches receipts automatically. +Use the framework-specific middleware from `mppx` to integrate payment into your server. Each middleware handles the `402` Challenge/Credential flow and attaches Receipts automatically. ::::code-group diff --git a/src/pages/sdk/typescript/proxy.mdx b/src/pages/sdk/typescript/proxy.mdx index 72a2930e..ee4ccffe 100644 --- a/src/pages/sdk/typescript/proxy.mdx +++ b/src/pages/sdk/typescript/proxy.mdx @@ -6,7 +6,7 @@ imageDescription: "Add paid access to existing APIs" # Proxy [Paid API proxy] -Gates upstream API services behind MPP `402` payments. The proxy handles routing, credential injection, and payment verification—you configure which endpoints require payment and which are free passthrough. +Gates upstream API services behind MPP `402` payments. The proxy handles routing, Credential injection, and payment verification—you configure which endpoints require payment and which are free passthrough. ## Install diff --git a/src/pages/sdk/typescript/server/Method.tempo.charge.mdx b/src/pages/sdk/typescript/server/Method.tempo.charge.mdx index 9fd0a7ab..1ac5faa0 100644 --- a/src/pages/sdk/typescript/server/Method.tempo.charge.mdx +++ b/src/pages/sdk/typescript/server/Method.tempo.charge.mdx @@ -264,7 +264,7 @@ Human-readable description of the payment request. - **Type:** `string` - **Default:** 5 minutes from now -ISO 8601 timestamp for when the payment challenge expires. +ISO 8601 timestamp for when the payment Challenge expires. ### meta (optional) diff --git a/src/pages/sdk/typescript/server/Mppx.compose.mdx b/src/pages/sdk/typescript/server/Mppx.compose.mdx index f11bfd29..e79cfd38 100644 --- a/src/pages/sdk/typescript/server/Mppx.compose.mdx +++ b/src/pages/sdk/typescript/server/Mppx.compose.mdx @@ -36,7 +36,7 @@ export async function handler(request: Request) { ## Behavior -- **No Credential present:** Calls all handlers and merges their `402` challenges into a single response with multiple `WWW-Authenticate` headers. +- **No Credential present:** Calls all handlers and merges their `402` Challenges into a single response with multiple `WWW-Authenticate` headers. - **`Accept-Payment` present:** Ranks and filters the merged Challenges by the client's supported `method/intent` entries. Entries with `q=0` are excluded. If the header is invalid or filters out every Challenge, all Challenges are returned. - **Credential present:** Dispatches to the handler matching the Credential's `method` and `intent`. diff --git a/src/pages/sdk/typescript/server/Mppx.create.mdx b/src/pages/sdk/typescript/server/Mppx.create.mdx index a6f6fd2a..d7843e41 100644 --- a/src/pages/sdk/typescript/server/Mppx.create.mdx +++ b/src/pages/sdk/typescript/server/Mppx.create.mdx @@ -99,7 +99,7 @@ const payment = Mppx.create({ - **Type:** `string` - **Default:** Auto-detected from `MPP_SECRET_KEY` environment variable. Throws if neither provided nor set. -Secret key for HMAC-bound challenge IDs. Enables stateless verification—the server verifies that a Challenge was issued by itself without storing state. Treat it as root-of-trust material: store it in your secret manager, keep it server-side, never log it, and rotate it immediately if it is exposed. See [Security](/advanced/security). +Secret key for HMAC-bound Challenge IDs. Enables stateless verification—the server verifies that a Challenge was issued by itself without storing state. Treat it as root-of-trust material: store it in your secret manager, keep it server-side, never log it, and rotate it immediately if it is exposed. See [Security](/advanced/security). ```ts twoslash import { Mppx, tempo } from 'mppx/server' diff --git a/src/pages/sdk/typescript/server/Transport.from.mdx b/src/pages/sdk/typescript/server/Transport.from.mdx index 6166c701..3975eb81 100644 --- a/src/pages/sdk/typescript/server/Transport.from.mdx +++ b/src/pages/sdk/typescript/server/Transport.from.mdx @@ -70,10 +70,10 @@ Transport name for identification. - **Type:** `(options: { challenge: Challenge; error?: PaymentError; input: Input }) => ChallengeOutput | Promise` -Creates a transport response for a payment challenge. +Creates a transport response for a payment Challenge. ### respondReceipt - **Type:** `(options: { challengeId: string; receipt: Receipt; response: ReceiptOutput }) => ReceiptOutput` -Attaches a receipt to a successful response. +Attaches a Receipt to a successful response. diff --git a/src/pages/sdk/typescript/server/Transport.http.mdx b/src/pages/sdk/typescript/server/Transport.http.mdx index a5167fc3..8506ea1e 100644 --- a/src/pages/sdk/typescript/server/Transport.http.mdx +++ b/src/pages/sdk/typescript/server/Transport.http.mdx @@ -15,9 +15,9 @@ const mppx = Mppx.create({ ## Behavior -- Reads credentials from the `Authorization` header -- Issues challenges in the `WWW-Authenticate` header with `402` status -- Attaches receipts in the `Payment-Receipt` header +- Reads Credentials from the `Authorization` header +- Issues Challenges in the `WWW-Authenticate` header with `402` status +- Attaches Receipts in the `Payment-Receipt` header ## Return type diff --git a/src/pages/sdk/typescript/server/Transport.mcp.mdx b/src/pages/sdk/typescript/server/Transport.mcp.mdx index 77d761fe..9a91a543 100644 --- a/src/pages/sdk/typescript/server/Transport.mcp.mdx +++ b/src/pages/sdk/typescript/server/Transport.mcp.mdx @@ -15,9 +15,9 @@ const mppx = Mppx.create({ ## Behavior -- Reads credentials from `_meta["org.paymentauth/credential"]` -- Issues challenges in a JSON-RPC error with code `-32042`/`-32043` -- Attaches receipts in `_meta["org.paymentauth/receipt"]` +- Reads Credentials from `_meta["org.paymentauth/credential"]` +- Issues Challenges in a JSON-RPC error with code `-32042`/`-32043` +- Attaches Receipts in `_meta["org.paymentauth/receipt"]` Use this transport when handling raw JSON-RPC messages directly. For use with [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk), use [`Transport.mcpSdk()`](/sdk/typescript/server/Transport.mcpSdk) instead. diff --git a/src/pages/sdk/typescript/server/Transport.mcpSdk.mdx b/src/pages/sdk/typescript/server/Transport.mcpSdk.mdx index e1fe423c..56b31ace 100644 --- a/src/pages/sdk/typescript/server/Transport.mcpSdk.mdx +++ b/src/pages/sdk/typescript/server/Transport.mcpSdk.mdx @@ -28,9 +28,9 @@ server.registerTool('premium', { description: 'A premium tool' }, async (extra) ## Behavior -- Reads credentials from `_meta["org.paymentauth/credential"]` -- Issues challenges as `McpError` with code `-32042` and challenge in `error.data` -- Attaches receipts in `_meta["org.paymentauth/receipt"]` on tool results +- Reads Credentials from `_meta["org.paymentauth/credential"]` +- Issues Challenges as `McpError` with code `-32042` and Challenge in `error.data` +- Attaches Receipts in `_meta["org.paymentauth/receipt"]` on tool results ## Return type diff --git a/src/pages/tools/wallet.mdx b/src/pages/tools/wallet.mdx index 177b5888..c61fba98 100644 --- a/src/pages/tools/wallet.mdx +++ b/src/pages/tools/wallet.mdx @@ -204,7 +204,7 @@ $ claude mcp add agentcash --scope user -- npx -y agentcash@latest [Link CLI](https://github.com/stripe/link-cli) lets agents pay for MPP services using a [Link](https://link.co) wallet. The agent authenticates with Link, then `link-cli mpp pay` handles the full `402` → SPT → retry flow automatically—no Stripe integration code required. -The user approves each purchase via the Link app, and credentials are one-time-use tokens scoped to a specific merchant and amount. +The user approves each purchase via the Link app, and Credentials are one-time-use tokens scoped to a specific merchant and amount. @@ -257,7 +257,7 @@ $ link-cli mpp pay https://api.example.com/resource \ - **End-to-end 402 handling**—`link-cli mpp pay` parses the Challenge, creates an SPT, and retries with the Credential - **User approval**—each purchase requires explicit approval in the Link app -- **One-time-use credentials**—SPTs are scoped to a specific merchant, amount, and context +- **One-time-use Credentials**—SPTs are scoped to a specific merchant, amount, and context - **MCP server mode**—run as `link-cli --mcp` for integration with Claude Code and other MCP-compatible agents ## `mppx`