Three example/doc gaps found testing Base Account SDK v2.5.7 (dataCallback shape, prolink missing 'from', send_calls gas note)
- Dominant language
- JavaScript
- Stars
- 337
- Forks
- 792
- Avg merge
- 17h 23m
- Merged PRs (30d)
- 49
Description
Found while building an agent (Kokosh) that exercises Base Account SDK v2.5.7 and Base MCP end-to-end on mainnet. Three separate example/documentation gaps, all reproduced live and cross-checked against the currently live `base/docs` content (not just a cached copy) before filing.
## 1. `base-account/reference/core/capabilities/datacallback` — callback payload shape doesn't match the live request body
The reference page's example (and the "Example Implementation" callback handler) reads:
```typescript
const { requestedInfo } = requestData.capabilities.dataCallback;
```
The actual POST body Base sends to the `callbackURL` has `requestedInfo` as a **top-level** field, sibling to `calls`/`capabilities`/`chainId` — there is no `requestData.capabilities.dataCallback.requestedInfo` nesting.
Diagnosed by logging the raw request body in production after every live attempt using the documented shape returned `400` (Coinbase's own backend, `api.wallet.coinbase.com/rpc/v3/scw/submitDataCallbackUpdate`, rejected the echoed response built from the wrong shape). Once the handler was changed to read `requestData.requestedInfo` directly, a real $0.05 USDC Base Pay payment with `payerInfo` settled correctly in production.
## 2. `base-account/reference/prolink-utilities/decodeProlink` — "Validate Before Execution" example is missing `from`
The example executes the decoded request directly:
```typescript
const result = await provider.request({
method: decoded.method,
params: decoded.params
});
```
For a `wallet_sendCalls` prolink that was encoded as a **payment request** (the common case — the encoder doesn't know who will open the link, so it has no `from`), this throws `"The requested account and/or method has not been authorized by the user."` The example needs an extra line connecting first and injecting the connected address into `params[0].from` before executing, e.g.:
```typescript
const { accounts } = await provider.request({ method: 'wallet_connect', params: [{ version: '1' }] });
const sendParams = [{ ...decoded.params[0], from: accounts[0].address }];
const result = await provider.request({ method: decoded.method, params: sendParams });
```
Reproduced live: the unmodified example throws the unauthorized error on mainnet against a real payment-request prolink; adding the `from` injection fixes it and the transaction settles.
## 3. `agents/guides/batch-calls` — no mention that `send_calls` may need native gas, unlike other Base MCP/Base Account flows
Nothing on this page (or elsewhere I could find under `agents/`) notes that `send_calls` transactions may require the Base Account to hold native ETH for gas. This is easy to miss because *other* flows against the same Base Account — Base Pay's `pay()`, and a `wallet_sendCalls` executed directly via a first-party SDK popup — settle gaslessly (sponsored), while a `send_calls` submitted through Base MCP against a zero-ETH smart account failed with an insufficient-funds error until the account was funded with a small amount of ETH.
Worth a short caveat on this page (or wherever gas sponsorship for Base MCP write tools is centrally documented) noting that gas sponsorship is not guaranteed for every path that can produce a `wallet_sendCalls`-shaped transaction, so agents/users may need to fund the Base Account with native gas before using `send_calls` even if other flows against the same account have been gasless.
---
All three were hit while building https://github.com/Kajko25/kokosh (JOURNAL.md has the full reproduction detail with tx hashes) and while updating base/skills#148.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the three referenced pages: base-account/reference/core/capabilities/datacallback, base-account/reference/prolink-utilities/decodeProlink, and agents/guides/batch-calls. Compare their examples with the documented request bodies and the reported live behavior, then update the callback and prolink guidance and document the send_calls gas caveat. Done means all three examples and notes match the reproduced behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 68/100