@coinbase/cdp-cli 0.0.0 → 2.0.1

package/skills/cdp-setup/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: cdp-setup
+description: Installs the CDP CLI and configures API key + wallet secret from the Coinbase Developer Portal. Verifies connectivity.
+---
+
+# cdp-setup
+
+Set up the CDP CLI: install, configure API key and wallet secret, verify.
+
+## Steps
+
+1. **Check Node.js**: `node --version` — must be >= 22. If missing or too old, install from https://nodejs.org/en/download
+
+   **Warning (nvm/fnm users):** If you upgrade your default Node version, globally installed tools (e.g., Claude Code) will need to be reinstalled since each Node version has its own global packages. After upgrading, open a new terminal and reinstall any global tools you had on the previous version.
+
+2. **Linux only — install keyring support** (prevents secrets from being stored in plaintext):
+   ```
+   which secret-tool || sudo apt install -y libsecret-tools
+   ```
+
+3. **Check if `cdp` is installed**:
+   ```
+   cdp --version
+   ```
+   If not found:
+   ```
+   npm i -g @coinbase/cdp-cli
+   ```
+
+4. **Create a CDP project and API key**:
+   > Go to https://portal.cdp.coinbase.com/projects/api-keys
+   > - Sign in (a project is auto-created on first sign-in).
+   > - Click **Create API Key** → **Download** the JSON key file.
+   > - Provide the path to the downloaded file.
+
+   ```
+   cdp env live --key-file <path>
+   ```
+
+5. **Generate a wallet secret** (required for server wallet operations):
+   > Go to https://portal.cdp.coinbase.com/products/server-wallet/accounts
+   > - Click **Generate Wallet Secret** → **Download** the file.
+
+   ```
+   cdp env live --wallet-secret-file <path>
+   ```
+
+6. **Verify**:
+   ```
+   cdp env
+   ```
+   Assert: `live` appears with key ID and `(wallet)` indicator.
+   ```
+   cdp evm accounts list
+   ```
+   Assert: returns JSON (no auth error). May return `{"accounts":[]}`.
+
+7. **Set up MCP server** (optional — gives your agent direct tool access to all CDP APIs):
+
+   The CDP CLI includes an MCP server (`cdp mcp`) that exposes every API endpoint as a tool.
+
+   **Claude Code:**
+   ```
+   claude mcp add --scope user --transport stdio cdp -- cdp mcp
+   ```
+
+   **Other agents** — add to your agent's MCP config (format varies by agent):
+   ```json
+   { "command": "cdp", "args": ["mcp"], "transport": "stdio" }
+   ```
+
+8. **Install agent skills** (optional):
+   ```
+   cdp skills add
+   ```
+   If non-interactive, determine your agent's skills directory and pass it:
+   ```
+   cdp skills add --dir <skills-directory>
+   ```
+
+9. **Codex users**: If not running with `--sandbox danger-full-access` (full access mode), the default sandbox cannot access OS keychain secrets. Options:
+   - Prompt Codex to run `cdp` commands with "elevated access" (safest)
+   - Or use the `cdp mcp` server instead of direct CLI commands (MCP has expected keychain access in Codex)
+
+10. **Troubleshooting**:
+   - "Must use a CDP Entity scoped API key" → need a v2 portal key, not legacy
+   - "Wallet authentication error" → wallet secret missing or incorrect
+   - "forbidden" → API key permissions issue
+   - After upgrading Node via nvm/fnm → open a new terminal, reinstall global tools that were on the old version
+   - Windows: `cdp` not found after `npm i -g` → add npm's global bin to PATH: `%APPDATA%\npm`

package/skills/cdp-smart-accounts/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: cdp-smart-accounts
+description: Creates ERC-4337 smart accounts, prepares and sends user operations with optional paymaster sponsorship. Requires an EOA owner.
+---
+
+# cdp-smart-accounts
+
+Smart account lifecycle: create, user operations, paymaster.
+
+## Create
+
+1. Ensure a funded EOA owner exists (create via `/cdp-accounts-create` if needed).
+2. ```
+   cdp evm smart-accounts create 'owners:=["<ownerAddress>"]' name=<name>
+   ```
+   `owners` is a string array of addresses, NOT objects.
+3. Verify:
+   ```
+   cdp evm smart-accounts get <address>
+   cdp evm smart-accounts by-name <name>
+   ```
+
+## Send via user operation
+
+Smart accounts cannot use the encode→sign→send pipeline. Use user operations instead.
+
+### Prepare and send (one step)
+
+```
+cdp evm smart-accounts user-operations prepare-and-send <smartAddress> \
+  network=base-sepolia \
+  'calls:=[{"to":"<recipient>","value":"10000000000000","data":"0x"}]'
+```
+Returns `.userOpHash`. Poll until complete:
+```
+cdp evm smart-accounts user-operations get <smartAddress> <userOpHash>
+```
+
+### With paymaster (gas sponsorship)
+
+Add `paymasterUrl`:
+```
+cdp evm smart-accounts user-operations prepare-and-send <smartAddress> \
+  network=base-sepolia \
+  'calls:=[{"to":"<recipient>","value":"10000000000000","data":"0x"}]' \
+  paymasterUrl=https://paymaster.cdp.coinbase.com
+```
+
+Note: paymaster covers gas only, not call value. For calls with non-zero value, fund the smart account directly first.
+
+### Prepare then send (two steps)
+
+1. Prepare:
+   ```
+   cdp evm smart-accounts user-operations create <smartAddress> \
+     network=base-sepolia 'calls:=[{"to":"<to>","value":"0","data":"0x"}]'
+   ```
+2. Send:
+   ```
+   cdp evm smart-accounts user-operations send <smartAddress> <userOpHash>
+   ```
+
+## Verify
+
+After user op completes, check recipient balance:
+```
+cdp evm token-balances get base-sepolia <recipient>
+```
+
+## Notes
+
+- Smart account addresses are deterministic from the owner address.
+- Owner EOA must be funded on testnet for non-paymaster operations.
+- `value` in calls is in wei as a string.

package/skills/cdp-solana/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: cdp-solana
+description: Creates Solana accounts, transfers SOL and SPL tokens using tx-encode with v0 transactions. Handles faucet funding on devnet.
+---
+
+# cdp-solana
+
+Solana account management and transfers.
+
+## Create account
+
+```
+cdp solana accounts create name=<name>
+```
+Verify: `cdp solana accounts get <address>` and `cdp solana accounts by-name <name>`
+
+## Fund (devnet)
+
+```
+cdp solana faucet address=<address> token=sol
+```
+Faucet tokens: sol, usdc. Faucet is rate-limited per address per 24h window. If limit hit, wait or fund from another account. Verify:
+```
+cdp solana token-balances get solana-devnet <address>
+```
+
+## SOL transfer
+
+1. Encode (produces v0 transaction automatically):
+   ```
+   cdp util tx-encode --network solana-devnet --to <recipient> --value <lamports> --from <sender>
+   ```
+
+2. Decode and verify:
+   ```
+   cdp util tx-decode <base64>
+   ```
+
+3. Sign:
+   ```
+   cdp solana accounts sign transaction <sender> transaction=<base64>
+   ```
+
+4. Send:
+   ```
+   cdp solana accounts send transaction network=solana-devnet transaction=<signedTransaction>
+   ```
+
+5. Verify:
+   ```
+   cdp solana token-balances get solana-devnet <sender>
+   ```
+
+If `InsufficientFundsForRent` → new recipient accounts require at least 890000 lamports (0.00089 SOL) for rent-exemption. Send at least 1000000 lamports.
+
+## SPL token transfer
+
+```
+cdp util tx-encode --network solana-devnet --to <recipient> --value <atomic_units> --from <sender> --token <mint_address>
+```
+Value is in atomic token units (e.g., 1000000 for 1 USDC with 6 decimals).
+
+Then sign and send as above.
+
+## Sign message
+
+```
+cdp solana accounts sign message <address> message="<message>"
+```
+
+## Import / Export
+
+See `/cdp-accounts-import-export` — works the same as EVM but uses base58 keys.
+
+## Notes
+
+- tx-encode auto-generates v0 transactions with recent blockhash.
+- Solana faucet amounts: ~0.00125 SOL — enough for a few test transfers.
+- SPL token transfers require the recipient to have an associated token account (created automatically by the transfer instruction if funded).

package/skills/cdp-spend-permissions/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: cdp-spend-permissions
+description: Sets up EIP-7702 delegation on an EOA and manages spend permissions — create, list, and revoke. Testnet delegations require gas.
+---
+
+# cdp-spend-permissions
+
+EIP-7702 delegation + spend permission lifecycle.
+
+## Preconditions
+
+1. CLI configured → `/cdp-setup`
+2. Funded EOA → `/cdp-accounts-create` (testnet delegations require gas; mainnet delegations are gas-sponsored by Coinbase)
+3. Spender address → create a second account if needed
+
+## Steps
+
+### 1. EIP-7702 delegation
+
+```
+cdp evm accounts eip7702 delegation <address> network=base-sepolia 'enableSpendPermissions:=true'
+```
+If "Insufficient balance" → fund the EOA first.
+
+Poll until COMPLETED:
+```
+cdp evm eip7702 delegation-operations <delegationOperationId>
+```
+
+### 2. Create spend permission
+
+```
+cdp evm smart-accounts spend-permissions <address> \
+  network=base-sepolia token=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE \
+  allowance=1000000000000000 period=3600 \
+  start=<unix_now> end=<unix_now+86400> \
+  spender=<spenderAddress> paymasterUrl=https://paymaster.cdp.coinbase.com
+```
+Returns a user operation — poll until complete.
+
+If "Smart Account with given address not found" → delegation may have failed or wrong address namespace.
+
+### 3. List permissions
+
+```
+cdp evm smart-accounts spend-permissions list <address>
+```
+Extract `.spendPermissions[0].permissionHash`.
+
+### 4. Revoke
+
+```
+cdp evm smart-accounts spend-permissions revoke <address> \
+  network=base-sepolia permissionHash=<hash>
+```
+
+## Compatibility
+
+| Account type | Supported |
+|-------------|-----------|
+| EVM EOA (delegated) | yes — requires EIP-7702 with enableSpendPermissions=true |
+| Solana | no |
+| Smart account (ERC-4337) | no — use EIP-7702 delegated EOA |
+| End-user smart account | no — separate namespace |

package/skills/cdp-swaps/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: cdp-swaps
+description: Executes EVM token swaps (ETH to ERC-20 or ERC-20 to ERC-20) with Permit2 approval flow. Mainnet only (base, ethereum, arbitrum, optimism, polygon).
+---
+
+# cdp-swaps
+
+Token swap on EVM mainnet.
+
+## Preconditions
+
+1. CLI configured → `/cdp-setup`
+2. Funded account on a mainnet network (base, ethereum, arbitrum, optimism, polygon).
+3. Swaps are mainnet only — testnet networks are rejected.
+
+## Steps
+
+### 1. Get quote (read-only)
+
+```
+cdp evm swaps quote network==base toToken==0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
+  fromToken==0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE \
+  fromAmount==100000000000000 taker==<address>
+```
+Note: `==` for query params on GET.
+
+### 2. Create swap
+
+```
+cdp evm swaps network=base toToken=<toToken> fromToken=<fromToken> \
+  fromAmount=<amount> taker=<address> signerAddress=<address>
+```
+`cdp evm swaps` IS the POST action (no `create` subcommand). Use `=` for body fields.
+
+### 3. Handle Permit2 (ERC-20 source tokens only)
+
+If response contains `.permit2.eip712`:
+
+a. **One-time approval** — approve ERC-20 to Permit2 contract:
+   ```
+   PERMIT2=0x000000000022d473030f116ddee9f6b43ac78ba3
+   APPROVE_DATA=$(cdp util abi-encode "approve(address,uint256)" $PERMIT2 115792089237316195423570985008687907853269984665640564039457584007913129639935)
+   ```
+   Send via `/cdp-accounts-send` with `to=<fromToken_contract>`, `data=$APPROVE_DATA`, `value=0`.
+
+b. **Sign Permit2 typed data**:
+   ```
+   cdp evm accounts sign typed-data <address> \
+     primaryType=<permit2.eip712.primaryType> \
+     types:=<permit2.eip712.types> \
+     message:=<permit2.eip712.message> \
+     domain:=<permit2.eip712.domain>
+   ```
+
+c. **Append signature to calldata**:
+   ```
+   SIG_RAW="${signature:2}"
+   SIG_LEN="0000000000000000000000000000000000000000000000000000000000000041"
+   FULL_DATA="${swap.transaction.data}${SIG_LEN}${SIG_RAW}"
+   ```
+
+If no `.permit2` (native ETH source) → use `swap.transaction.data` as-is.
+
+### 4. Confirm with user
+
+Show amount, estimated output, and network before proceeding.
+
+### 5. Encode, sign, send
+
+```
+cdp util tx-encode --network <network> --to <swap.transaction.to> \
+  --data <FULL_DATA> --value <swap.transaction.value> --from <address> \
+  --gas-limit <swap.transaction.gas>
+cdp evm accounts sign transaction <address> transaction=<tx>
+cdp evm accounts send transaction <address> network=<network> transaction=<signedTransaction>
+```
+
+### 6. Verify
+
+```
+cdp evm token-balances get <network> <address>
+```
+Assert: fromToken decreased, toToken increased.
+
+## Compatibility
+
+| Account type | Supported |
+|-------------|-----------|
+| EVM EOA | yes (mainnet only) |
+| Smart account | no — taker must be EOA |
+| Solana | no |

package/skills/cdp-x402/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: cdp-x402
+description: Explores x402 HTTP payment protocol — lists supported schemes, discovers resources from the bazaar, and verifies/settles payments.
+---
+
+# cdp-x402
+
+x402 HTTP payment protocol: supported schemes, bazaar discovery, payment verification.
+
+## Supported schemes
+
+```
+cdp x402 supported
+```
+Returns `.kinds` with available network/scheme combinations.
+
+## Discover resources from bazaar
+
+```
+cdp api /x402/discovery/resources
+```
+Filter for target network from the response items.
+
+## Test 402 response
+
+```
+curl -s -o /dev/null -w "%{http_code}" <resourceUrl>
+```
+Expect: 402 Payment Required.
+
+## Verify payment (seller-side)
+
+```
+cdp x402 verify paymentPayload:=<json> paymentRequirements:=<json> x402Version:=2
+```
+
+## Settle payment (seller-side)
+
+```
+cdp x402 settle paymentPayload:=<json> paymentRequirements:=<json> x402Version:=2
+```
+
+## Notes
+
+- `verify` and `settle` are for resource servers (sellers), not buyers.
+- Buyer flow is best handled by `@x402/fetch` or `@x402/axios` SDKs.
+- CDP facilitator: `https://api.cdp.coinbase.com/platform/v2/x402` (all networks, needs API key).
+- x402.org facilitator: testnet only, no signup.
+
+## Network support
+
+| Network | Facilitator |
+|---------|-------------|
+| Base / Base Sepolia | CDP or x402.org (testnet) |
+| Polygon | CDP |
+| Solana / Solana Devnet | CDP or x402.org (testnet) |

package/index.js

@@ -1 +0,0 @@
-console.log("Temporary package");