MetaMask · AyushBherwani1998 · Mar 10, 2026
diff --git a/metamask/gator-cli/SKILL.md b/metamask/gator-cli/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gator-cli
-description: Use when you need to operate the @metamask/gator-cli to initialize profiles, upgrade EOA to EIP-7702, grant, redeem, and revoke ERC-7710 delegations, or inspect balances and delegations. Covers commands, required flags, grant scopes, redeem action types, configuration locations, and common usage flows.
+description: Use when you need to operate the @metamask/gator-cli to initialize profiles, upgrade EOA to EIP-7702, grant, redeem, and revoke ERC-7710 delegations, or inspect balances and delegations. Covers commands, required flags, allow types, redeem action types, configuration locations, and common usage flows.
 metadata:
   openclaw:
     emoji: "🐊"
@@ -19,6 +19,30 @@ metadata:
 
 Use this skill to run the gator CLI from the repo and to choose the correct command/flags for delegation workflows.
 
+## Grant Decision Flow
+
+Follow these steps when building a `gator grant` command:
+
+1. Identify what the user wants to delegate.
+
+2. Check if the intent matches a **primary allow type**:
+   - Token transfer with max amount → `erc20TransferAmount` or `nativeTokenTransferAmount`
+   - Periodic token transfer → `erc20PeriodTransfer` or `nativeTokenPeriodTransfer`
+   - Token streaming → `erc20Streaming` or `nativeTokenStreaming`
+   - NFT transfer → `erc721Transfer`
+   - Ownership transfer → `ownershipTransfer`
+   - Function call restriction → `functionCall`
+
+3. If a primary allow type matches:
+   a. Start with `--allow <primaryType>` and its required flags (see Primary Allow Types table).
+   b. Does the user need extra constraints (time limits, call limits, redeemer restrictions, etc.)?
+   c. If yes → append `--allow <additionalType>` for each constraint (see Additional Allow Types table).
+   d. If no → the command is complete.
+
+4. If NO primary allow type matches the intent:
+   - Compose the grant using only additional allow types.
+   - Use one `--allow <type>` per constraint, each with its own flags.
+
 ## Installation
 
 ```sh
@@ -90,46 +114,14 @@ Show native balance and optional ERC-20 balance.
 
 ### grant
 
-Create, sign, and store a delegation with a predefined scope.
-
-- `gator grant --to <to-address> --scope <type> [scope flags] [--profile <profile-name>]`
-
-Scope flags:
+Create, sign, and store a delegation with one or more allow types. Multiple `--allow` flags can be combined in a single grant to compose constraints.
 
-- Token scopes: `--tokenAddress <token-address>`, `--maxAmount <amount>`, `--tokenId <id>`
-- Periodic scopes: `--periodAmount <amount>`, `--periodDuration <seconds>`, `--startDate <timestamp>`
-- Streaming scopes: `--amountPerSecond <amount>`, `--initialAmount <amount>`, `--startTime <timestamp>`
-- Function call scope: `--targets <addresses>`, `--selectors <sigs>`, `--valueLte <ether>`
-- Ownership transfer: `--contractAddress <contract-address>`
+- `gator grant --to <to-address> --allow <type> [type flags] [--allow <type> [type flags] ...] [--profile <profile-name>]`
 
-Supported scopes:
+Run `gator help grant` for the full list of flags.
 
-- `erc20TransferAmount`
-- `erc20PeriodTransfer`
-- `erc20Streaming`
-- `erc721Transfer`
-- `nativeTokenTransferAmount`
-- `nativeTokenPeriodTransfer`
-- `nativeTokenStreaming`
-- `functionCall`
-- `ownershipTransfer`
+For the full list of allow types with descriptions, required flags, and optional flags, see the [Allow Types Reference](./references/allow-types.md).
 
-Grant flags per scope:
-
-| Scope                       | Required Flags                                                          | Optional Flags   |
-| --------------------------- | ----------------------------------------------------------------------- | ---------------- |
-| `erc20TransferAmount`       | `--tokenAddress`, `--maxAmount`                                         |                  |
-| `erc20PeriodTransfer`       | `--tokenAddress`, `--periodAmount`, `--periodDuration`                  | `--startDate`    |
-| `erc20Streaming`            | `--tokenAddress`, `--amountPerSecond`, `--initialAmount`, `--maxAmount` | `--startTime`    |
-| `erc721Transfer`            | `--tokenAddress`, `--tokenId`                                           |                  |
-| `nativeTokenTransferAmount` | `--maxAmount`                                                           |                  |
-| `nativeTokenPeriodTransfer` | `--periodAmount`, `--periodDuration`                                    | `--startDate`    |
-| `nativeTokenStreaming`      | `--amountPerSecond`, `--initialAmount`, `--maxAmount`                   | `--startTime`    |
-| `functionCall`              | `--targets`, `--selectors`                                              | `--valueLte`     |
-| `ownershipTransfer`         | `--contractAddress`                                                     |                  |
-
-- `--startDate` and `--startTime` default to the current time (unix seconds) when omitted.
-- `--valueLte` sets the max native token value per call for `functionCall` scopes.
 
 ### redeem
 
@@ -182,11 +174,51 @@ gator init --profile <profile-name>
 gator create --profile <profile-name>
 ```
 
-Grant an ERC-20 transfer delegation:
+Grant an ERC-20 transfer delegation (primary allow type only):
+
+```bash
+gator grant --profile <profile-name> --to <to-address> \
+  --allow erc20TransferAmount --tokenAddress <token-address> --maxAmount 50
+```
+
+Grant with additional constraints (primary + additional allow types):
+
+```bash
+gator grant --profile <profile-name> --to <to-address> \
+  --allow erc20TransferAmount --tokenAddress <token-address> --maxAmount 50 \
+  --allow limitedCalls --limit 5
+```
+
+Time-bounded native transfer delegation:
+
+```bash
+gator grant --profile <profile-name> --to <to-address> \
+  --allow nativeTokenTransferAmount --maxAmount 0.5 \
+  --allow timestamp --afterTimestamp 1700000000 --beforeTimestamp 1800000000
+```
+
+Redeemer-restricted delegation:
+
+```bash
+gator grant --profile <profile-name> --to <to-address> \
+  --allow nativeTokenTransferAmount --maxAmount 1 \
+  --allow redeemer --redeemers 0xADDR1,0xADDR2
+```
+
+Restrict targets and methods (additional allow types only, no primary):
+
+```bash
+gator grant --profile <profile-name> --to <to-address> \
+  --allow allowedTargets --allowedTargets 0xContract \
+  --allow allowedMethods --allowedMethods "transfer(address,uint256)"
+```
+
+Custom caveat enforcer:
 
 ```bash
-gator grant --profile <profile-name> --to <to-address> --scope erc20TransferAmount \
-  --tokenAddress <token-address> --maxAmount 50
+gator grant --profile <profile-name> --to <to-address> \
+  --allow nativeTokenTransferAmount --maxAmount 1 \
+  --allow custom --enforcerAddress 0xDeployed --enforcerTerms 0xEncoded
 ```
 
 Redeem an ERC-20 transfer:
@@ -227,9 +259,11 @@ gator revoke --profile <profile-name> --to <to-address>
 ## Operational Notes
 
 - **Private key security**: This is alpha version. Private keys are stored in plaintext JSON. Never use accounts with significant funds.
+- Run `gator help <command>` for full flag details on any command.
 - `--from` refers to the delegator address; `--to` refers to the delegate/recipient.
-- `--targets` and `--selectors` are comma-separated lists.
-- `--function` accepts a human-readable Solidity function signature like `"approve(address,uint256)"`. Do **not** pass a 4-byte selector (e.g. `0x095ea7b3`) — the CLI derives the selector from the signature automatically.
+- `--allowedTargets` and `--redeemers` are comma-separated lists.
+- `--allowedMethods` accepts comma-separated human-readable Solidity function signatures like `"approve(address,uint256)"`. Do **not** pass 4-byte selectors.
+- `--function` (for `redeem --action functionCall`) accepts a human-readable Solidity function signature like `"approve(address,uint256)"`. The CLI derives the selector automatically.
 - `--startDate` and `--startTime` accept unix timestamps in seconds. When omitted, they default to the current time.
 - `--action` is required for `redeem` and must be one of: `erc20Transfer`, `erc721Transfer`, `nativeTransfer`, `functionCall`, `ownershipTransfer`, `raw`.
 - Supported chains for `--chain` in `gator init`: `base` (default), `baseSepolia`, `sepolia`.
diff --git a/metamask/gator-cli/references/allow-types.md b/metamask/gator-cli/references/allow-types.md
@@ -0,0 +1,50 @@
+# Allow Types Reference
+
+This reference lists all allow types available for the `gator grant --allow` flag. See the [Caveats reference](https://docs.metamask.io/smart-accounts-kit/reference/delegation/caveats/) for the full Smart Accounts Kit documentation.
+
+## Primary Allow Types
+
+High-level types for common delegation patterns. Use these when the user's intent directly maps to one.
+
+| Allow Type | Description | Required Flags | Optional Flags |
+|---|---|---|---|
+| `erc20TransferAmount` | Limit the total amount of an ERC-20 token the delegate can transfer. | `--tokenAddress`, `--maxAmount` | — |
+| `erc20PeriodTransfer` | Allow ERC-20 transfers up to a limit per recurring time period. Unused allowance does not carry over. | `--tokenAddress`, `--periodAmount`, `--periodDuration` | `--startDate` |
+| `erc20Streaming` | Linear streaming limit for ERC-20 tokens. Releases an initial amount at start, then accrues linearly up to a max. | `--tokenAddress`, `--amountPerSecond`, `--initialAmount`, `--maxAmount` | `--startTime` |
+| `erc721Transfer` | Restrict execution to only allow transfer of a specific ERC-721 token ID. | `--tokenAddress`, `--tokenId` | — |
+| `nativeTokenTransferAmount` | Enforce a maximum allowance of native currency (e.g. ETH) the delegate can transfer. | `--maxAmount` | — |
+| `nativeTokenPeriodTransfer` | Allow native token transfers up to a limit per recurring time period. Unused allowance does not carry over. | `--periodAmount`, `--periodDuration` | `--startDate` |
+| `nativeTokenStreaming` | Linear streaming limit for native tokens. Releases an initial amount at start, then accrues linearly up to a max. | `--amountPerSecond`, `--initialAmount`, `--maxAmount` | `--startTime` |
+| `functionCall` | Restrict which contract addresses and methods the delegate can call. | `--allowedTargets`, `--allowedMethods` | `--maxValue` (adds a `valueLte` constraint) |
+| `ownershipTransfer` | Restrict execution to only allow `transferOwnership` on a specific contract. | `--contractAddress` | — |
+
+Notes:
+- `--startDate` and `--startTime` default to the current timestamp (unix seconds) when omitted.
+- `--maxValue` on `functionCall` adds a `valueLte` constraint to the delegation.
+
+## Additional Allow Types
+
+Granular constraint types that can be layered on top of a primary allow type or composed standalone.
+
+| Allow Type | Description | Required Flags | Optional Flags |
+|---|---|---|---|
+| `limitedCalls` | Limit the number of times the delegate can redeem the delegation. | `--limit` | — |
+| `timestamp` | Restrict the delegation to a time window. Set either threshold to `0` to leave that side unbounded. | — | `--afterTimestamp`, `--beforeTimestamp` (both default to `0`) |
+| `blockNumber` | Restrict the delegation to a block number range. Set either threshold to `0` to leave that side unbounded. | — | `--afterBlock`, `--beforeBlock` (both default to `0`) |
+| `redeemer` | Limit which addresses can redeem the delegation. Delegator accounts with delegation support can bypass this by re-delegating. | `--redeemers` (comma-separated) | — |
+| `nonce` | Attach a nonce to enable bulk revocation by incrementing the nonce on-chain. | `--nonce` (hex) | — |
+| `id` | Assign a shared ID across multiple delegations. Once one is redeemed, the others with the same ID are revoked. | `--caveatId` | — |
+| `valueLte` | Limit the native token value that can be sent per execution. | `--maxValue` | — |
+| `allowedTargets` | Restrict which contract addresses the delegate can call. | `--allowedTargets` (comma-separated) | — |
+| `allowedMethods` | Restrict which methods the delegate can call. Accepts function signatures or 4-byte selectors. | `--allowedMethods` (comma-separated) | — |
+| `allowedCalldata` | Enforce that calldata at a specific byte index matches an expected value. Useful for validating static function parameters. | `--calldataStartIndex`, `--calldataValue` | — |
+| `argsEqualityCheck` | Ensure the args provided when redeeming match the specified terms exactly. | `--argsCheck` (hex) | — |
+| `exactCalldata` | Verify that the entire transaction calldata matches the expected value exactly. | `--exactCalldata` (hex) | — |
+| `exactExecution` | Verify that the execution matches an exact target, value, and calldata. | `--execTarget` | `--execValue` (default `0`), `--execCalldata` (default `0x`) |
+| `nativeTokenPayment` | Require payment in native token (e.g. ETH) to use the delegation. | `--paymentRecipient`, `--paymentAmount` | — |
+| `nativeBalanceChange` | Ensure the recipient's native token balance changes by at least (increase) or at most (decrease) a specified amount. | `--nativeBalanceRecipient`, `--nativeBalanceAmount`, `--nativeBalanceChangeType` | — |
+| `erc20BalanceChange` | Ensure the recipient's ERC-20 balance changes within allowed bounds. | `--erc20BalanceToken`, `--erc20BalanceRecipient`, `--erc20BalanceAmount`, `--erc20BalanceChangeType` | — |
+| `erc721BalanceChange` | Ensure the recipient's ERC-721 balance changes within allowed bounds. | `--erc721BalanceToken`, `--erc721BalanceRecipient`, `--erc721BalanceAmount`, `--erc721BalanceChangeType` | — |
+| `erc1155BalanceChange` | Ensure the recipient's ERC-1155 token balance changes within allowed bounds. | `--erc1155BalanceToken`, `--erc1155BalanceRecipient`, `--erc1155BalanceTokenId`, `--erc1155BalanceAmount`, `--erc1155BalanceChangeType` | — |
+| `deployed` | Ensure a contract is deployed at the specified address; deploys it if not. | `--deployAddress`, `--deploySalt`, `--deployBytecode` | — |
+| `custom` | Use an arbitrary caveat enforcer contract with custom encoded terms. | `--enforcerAddress`, `--enforcerTerms` | — |