[Smart Accounts Kit] x402 seller guide

[AyushBherwani1998]

Description

• Adds x402 seller guide

Issue(s) fixed

Fixes #

Preview

Checklist

• If this PR updates or adds documentation content that changes or adds technical meaning, it has received an approval from an engineer or DevRel from the relevant team.
• If this PR updates or adds documentation content, it has received an approval from a technical writer.

External contributor checklist

• I've read the contribution guidelines.
• I've created a new issue (or assigned myself to an existing issue) describing what this PR addresses.

---

Note

Low Risk
Low risk: documentation-only change adding a new guide and sidebar entry, with no runtime code or security-sensitive logic modified.

Overview
Adds a new guides/x402/seller documentation page that walks through building an x402-compatible Express server accepting ERC-7710 delegation payments via the MetaMask facilitator (including discovery, payment requirement headers, verify/settle flow, and example middleware).

Updates gator-sidebar.js to introduce a new x402 guides category linking to the seller guide.

^{Reviewed by Cursor Bugbot for commit 955ec06. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
metamask-docs	Ready	Preview, Comment	May 12, 2026 1:07pm

[AyushBherwani1998]

@cursoragent review the PR based on https://docs-template.consensys.io/contribute/style-guide. Also find the missing gaps in the guide as a developers which can be added.

[cursor]

Let me create a comprehensive style review report for the x402 seller guide.

Style review: smart-accounts-kit/guides/x402/seller.md

Product: Smart Accounts Kit | Content type: How-to guide

Summary

• Vale not available (skipped automated checks)
• 15 issues found from manual review
• Severity: 3 critical (structural/completeness), 12 suggestions (style, formatting, content gaps)

---

Critical issues

Line 26-28: Duplicate step numbering

• Two headings both numbered "### 1." — "Install the dependencies" (line 26) and "Create payment requirements" (line 28)
• The first step heading (line 26) has no content beneath it
• Fix: Either remove the empty "Install the dependencies" heading or populate it with actual installation instructions, then renumber subsequent steps

Line 223-226: Malformed code

• The app.listen call is syntactically incorrect:

  ;(app.listen(4402),
    () => {
      console.log('Seller listening on port 4402')
    })

• Fix: Should be:

  app.listen(4402, () => {
    console.log('Seller listening on port 4402')
  })

Missing "Next steps" section

• How-to guides should end with links to related content or logical next actions
• Fix: Add a "Next steps" section linking to related x402 concepts, buyer guide (if it exists), or troubleshooting

---

Voice and tone

Line 16: Passive construction

• "so you implement the x402 HTTP contract manually" — while grammatically active, the phrasing "so you implement" is weak
• Suggestion: "This guide shows you how to implement the x402 HTTP contract manually" or "You'll implement the x402 HTTP contract manually because the official @x402/express middleware doesn't support ERC-7710 delegation payloads."

---

Terminology

Line 95: Standard not spelled out on first use

• "ERC-7710" appears without the full name
• Per terminology.mdc, standards should be spelled out on first use: "ERC-7710 (General Permission Management for Smart Accounts)" or similar
• Fix: Add full name on first mention (line 95 or earlier in the intro)

Line 22: Typo

• "recieve" should be "receive"

---

Formatting

Line 64: Placeholder format

• 'YOUR_PAYTO_ADDRESS' should use angle brackets per markdown-formatting.mdc
• Fix: '<YOUR_PAYTO_ADDRESS>'

Line 95: Mixed line wrapping

• Some sentences exceed 100 columns; lines should wrap at roughly 100 columns
• Example: line 95 is 119 characters
• Fix: Break long lines

---

Content gaps (developer perspective)

These gaps make it difficult for developers to actually build and run this server:

1. No installation/dependencies instructions

   • Step 1 heading exists but is empty
   • Missing npm install express viem or similar
   • Missing package.json setup
   • Missing TypeScript configuration if using .ts files

2. No complete working example

   • Code is split across multiple tabs/files
   • No indication of full project structure
   • No GitHub repo link or downloadable starter
   • Suggestion: Provide a complete file tree or link to a working example repo

3. No environment configuration

   • FACILITATOR_URL is hardcoded in src/config.ts
   • No guidance on whether this URL changes per network
   • No mention of API keys or authentication requirements
   • Suggestion: Add a prerequisites note about facilitator endpoints and whether they require authentication

4. No security considerations

   • No rate limiting mentioned
   • No DoS protection (malicious clients sending bad X-PAYMENT headers)
   • No validation of maxAmountRequired vs actual settlement amount
   • Suggestion: Add a "Security considerations" section or note about production hardening

5. No error handling beyond 402

   • What if the facilitator is down?
   • What if settle fails after verify succeeds?
   • What if the buyer's delegation expired between verify and settle?
   • Suggestion: Add error handling examples

6. No explanation of post-settlement flow

   • What happens after settle is called?
   • When does the seller actually receive funds?
   • Is there a claim/withdraw step?
   • Suggestion: Add a brief explanation or link to facilitator documentation

7. No testing guidance

   • How does a developer test this without a real buyer?
   • Are there test networks or mock facilitators?
   • Suggestion: Add a "Test your server" section or link to testing tools

8. Incomplete prerequisites

   • "Minimal Node.js Express server" is vague
   • Should specify Express version or provide a minimal starting template
   • Suggestion: Be more specific: "A Node.js project with Express 4.x or later" and optionally link to Express setup docs

9. No CORS or cross-origin guidance

   • If buyers call this from browsers, CORS must be configured
   • Suggestion: Add a note about CORS middleware if browser clients are expected

10. Missing type imports

    • src/type.ts defines PaymentRequirements but imports from viem (Address) are shown
    • src/middleware.ts imports from express but the Express types aren't shown in the installation step
    • Suggestion: Show all necessary imports in step 1

---

Sidebar (workflow check)

✅ Verified: gator-sidebar.js correctly includes 'guides/x402/seller' in a new collapsed "x402" category (lines 117-122)

No redirect needed (new file, not moved/renamed).

---

Recommendations

High priority (fix before merge)

1. Fix the duplicate step 1 headers (remove empty "Install dependencies" or populate it)
2. Fix the malformed app.listen code at the end
3. Fix the typo: "recieve" → "receive"
4. Add actual installation/dependency instructions
5. Fix the placeholder format: <YOUR_PAYTO_ADDRESS>

Medium priority (improves usability)

6. Spell out ERC-7710 on first use
7. Add a "Next steps" section at the end
8. Add security considerations (rate limiting, validation, error handling)
9. Clarify what happens after settlement
10. Provide a complete working example or repo link

Lower priority (nice to have)

11. Add testing guidance
12. Add CORS guidance if browser clients are expected
13. Show full project structure / file tree
14. Add environment configuration section

---

Let me know if you'd like me to implement any of these fixes. I can update the file to address the critical and high-priority issues immediately.

  

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fe865a2. Configure here.}