diff --git a/docs/base-account/improve-ux/spend-permissions.mdx b/docs/base-account/improve-ux/spend-permissions.mdx
index 76754cbb..b5df4b29 100644
--- a/docs/base-account/improve-ux/spend-permissions.mdx
+++ b/docs/base-account/improve-ux/spend-permissions.mdx
@@ -180,6 +180,7 @@ await provider.request({
- [requestRevoke](/base-account/reference/spend-permission-utilities/requestRevoke)
- [prepareRevokeCallData](/base-account/reference/spend-permission-utilities/prepareRevokeCallData)
- [fetchPermissions](/base-account/reference/spend-permission-utilities/fetchPermissions)
+- [fetchPermission](/base-account/reference/spend-permission-utilities/fetchPermission)
- [getPermissionStatus](/base-account/reference/spend-permission-utilities/getPermissionStatus)
## Complete Integration Example
@@ -187,6 +188,7 @@ await provider.request({
```typescript
import {
fetchPermissions,
+ fetchPermission,
getPermissionStatus,
prepareSpendCallData,
requestSpendPermission,
@@ -205,22 +207,30 @@ const sdk = createBaseAccountSDK({
const spender = "0xAppSpenderAddress";
-// 1) Fetch available permissions
-const permissions = await fetchPermissions({
- account: "0xUserBaseAccountAddress",
- chainId: 84532,
- spender,
+// 1) Fetch a specific permission by its hash
+// Use fetchPermission when you already know the permission hash
+// (e.g., stored from a previous session or passed as a parameter)
+const permission = await fetchPermission({
+ permissionHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
provider: sdk.getProvider(),
});
+// Alternative: Fetch all permissions for a spender
+// Use fetchPermissions when you need to see all available permissions
+// and want to choose which one to use
+// const permissions = await fetchPermissions({
+// account: "0xUserBaseAccountAddress",
+// chainId: 84532,
+// spender,
+// provider: sdk.getProvider(),
+// });
+// const permission = permissions.at(0);
+
// ========================================
// When there IS an existing permission
// ========================================
-// 2. find the permission to use, potentially filtering by token
-const permission = permissions.at(0);
-
-// 3. check the status of permission
+// 2. check the status of permission
try {
const { isActive, remainingSpend } = await getPermissionStatus(permission);
const amount = 1000n;
@@ -232,13 +242,13 @@ try {
throw new Error("No spend permission available");
}
-// 4. prepare the calls
+// 3. prepare the calls
const [approveCall, spendCall] = await prepareSpendCallData({
permission,
amount,
});
-// 5. execute the calls using your app's spender account
+// 4. execute the calls using your app's spender account
// this is an example using wallet_sendCalls, in production it could be using eth_sendTransaction.
await provider.request({
method: "wallet_sendCalls",
diff --git a/docs/base-account/reference/core/provider-rpc-methods/coinbase_fetchPermissions.mdx b/docs/base-account/reference/core/provider-rpc-methods/coinbase_fetchPermissions.mdx
index 43c9e779..d9aa681f 100644
--- a/docs/base-account/reference/core/provider-rpc-methods/coinbase_fetchPermissions.mdx
+++ b/docs/base-account/reference/core/provider-rpc-methods/coinbase_fetchPermissions.mdx
@@ -1,12 +1,12 @@
---
title: "coinbase_fetchPermissions"
-description: "Retrieve permissions associated with a specific account, chain, and spender"
+description: "Retrieve permissions associated with a specific account and chain, optionally filtered by spender"
---
Coinbase-specific RPC method
-Retrieves permissions associated with a specific account, chain, and spender. This method excludes permissions that have expired or been revoked, returning only active spend permissions.
+Retrieves permissions associated with a specific account and chain. If a spender is provided, returns only permissions for that spender. Otherwise, returns all permissions for the account. This method excludes permissions that have expired or been revoked, returning only active spend permissions.
## Parameters
@@ -19,8 +19,8 @@ The address of the account whose permissions are being queried.
The ID of the blockchain, in hexadecimal format.
-
-The entity granted with the permission to spend the account's funds.
+
+Optional. The entity granted with the permission to spend the account's funds. If not provided, returns all permissions for the account.
@@ -54,7 +54,7 @@ Pagination information for the response.
-```json Request
+```json Request with spender
{
"id": 1,
"jsonrpc": "2.0",
@@ -66,6 +66,18 @@ Pagination information for the response.
}]
}
```
+
+```json Request without spender (all permissions)
+{
+ "id": 1,
+ "jsonrpc": "2.0",
+ "method": "coinbase_fetchPermissions",
+ "params": [{
+ "account": "0xfB2adc8629FC9F54e243377ffcECEb437a42934C",
+ "chainId": "0x14A34"
+ }]
+}
+```
@@ -110,5 +122,5 @@ Pagination information for the response.
| -32602 | Invalid params | Invalid account, chainId, or spender parameters |
-Ensure the `chainId`, `account`, and `spender` parameters are correctly formatted and valid for the blockchain you are querying.
+Ensure the `chainId` and `account` parameters are correctly formatted and valid for the blockchain you are querying. If provided, the `spender` parameter must also be a valid address.
diff --git a/docs/base-account/reference/spend-permission-utilities/fetchPermission.mdx b/docs/base-account/reference/spend-permission-utilities/fetchPermission.mdx
new file mode 100644
index 00000000..f162da77
--- /dev/null
+++ b/docs/base-account/reference/spend-permission-utilities/fetchPermission.mdx
@@ -0,0 +1,125 @@
+---
+title: "fetchPermission"
+description: "Retrieve a single Spend Permission by its hash"
+---
+
+Defined in the [Base Account SDK](https://github.com/base/account-sdk)
+
+
+ Returns a single spend permission by its unique hash identifier. This is useful when you have a permission hash from a previous operation and need to retrieve its current details.
+
+
+## Parameters
+
+
+ The unique hash identifier of the permission to retrieve.
+
+
+
+ Optional. EIP-1193 compliant Ethereum provider instance. Get this from `sdk.getProvider()`. If not provided, uses the default SDK provider.
+
+
+## Returns
+
+
+ The spend permission matching the hash, or null if not found.
+
+
+
+Deterministic EIP-712 hash of the permission.
+
+
+
+ Signature for the EIP-712 payload.
+
+
+
+ Target chain ID.
+
+
+
+Underlying permission fields.
+
+
+
+
+
+
+Duration in seconds.
+Unix timestamp (seconds).
+Unix timestamp (seconds).
+
+
+
+
+
+
+
+
+```typescript Fetch single permission
+import { fetchPermission } from "@base-org/account/spend-permission";
+import { createBaseAccountSDK } from "@base-org/account";
+
+const sdk = createBaseAccountSDK({
+ appName: 'My App',
+ appLogoUrl: 'https://example.com/logo.png',
+ appChainIds: [84532],
+});
+
+// Fetch a specific permission by its hash
+const permission = await fetchPermission({
+ permissionHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+ provider: sdk.getProvider(),
+});
+
+if (permission) {
+ console.log('Permission found:', permission);
+} else {
+ console.log('Permission not found');
+}
+
+// Using without explicit provider (uses default SDK provider)
+const permission2 = await fetchPermission({
+ permissionHash: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
+});
+```
+
+
+## Error Handling
+
+The function returns `null` if the permission is not found rather than throwing an error. Always check for null values:
+
+```typescript
+const permission = await fetchPermission({
+ permissionHash: hash,
+});
+
+if (!permission) {
+ // Handle permission not found
+ console.error('Permission not found');
+ return;
+}
+
+// Safe to use permission here
+console.log('Permission details:', permission);
+```
+
+## Usage Notes
+
+
+This function is particularly useful when:
+- You have a permission hash from a previous operation (e.g., from `requestSpendPermission`)
+- You want to verify the current state of a specific permission
+- You need to look up permission details without knowing the account or spender information
+- You're tracking specific permissions across sessions
+
+
+Unlike `fetchPermissions`, this function:
+- Returns a single permission instead of an array
+- Does not require account, chain, or spender parameters
+- Provides direct access via the permission's unique identifier
+- Returns `null` instead of an empty array when no permission is found
+
+import PolicyBanner from "/snippets/PolicyBanner.mdx";
+
+
diff --git a/docs/base-account/reference/spend-permission-utilities/fetchPermissions.mdx b/docs/base-account/reference/spend-permission-utilities/fetchPermissions.mdx
index eaf2f12d..2c3115e4 100644
--- a/docs/base-account/reference/spend-permission-utilities/fetchPermissions.mdx
+++ b/docs/base-account/reference/spend-permission-utilities/fetchPermissions.mdx
@@ -1,13 +1,12 @@
---
title: "fetchPermissions"
-description: "Retrieve available Spend Permissions for an account, chain, and spender"
+description: "Retrieve available Spend Permissions for an account and chain, optionally filtered by spender"
---
Defined in the [Base Account SDK](https://github.com/base/account-sdk)
- Returns all permissions available to a given `spender` for a user's Base
- Account on a specific chain.
+ Returns permissions for a user's Base Account on a specific chain. If a `spender` is provided, returns only permissions for that spender. Otherwise, returns all permissions for the account.
## Parameters
@@ -20,12 +19,12 @@ Defined in the [Base Account SDK](https://github.com/base/account-sdk)
Target chain ID.
-
- Spender address you intend to use for spending.
+
+ Optional. Spender address you intend to use for spending. If not provided, returns all permissions for the account.
-
- EIP-1193 compliant Ethereum provider instance. Get this from `sdk.getProvider()`.
+
+ Optional. EIP-1193 compliant Ethereum provider instance. Get this from `sdk.getProvider()`. If not provided, uses the default SDK provider.
## Returns
@@ -65,7 +64,7 @@ Underlying permission fields.
-```typescript Fetch permissions
+```typescript Fetch permissions for specific spender
import { fetchPermissions } from "@base-org/account/spend-permission";
import { createBaseAccountSDK } from "@base-org/account";
@@ -75,12 +74,19 @@ const sdk = createBaseAccountSDK({
appChainIds: [84532],
});
+// Fetch permissions for a specific spender
const permissions = await fetchPermissions({
account: "0xUserBaseAccountAddress",
chainId: 84532,
spender: "0xAppSpenderAddress",
provider: sdk.getProvider(),
});
+
+// Fetch all permissions for the account (omitting spender)
+const allPermissions = await fetchPermissions({
+ account: "0xUserBaseAccountAddress",
+ chainId: 84532,
+});
```
diff --git a/docs/docs.json b/docs/docs.json
index 7c3fcf72..ec7c294a 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -252,6 +252,7 @@
"base-account/reference/spend-permission-utilities/requestSpendPermission",
"base-account/reference/spend-permission-utilities/prepareSpendCallData",
"base-account/reference/spend-permission-utilities/fetchPermissions",
+ "base-account/reference/spend-permission-utilities/fetchPermission",
"base-account/reference/spend-permission-utilities/getPermissionStatus",
"base-account/reference/spend-permission-utilities/requestRevoke",
"base-account/reference/spend-permission-utilities/prepareRevokeCallData",