docs(base-account): add Session Keys guide for AI agents and games

[erhnysr]

Summary

Closes #1505.

Adds a new guide docs/base-account/guides/session-keys.mdx covering how to use Spend Permissions as "session keys" for AI agents and on-chain games — scenarios that aren't addressed by the existing Accept Recurring Payments or Use Spend Permissions guides.

What's new:

• Clear framing: one-time user approval → autonomous backend charging, no per-action popup
• Step-by-step flow using the high-level subscribe() / charge() / getSubscriptionStatus() / revoke() SDK functions
• Full AI agent example — chat interface that charges $0.10/message against a $5/month budget (React client + Next.js API route)
• Full on-chain game example — crafting system that charges per item without interrupting gameplay
• Testnet section with overridePeriodInSecondsForTestnet for fast iteration
• Security best practices accordion: status checks before every charge, transparent pricing, budget management
• API reference table cross-linked to existing reference docs
• Added to the base-account Guides nav group in docs.json (after Accept Recurring Payments)

Relationship to existing docs:
This guide sits between the generic Spend Permissions primitives page and the SaaS-focused recurring payments guide. It fills the gap for developers building AI products and games who need autonomous spending without a subscription mental model.

Test plan

• Verify MDX renders without errors in Mintlify preview
• Confirm code examples type-check against @base-org/account types
• Confirm nav entry appears in sidebar between "Accept Recurring Payments" and "Batch Transactions"
• Verify all cross-links resolve correctly

🤖 Generated with Claude Code

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/2	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[erhnysr]

Hi! Following up on this PR — adds a Session Keys guide for AI agents and games, an area that currently has no dedicated documentation. Happy to address any feedback.

[maho0638]

Thanks for putting this together. Since this PR is linked to #1505, I wanted to add a few issue-scope review notes.

I think the current Closes #1505 claim may be a bit too broad for the diff as it stands. The original issue asked not only for a guide, but also for clearer API/reference coverage (and possibly provider/RPC coverage if that is the official path). This PR currently adds a guide + nav entry, but no dedicated reference updates.

A few specific things that would make this much stronger:

1. The README.md change looks unrelated to the Session Keys / Spend Permissions docs work and would be better as a separate PR.
2. The guide currently documents the USDC subscription / spend-permissions wrapper flow for agents and games, which is useful, but that is narrower than generic “Session Keys”. It would help to clarify whether this page is intended to document official Session Keys, or specifically the Spend Permissions pattern for autonomous spending.
3. To align more closely with docs(base-account): missing documentation for Session Keys (critical feature) #1505, I think the guide should point more directly to the lower-level Spend Permission utilities (requestSpendPermission, getPermissionStatus, prepareSpendCallData, requestRevoke) and include an example that covers permission scope + expiry + revocation explicitly.
4. The full examples are directionally helpful, but they still rely on placeholders / omitted setup, so I’d suggest tightening them to smaller validated examples unless they’ve been fully type-checked end to end.

Happy to help prepare a narrower follow-up docs PR if maintainers prefer a more issue-complete version.

[erhnysr]

Thanks for the detailed review @maho0638! Will address all 4 points: split out the README change, clarify the Spend Permissions scope vs generic Session Keys, add the low-level function examples (requestSpendPermission, getPermissionStatus, etc.) with expiry/revocation, and tighten the examples to fully validated code. Updating shortly.