docs: document Base Sepolia account readiness limitation

[osr21]

Summary

• document the currently reported Base Sepolia limitation for newly created Base Accounts beside the testnet: true Base Pay example
• clarify that capability discovery does not guarantee that the connected account has completed hosted-wallet provisioning on that chain
• point developers to Bug: Base Sepolia transactions refused for newly-created 7702 accounts, while wallet_getCapabilities reports the chain as supported #363 and provide non-speculative integration-testing guidance

This is intentionally documentation-only because the rejection occurs in the hosted wallet flow rather than in this SDK repository.

Documents #363 while the underlying hosted-wallet behavior is investigated.

How did you test your changes?

• reviewed both rendered Markdown insertion points
• confirmed the change only modifies README.md and packages/account-sdk/README.md
• checked the patch for whitespace errors

[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

[jaooli-cyber]

Thanks for documenting this limitation. Our independent reproduction supports the proposed note:

• connection and SIWE authentication succeeded;
• the newly created account held canonical Base Sepolia test USDC;
• the hosted wallet rejected the request before creating either a Base Pay ID or an onchain transaction.

One small clarification may help integrators: in our reproduction the hosted flow returned { code: 4001 }. Since this code is commonly interpreted as a user rejection, a dapp cannot reliably distinguish an account-readiness/provisioning failure from an actual cancellation.

It may therefore be useful to clarify that, until a machine-readable readiness signal or distinct error is available, applications should not assume that every 4001 returned from this flow means the user cancelled the payment.

No client-side preflight capable of detecting this condition was found in wallet_getCapabilities.

[osr21]

@jaooli-cyber — this is a useful reproduction, and the distinction around 4001 matters. One guardrail I would add is that clients should not invert the ambiguity and treat 4001 as an account-readiness signal either.

4001 is conventionally the EIP-1193 “User Rejected Request” code. If the hosted flow also surfaces provisioning failure under that code, the only safe client-side conclusion is that the request did not complete; the client cannot determine whether the user cancelled, provisioning failed, or another wallet-side path was collapsed into the same error. A reasonable integration response is therefore to:

• present neutral “payment request was not completed” UX rather than asserting a cause;
• avoid automatic retries, because a genuine user rejection remains possible;
• preserve the full provider error (code, message, and any data/nested cause) in diagnostics while avoiding sensitive payload logging;
• confirm completion only from the Base Pay result/payment status or onchain evidence, never from capability discovery.

The absence of a preflight in wallet_getCapabilities is consistent with the proposed docs: capability support says the wallet implements a method on that chain; it is not a liveness or per-account provisioning guarantee. Adding a client heuristic around balances, prior SIWE success, or capability presence would create false confidence.

For a durable platform fix, a distinct machine-readable provider error (or structured error data reason) would be preferable to a readiness flag inferred by the dapp. If possible, attaching the sanitized raw error shape, requested wallet method, SDK/wallet versions, and whether a prompt was shown to issue #363 would help establish where 4001 is introduced without making this documentation PR depend on that diagnosis.

The current PR wording remains appropriately conservative: it documents the observed limitation and warns that capability discovery is not proof of readiness, without claiming a client-side detector that does not exist.

[jaooli-cyber]

Thanks for the clarification. I have added the sanitized diagnostic details to issue #363 so that the underlying 4001 behaviour can be investigated without expanding the scope of this documentation PR:

#363 (comment)

This includes the SDK version, requested Base Pay flow, hosted wallet route, prompt behaviour and the diagnostic fields retained from our reproduction.