Rewrite V2 SDK Getting Started pages

[vraspar]

Summary

Replaces PR #18 with a full rewrite of the 4 Getting Started pages following the new DOCS_WRITING_GUIDE anti-slop rules.

What changed:

• sdk/overview.mdx — landing page feel, leads with x402 vs x402r contrast, real chain tables
• sdk/installation.mdx — shortest page on the site, jumps straight to install command
• sdk/create-client.mdx — decision tree between createX402r() and role presets, config reference
• sdk/typescript.mdx — reference sheet with role narrowing tables verified against types.ts
• docs.json — adds create-client and typescript to Getting Started nav, removes concepts and limitations

Writing approach:

• Every opening answers "why would I read this?" not "what is this page about?"
• Code first, prose annotates only non-obvious behavior
• Real addresses from config/index.ts, not placeholders
• Structural variety: each page has a different feel (landing page / quick-start / decision tree / reference sheet)
• All signatures verified against x402r-sdk/packages/sdk/src/types.ts

Test plan

• npx mintlify broken-links passes
• Anti-slop grep (no banned words: powerful, seamless, robust, allows you to, etc.)
• All function signatures match types.ts
• Role narrowing tables match Pick types (lines 235-379)
• getChainConfig confirmed re-exported from @x402r/sdk
• Preview deploy renders correctly

🤖 Generated with Claude Code

[vraspar]

Code review

Found 8 issues:

1. Broken code fence in merchant-quickstart.mdx -- a ```typescript block opens at line 62, then another ```typescript opens at line 68 without closing the first. This will break Mintlify rendering, showing raw fence characters instead of a code block.

docs/sdk/merchant-quickstart.mdx

Lines 61 to 76 in 8a2b99f

	```typescript
	import type { PaymentInfo } from '@x402r/sdk'
	// paymentInfo comes from the facilitator callback or your payment records
	const paymentInfo: PaymentInfo = { /* ... */ }
	```typescript
	const amounts = await merchant.payment.getAmounts(paymentInfo)
	console.log('Collected:', amounts.hasCollectedPayment) // true
	console.log('Capturable:', amounts.capturableAmount) // 1000000n
	console.log('Refundable:', amounts.refundableAmount) // 1000000n
	const inEscrow = await merchant.escrow?.isDuringEscrow(paymentInfo)
	console.log('In escrow:', inEscrow) // true
	```

2. MarketplaceOperatorDeployment interface and code example use wrong field names (SDK source of truth: x402r-sdk/packages/core/src/deploy/presets.ts) -- The documented interface at lines 139-155 and the console.log example at lines 120-121 have multiple mismatches with the actual SDK type: summary.newDeployments should be summary.newCount, summary.existingContracts should be summary.existingCount, txHashes is inside summary not top-level, and arbiterConditionAddress does not exist on MarketplaceOperatorDeployment (it belongs to a different deployment type).

docs/sdk/deploy-operator.mdx

Lines 119 to 155 in 8a2b99f

	console.log('Freeze:', result.freezeAddress)
	console.log('New deployments:', result.summary.newDeployments)
	console.log('Existing (reused):', result.summary.existingContracts)
	```
	## Configuration Options
	| Option | Type | Description |
	|--------|------|-------------|
	| `feeRecipient` | `Address` | Address that receives operator fees |
	| `arbiter` | `Address` | Arbiter address for dispute resolution |
	| `escrowPeriodSeconds` | `bigint` | Escrow waiting period (e.g., `604800n` for 7 days) |
	| `freezeDurationSeconds` | `bigint` | How long freezes last. Default: `0n` (permanent until unfrozen) |
	| `operatorFeeBps` | `bigint` | Fee in basis points. Default: `0n` (no fee). `100n` = 1% |
	## Deployment Result
	The `deployMarketplaceOperator` function returns:
	```typescript
	interface MarketplaceOperatorDeployment {
	operatorAddress: Address; // The PaymentOperator
	escrowPeriodAddress: Address; // EscrowPeriod recorder/condition
	freezeAddress: Address; // Freeze condition
	refundRequestAddress: Address; // RefundRequest recorder
	refundRequestEvidenceAddress: Address; // Evidence storage
	arbiterConditionAddress: Address; // StaticAddressCondition for arbiter
	refundInEscrowConditionAddress: Address; // OR(Receiver, Arbiter)
	feeCalculatorAddress: Address | null; // null if no fee
	txHashes: Hash[]; // All deployment tx hashes
	summary: {
	newDeployments: number; // Newly deployed contracts
	existingContracts: number; // Reused existing contracts
	};
	}
	```

3. Em dashes in 8+ locations across new files (CLAUDE.md says "Never use em dashes. Use a comma, period, or rewrite the sentence instead.") -- sdk/create-client.mdx lines 7, 32, 69, 85, 114; sdk/installation.mdx line 36; sdk/typescript.mdx lines 46, 51. Notably, this PR adds the em dash rule to CLAUDE.md while violating it in the same changeset.

docs/sdk/create-client.mdx

Lines 6 to 8 in 8a2b99f

	The SDK creates clients two ways: `createX402r()` gives you every action group with no type restrictions. The role presets — `createPayerClient()`, `createMerchantClient()`, `createArbiterClient()` — narrow TypeScript types so you only see methods relevant to your role.

4. "Merchants authorize payments" is factually incorrect -- overview.mdx line 11 says "Merchants authorize payments into escrow." Per the x402 payment flow: the payer signs the ERC-3009 authorization, the facilitator submits it on-chain. The merchant does not authorize. Similarly, create-client.mdx line 32 says "payers don't authorize payments, merchants do" which inverts the actual flow.

docs/sdk/overview.mdx

Lines 10 to 12 in 8a2b99f

	- **Merchants** authorize payments into escrow and release funds after delivery
	- **Payers** can request refunds, freeze payments, and submit evidence during disputes

5. viem incorrectly described as a peer dependency -- installation.mdx line 19 says "viem, the only peer dependency" and adds it to the install command. But @x402r/sdk/package.json lists viem under dependencies (not peerDependencies), so it installs automatically. A previous commit (fecbb68) deliberately removed viem from install commands for this exact reason.

docs/sdk/installation.mdx

Lines 17 to 20 in 8a2b99f

	</CodeGroup>
	This installs the full SDK and [viem](https://viem.sh), the only peer dependency.

6. @x402r/evm incorrectly described as a peer dependency of @x402r/helpers -- installation.mdx line 51 says "@x402r/evm is a peer dependency of @x402r/helpers." The actual @x402r/helpers/package.json only declares @x402/core as a peer dependency. @x402r/evm is not a peer dep.

docs/sdk/installation.mdx

Lines 50 to 52 in 8a2b99f

	<Note>
	`@x402r/evm` is a peer dependency of `@x402r/helpers`. It provides escrow scheme types used by the `refundable()` helper.
	</Note>

7. Monad USDC address has wrong EIP-55 checksum (contract address source of truth: x402r-sdk/packages/core/src/config/index.ts) -- overview.mdx line 89 has ...BC8a327... (lowercase a), but the SDK source has ...BC8A327... (uppercase A).

docs/sdk/overview.mdx

Lines 88 to 90 in 8a2b99f

	| Avalanche C-Chain | `43114` | `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E` |
	| Monad | `143` | `0x754704Bc059F8C67012fEd69BC8a327a5aafb603` |
	| Linea | `59144` | `0x176211869cA2b568f2A7D4EE941E073a821EE1ff` |

8. create-client, typescript, and installation pages missing from nav -- All three files are created or modified in this PR, but none appear anywhere in docs.json. They are orphaned pages that users cannot discover from the sidebar.

docs/docs.json

Lines 1 to 10 in 8a2b99f

	{
	"$schema": "https://mintlify.com/docs.json",
	"theme": "mint",
	"name": "x402r Documentation",
	"colors": {
	"primary": "#16A34A",
	"light": "#07C983",
	"dark": "#15803D"
	},
	"favicon": "/favicon.svg",

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[vraspar]

Code review (re-review after updates)

Previous 8 issues are all fixed. Found 7 new issues, mostly in the new arbiter-delivery.mdx page:

1. RefundRequestStatus enum comment is wrong in two files. Status 3 is Cancelled (not Refused), and status 4 (Refused) is missing entirely. Actual SDK enum: Pending: 0, Approved: 1, Denied: 2, Cancelled: 3, Refused: 4. (SDK source: x402r-sdk/packages/core/src/actions/refund/types.ts)

docs/sdk/arbiter-dispute.mdx

Lines 66 to 68 in a4a6757

	console.log('Amount:', request?.amount)
	console.log('Status:', request?.status) // 0 = Pending, 1 = Approved, 2 = Denied, 3 = Refused
	}

docs/sdk/payer-quickstart.mdx

Lines 90 to 92 in a4a6757

	const status = await payer.refund?.getStatus(paymentInfo)
	console.log('Status:', status) // 0 = Pending, 1 = Approved, 2 = Denied, 3 = Refused
	```

2. deployDeliveryProtectionOperator is not exported from @x402r/core's public API. It exists in core/src/deploy/presets.ts and is re-exported from core/src/deploy/index.ts, but core/src/index.ts does not include it. Only deployMarketplaceOperator and deployArbiterSetup are in the public surface. This import will fail.

docs/sdk/arbiter-delivery.mdx

Lines 36 to 38 in a4a6757

	```typescript
	import { deployDeliveryProtectionOperator } from '@x402r/core'

3. "CREATE2" should be "CREATE3" in two places. The project uses unified CREATE3 addresses across all chains. (CLAUDE.md memory: "unified CREATE3 -- same addresses on every chain"; SDK config comments: "Unified CREATE3 addresses")

docs/sdk/deploy-operator.mdx

Lines 23 to 25 in a4a6757

	All contracts are deployed via factories using CREATE2, so identical configurations produce identical addresses across deployments.

docs/sdk/deploy-operator.mdx

Lines 157 to 159 in a4a6757

	<Tip>
	Because all contracts use CREATE2, redeploying with the same parameters is idempotent it will detect existing contracts and skip them. The `summary` tells you what was new vs reused.
	</Tip>

4. extractPaymentInfo(paymentPayload) does not exist anywhere in the SDK. This is an invented function with no import statement. (CLAUDE.md says "Test all code examples before including")

docs/sdk/arbiter-delivery.mdx

Lines 116 to 118 in a4a6757

	// Extract paymentInfo from paymentPayload
	const paymentInfo = extractPaymentInfo(paymentPayload)
	const amounts = await arbiter.payment.getAmounts(paymentInfo)

5. CommerceEvmScheme is the client-side class (from @x402r/evm/commerce/client), not the server-side class needed for a resource server. Additionally, neither x402ResourceServer nor CommerceEvmScheme are imported -- only forwardToArbiter is imported in this code block.

docs/sdk/arbiter-delivery.mdx

Lines 61 to 68 in a4a6757

	```typescript
	import { forwardToArbiter } from '@x402r/helpers'
	const resourceServer = new x402ResourceServer(facilitatorClient)
	.register(networkId, new CommerceEvmScheme(serverConfig))
	.onAfterSettle(
	forwardToArbiter('http://your-arbiter:3001', {
	onError: (err) => console.error('Arbiter unreachable:', err),

6. Merchant Quickstart card says "Authorize payments, release funds from escrow." Merchants do not authorize payments -- payers sign authorizations, facilitators submit them. The overview.mdx card for the same page correctly says "accept a payment."

docs/sdk/deploy-operator.mdx

Lines 203 to 205 in a4a6757

	<Card title="Merchant Quickstart" icon="store" href="/sdk/merchant-quickstart">
	Authorize payments, release funds from escrow.
	</Card>

7. Card title still says "SDK Installation" but href was updated to /sdk/overview. All other similar cards in this PR were updated to "SDK Overview."

docs/x402-integration/overview.mdx

Lines 219 to 221 in a4a6757

	<Card title="SDK Installation" icon="rocket" href="/sdk/overview">
	Get started building with x402r.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[vraspar]

Code review (round 3)

All 7 issues from round 2 are fixed. Found 4 new issues:

1. fromNetworkId is imported from @x402r/sdk but is not exported from that package. It is only exported from @x402r/core. This import will fail. (Verified against x402r-sdk/packages/sdk/src/index.ts and packages/core/src/index.ts)

docs/sdk/delivery-arbiter.mdx

Lines 36 to 38 in 13b4ef3

	import { privateKeyToAccount } from 'viem/accounts'
	import { createArbiterClient, fromNetworkId } from '@x402r/sdk'

2. payment.authorize() is described as "a merchant action" but per the x402 payment flow, the payer signs the ERC-3009 authorization and the facilitator submits it. Saying it is a "merchant action" inverts who holds signing authority. Consider: "that method is not part of the payer role" or similar.

docs/sdk/payer-quickstart.mdx

Lines 55 to 57 in 13b4ef3

	`createPayerClient` restricts TypeScript types to payer-relevant methods. `refund.request()` shows up in autocomplete; `payment.authorize()` does not because that is a merchant action.

3. The forwarded payload JSON shape in delivery-merchant.mdx shows paymentPayload: { x402Version, scheme, payload: "..." } (flat structure), but delivery-arbiter.mdx uses parseForwardedPayload() which extracts paymentInfo and network as top-level return fields parsed from paymentPayload.accepted.network and paymentPayload.payload.paymentInfo. The two pages document different schemas for the same POST body, so a developer following both will hit a mismatch.

docs/sdk/delivery-merchant.mdx

Lines 90 to 95 in 13b4ef3

	```json
	{
	"responseBody": "the HTTP response body as a string",
	"transaction": "0xsettlement_tx_hash",
	"paymentPayload": { "x402Version": 1, "scheme": "commerce", "payload": "..." }
	}

docs/sdk/delivery-arbiter.mdx

Lines 64 to 69 in 13b4ef3

	app.post('/verify', async (req, res) => {
	const { responseBody, paymentInfo, network, transaction } =
	parseForwardedPayload(req.body)
	const chainId = fromNetworkId(network) // "eip155:84532" -> 84532

4. Two sentences in deploy-operator.mdx have double spaces where em dashes were removed, producing broken prose. (CLAUDE.md says "Never use em dashes. Use a comma, period, or rewrite the sentence instead." -- the em dashes were removed but replaced with whitespace, not punctuation.)

docs/sdk/deploy-operator.mdx

Lines 46 to 48 in 13b4ef3

	Edit `.env` with your values. Only `PRIVATE_KEY` is required everything else has sensible defaults:

docs/sdk/deploy-operator.mdx

Lines 157 to 159 in 13b4ef3

	<Tip>
	Because all contracts use CREATE3, redeploying with the same parameters is idempotent it will detect existing contracts and skip them. The `summary` tells you what was new vs reused.
	</Tip>

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}