@coinbase/cdp-cli 0.0.0 → 2.0.2

package/dist/version.txt

@@ -0,0 +1 @@
+2.0.2

package/package.json

@@ -1,8 +1,39 @@
 {
   "name": "@coinbase/cdp-cli",
-  "version": "0.0.0",
-  "description": "Placeholder package",
-  "main": "index.js",
-  "author": "Coinbase Inc.",
-  "license": "Apache-2.0"
+  "version": "2.0.2",
+  "description": "CLI for the Coinbase Developer Platform API",
+  "type": "module",
+  "bin": {
+    "cdp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "BUILD=external node scripts/embed-spec.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --no-warnings --test 'src/**/*.test.ts'",
+    "test:keyring": "node --experimental-strip-types --no-warnings --test src/lib/keyring/keyring.integration-test.ts",
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "scripts/postinstall.mjs"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "esbuild": "^0.27.3",
+    "typescript": "^5.7.0",
+    "yaml": "^2.6.0"
+  },
+  "license": "MIT",
+  "homepage": "https://docs.cdp.coinbase.com",
+  "keywords": [
+    "coinbase",
+    "cdp",
+    "cli",
+    "mcp",
+    "api"
+  ]
 }

package/scripts/postinstall.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// postinstall — auto-update skills if skillsDir is configured.
+// NEVER exits non-zero to avoid breaking npm install.
+
+import { readFileSync, readdirSync, existsSync, mkdirSync, cpSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+function configPath() {
+  if (process.env.CDP_CONFIG_DIR) return join(process.env.CDP_CONFIG_DIR, 'config.json');
+  if (process.platform === 'win32') {
+    const appData = process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming');
+    return join(appData, 'cdp', 'config.json');
+  }
+  return join(homedir(), '.config', 'cdp', 'config.json');
+}
+
+function copySkills(srcDir, destDir) {
+  if (!existsSync(srcDir)) return 0;
+  mkdirSync(destDir, { recursive: true });
+  let count = 0;
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const skillMd = join(srcDir, entry.name, 'SKILL.md');
+    if (!existsSync(skillMd)) continue;
+    cpSync(join(srcDir, entry.name), join(destDir, entry.name), { recursive: true, force: true });
+    count++;
+  }
+  return count;
+}
+
+try {
+  const cfgFile = configPath();
+  if (!existsSync(cfgFile)) process.exit(0);
+
+  const cfg = JSON.parse(readFileSync(cfgFile, 'utf8'));
+  const skillsDir = cfg?.settings?.skillsDir;
+  if (!skillsDir) process.exit(0);
+
+  // Resolve bundled skills directory relative to this script
+  const thisDir = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = dirname(thisDir);
+  const srcDir = join(packageRoot, 'skills');
+
+  if (!existsSync(srcDir)) process.exit(0);
+
+  const count = copySkills(srcDir, skillsDir);
+  process.stderr.write(`cdp: updated ${count} skills in ${skillsDir}\n`);
+} catch (err) {
+  process.stderr.write(`cdp: warning: could not update skills: ${err.message}\n`);
+}

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

@@ -0,0 +1,78 @@
+---
+name: cdp-accounts-create
+description: Creates and funds CDP server wallets (EVM, Solana, Smart Account) or end-user embedded wallets. Handles testnet faucet funding automatically.
+---
+
+# cdp-accounts-create
+
+Create a CDP account and optionally fund it.
+
+## Preconditions
+
+1. CLI configured → `/cdp-setup`
+2. Wallet secret required for server wallets (evm, solana, smart) → `/cdp-setup`
+3. Smart accounts require a funded EOA owner — create one first if needed.
+
+## EVM account
+
+```
+cdp evm accounts create name=<name>
+```
+With policy: `cdp evm accounts create name=<name> accountPolicy=<policyId>`
+
+Verify: `cdp evm accounts get <address>` and `cdp evm accounts by-name <name>`
+
+### Fund (testnet)
+
+```
+cdp evm faucet address=<address> network=base-sepolia token=eth
+```
+Faucet tokens: eth, usdc, eurc, cbbtc. Wait ~6s, then verify:
+```
+cdp evm token-balances get base-sepolia <address>
+```
+
+### Fund (mainnet)
+
+Prompt user to send funds manually. Poll balance until it increases.
+
+## Solana account
+
+```
+cdp solana accounts create name=<name>
+```
+Verify: `cdp solana accounts get <address>` and `cdp solana accounts by-name <name>`
+
+### Fund
+
+```
+cdp solana faucet address=<address> token=sol
+```
+Faucet tokens: sol, usdc. Verify:
+```
+cdp solana token-balances get solana-devnet <address>
+```
+
+## Smart account
+
+1. Resolve or create funded EOA owner.
+2. ```
+   cdp evm smart-accounts create 'owners:=["<ownerAddress>"]' name=<name>
+   ```
+   Note: `owners` is a string array, NOT objects.
+3. Verify: `cdp evm smart-accounts get <address>` and `cdp evm smart-accounts by-name <name>`
+4. Fund the owner EOA if needed (smart account gas comes from owner or paymaster).
+
+## Response fields
+
+| Command | Address field |
+|---------|--------------|
+| evm accounts create | `.address` |
+| solana accounts create | `.address` |
+| smart-accounts create | `.address` |
+
+## Notes
+
+- Faucet amounts are small (~0.0001 ETH, ~0.00125 SOL) — sufficient for testing.
+- Account names must be unique within a project, alphanumeric, 2-36 chars.
+- Use `0.00001ether` for send values to stay under default policy thresholds.

package/skills/cdp-accounts-import-export/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: cdp-accounts-import-export
+description: Exports account private keys with RSA encryption and imports external keys using CDP's encrypt-key utility. EVM and Solana.
+---
+
+# cdp-accounts-import-export
+
+Export or import account private keys.
+
+## Export
+
+1. Generate RSA keypair:
+   ```
+   openssl genpkey -algorithm RSA -out /tmp/rsa.pem -pkeyopt rsa_keygen_bits:4096 2>/dev/null
+   openssl rsa -pubout -in /tmp/rsa.pem -outform DER -out /tmp/rsa.pub.der 2>/dev/null
+   PUBKEY=$(base64 < /tmp/rsa.pub.der | tr -d '\n')
+   ```
+
+2. Export:
+   - EVM by address: `cdp evm accounts export <address> exportEncryptionKey=$PUBKEY`
+   - EVM by name: `cdp evm accounts export by-name <name> exportEncryptionKey=$PUBKEY`
+   - Solana by address: `cdp solana accounts export <address> exportEncryptionKey=$PUBKEY`
+   - Solana by name: `cdp solana accounts export by-name <name> exportEncryptionKey=$PUBKEY`
+
+3. Clean up RSA files.
+
+## Import
+
+1. Encrypt the private key with CDP's RSA key:
+   ```
+   ENCRYPTED=$(cdp util encrypt-key --file ./private-key.txt)
+   ```
+   Auto-detects hex (EVM) vs base58 (Solana).
+
+2. Import:
+   - EVM: `cdp evm accounts import encryptedPrivateKey=$ENCRYPTED name=<name>`
+   - Solana: `cdp solana accounts import encryptedPrivateKey=$ENCRYPTED name=<name>`
+
+3. Verify: `cdp evm accounts get <importedAddress>`
+
+## End-user import
+
+```
+cdp end-users import encryptedPrivateKey=$ENCRYPTED ...
+```
+
+## Notes
+
+- Export encryption uses YOUR RSA key (you decrypt with your private key).
+- Import encryption uses CDP's well-known RSA key (server decrypts in TEE).
+- Test key generation: `openssl rand -hex 32` (EVM) or `cast wallet new` (Foundry).
+
+## Compatibility
+
+| Account type | Export | Import |
+|-------------|--------|--------|
+| EVM EOA | yes | yes |
+| Solana | yes | yes |
+| Smart account | no (contract-based) | no |
+| End-user | no | import only |

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

@@ -0,0 +1,102 @@
+---
+name: cdp-accounts-send
+description: Sends EVM and Solana transactions using the encode-sign-send pipeline. Handles native transfers, ERC-20 transfers, and contract calls.
+---
+
+# cdp-accounts-send
+
+Send a transaction from a server wallet. Encode → sign → send pipeline.
+
+## Preconditions
+
+1. CLI configured → `/cdp-setup`
+2. Account exists and funded → `/cdp-accounts-create`
+3. Mainnet: confirm with user before sending.
+
+## EVM — native transfer
+
+1. Check balance:
+   ```
+   cdp evm token-balances get <network> <from>
+   ```
+
+2. Encode:
+   ```
+   cdp util tx-encode --network <network> --to <to> --value 0.00001ether --from <from>
+   ```
+
+3. Decode and verify:
+   ```
+   cdp util tx-decode <0x_hex>
+   ```
+   Assert: `to`, `value`, `chainId` match intent.
+
+4. Sign:
+   ```
+   cdp evm accounts sign transaction <from> transaction=<tx>
+   ```
+
+5. Send:
+   ```
+   cdp evm accounts send transaction <from> network=<network> transaction=<signedTransaction>
+   ```
+
+6. Verify balance changed:
+   ```
+   cdp evm token-balances get <network> <from>
+   ```
+
+## EVM — ERC-20 transfer
+
+Encode calldata with abi-encode:
+```
+DATA=$(cdp util abi-encode "transfer(address,uint256)" <recipient> <amount_atomic>)
+```
+Then send with `to=<token_contract>`, `data=$DATA`, `value=0`.
+
+## EVM — contract call with approval
+
+For Permit2 or other approvals:
+```
+APPROVE_DATA=$(cdp util abi-encode "approve(address,uint256)" <spender> 115792089237316195423570985008687907853269984665640564039457584007913129639935)
+```
+Send with `to=<token_contract>`, `data=$APPROVE_DATA`, `value=0`.
+
+## Solana — SOL transfer
+
+1. Encode:
+   ```
+   cdp util tx-encode --network solana-devnet --to <to> --value <lamports> --from <from>
+   ```
+
+2. Sign:
+   ```
+   cdp solana accounts sign transaction <from> transaction=<base64>
+   ```
+
+3. Send:
+   ```
+   cdp solana accounts send transaction network=solana-devnet transaction=<signedTransaction>
+   ```
+
+4. Verify:
+   ```
+   cdp solana token-balances get solana-devnet <from>
+   ```
+
+If `InsufficientFundsForRent` → reduce amount.
+
+## Solana — 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.
+
+## Notes
+
+- Use `0.00001ether` (not `0.0001ether`) for test sends — stays under default policy threshold of 50000000000000 wei.
+- Smart accounts cannot use encode→sign→send. Use `cdp evm smart-accounts user-operations prepare-and-send` instead.
+- Always verify balance after send to confirm the transaction landed.

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

@@ -0,0 +1,65 @@
+---
+name: cdp-accounts-sign
+description: Signs messages, hashes, typed data (EIP-712), and transactions with CDP server wallet accounts. Covers EVM and Solana signing.
+---
+
+# cdp-accounts-sign
+
+Sign data with a server wallet account.
+
+## EVM — sign message (EIP-191)
+
+```
+cdp evm accounts sign message <address> message="<message>"
+```
+Response: `.signature`
+
+## EVM — sign hash
+
+`hash` must be exactly 64 hex characters after the `0x` prefix (32 bytes).
+
+```
+cdp evm accounts sign <address> hash=<0x + 64 hex chars>
+```
+Response: `.signature`
+
+## EVM — sign typed data (EIP-712)
+
+```
+cdp evm accounts sign typed-data <address> primaryType=<type> \
+  'types:={"EIP712Domain":[...],"<type>":[...]}' \
+  'message:={...}' \
+  'domain:={...}'
+```
+`EIP712Domain` MUST be included in `types`.
+Response: `.signature`
+
+## EVM — sign transaction
+
+```
+cdp evm accounts sign transaction <address> transaction=<0x_hex>
+```
+Response: `.signedTransaction`
+
+## Solana — sign message
+
+```
+cdp solana accounts sign message <address> message="<message>"
+```
+Response: `.signature`
+
+## Solana — sign transaction
+
+```
+cdp solana accounts sign transaction <address> transaction=<base64>
+```
+Response: `.signedTransaction`
+
+## Compatibility
+
+| Account type | message | hash | typed-data | transaction |
+|-------------|---------|------|------------|-------------|
+| EVM EOA | yes | yes | yes | yes |
+| Solana | yes | no | no | yes |
+| Smart account | no | no | no | no |
+| End-user | no — requires CDP SDK | | | |

package/skills/cdp-data/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: cdp-data
+description: Queries on-chain data with CDP's SQL API, checks EVM/Solana token balances, and discovers available tables via the grammar endpoint.
+---
+
+# cdp-data
+
+On-chain data queries and token balances.
+
+## SQL queries
+
+### Discover tables
+
+```
+cdp data query grammar
+```
+Returns available tables, columns, and SQL dialect.
+
+### Run query
+
+```
+cdp data query run 'sql=SELECT block_number, timestamp FROM base.blocks LIMIT 5'
+```
+
+Tables are namespaced by network (e.g., `base.blocks`, `base.transactions`, `ethereum.blocks`).
+
+## Token balances
+
+### EVM
+
+```
+cdp evm token-balances get <network> <address>
+```
+Also available via data group:
+```
+cdp data evm token-balances <network> <address>
+```
+
+### Token ownership (EVM)
+
+```
+cdp data evm token-ownership <network> <address>
+```
+
+### Solana
+
+```
+cdp solana token-balances get <network> <address>
+```
+
+## Webhooks
+
+### Create subscription
+
+```
+cdp data webhooks subscriptions create target.url=<url> 'eventTypes:=["wallet.activity.detected"]' 'isEnabled:=true' 'labels:={"params.to":"<address>"}'
+```
+
+- `wallet.activity.detected` requires `labels` with `params.to` or `params.from` — omitting labels returns a 400 error.
+
+### Update subscription
+
+```
+cdp data webhooks subscriptions update <id> 'eventTypes:=["wallet.activity.detected"]' 'isEnabled:=false' target.url=<url> 'labels:={"params.to":"<address>"}'
+```
+
+- `update` requires ALL fields (eventTypes, target, isEnabled), not just changed fields — it's a full replace. Omitting any field causes an error.
+
+### Delete subscription
+
+```
+cdp data webhooks subscriptions delete <id>
+```
+
+## Notes
+
+- Both `cdp evm token-balances` and `cdp data evm token-balances` return the same data.
+- Use token balances to verify mutations (funding, sends, swaps).

package/skills/cdp-end-users/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: cdp-end-users
+description: Creates end-user embedded wallets with email authentication and adds EVM, Solana, or smart account sub-accounts to them.
+---
+
+# cdp-end-users
+
+End-user CRUD and sub-account management.
+
+## Create end user
+
+```
+cdp end-users create \
+  'authenticationMethods:=[{"type":"email","email":"<email>"}]' userId=<userId>
+```
+If `already_exists` → email in use, try different email.
+
+Verify: `cdp end-users get <userId>`
+
+## Add sub-accounts
+
+### EVM
+
+```
+cdp end-users evm <userId> 'createSmartAccount:=false'
+```
+Response: `.evmAccount.address`
+
+### Solana
+
+```
+cdp end-users solana <userId>
+```
+Response: `.solanaAccount.address`
+
+### Smart account
+
+```
+cdp end-users evm-smart-account <userId> 'enableSpendPermissions:=false'
+```
+Response: `.evmSmartAccount.address`
+
+## Import key for end user
+
+```
+ENCRYPTED=$(cdp util encrypt-key <privateKey>)
+cdp end-users import encryptedPrivateKey=$ENCRYPTED ...
+```
+
+## List end users
+
+```
+cdp end-users list
+```
+
+## Notes
+
+- End-user accounts are in a separate namespace — `cdp evm accounts sign <endUserAddr>` returns 404.
+- End-user signing requires the CDP SDK, not the CLI.
+- `userId` must be unique within your project.

package/skills/cdp-onramp/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: cdp-onramp
+description: Creates onramp sessions for fiat-to-crypto purchases, checks user purchase limits, and manages headless orders with sandbox testing support.
+---
+
+# cdp-onramp
+
+Onramp sessions, limits, and orders.
+
+## Create session (no enrollment needed)
+
+```
+cdp onramp sessions destinationAddress=<address> destinationNetwork=base \
+  purchaseCurrency=USDC partnerUserRef=<userId>
+```
+Returns `.session.onrampUrl` — user opens this in browser to complete purchase.
+
+After user completes payment, poll balance:
+```
+cdp evm token-balances get base <address>
+```
+Settlement takes 1-5 minutes.
+
+## Check limits
+
+Use a real phone number format (e.g., +12025551234). Test/fictitious numbers like 555-xxx are rejected.
+
+```
+cdp onramp limits userIdType=phone_number userId=<phone> paymentMethodType=GUEST_CHECKOUT_APPLE_PAY
+```
+
+## Headless order (requires merchant enrollment)
+
+Use `partnerUserRef=sandbox-<id>` to enable sandbox mode:
+```
+cdp onramp orders destinationAddress=<address> destinationNetwork=base \
+  paymentMethod=GUEST_CHECKOUT_APPLE_PAY purchaseCurrency=USDC \
+  purchaseAmount=10.000000 paymentCurrency=USD paymentAmount=10.00 \
+  email=<email> phoneNumber=<phone> \
+  phoneNumberVerifiedAt=<recent_iso> agreementAcceptedAt=<recent_iso> \
+  partnerUserRef=sandbox-e2e-<timestamp> 'isQuote:=false'
+```
+
+If 403 "not authorized": extract app ID from error → contact onramp team to enroll.
+
+Poll order status:
+```
+cdp onramp orders get <orderId>
+```
+Until `ONRAMP_TRANSACTION_STATUS_SUCCESS` or terminal.
+
+Verify funds:
+```
+cdp evm token-balances get base <address>
+```
+
+## Notes
+
+- Sessions and limits work without merchant enrollment.
+- Headless orders require enrollment and payment completion (sandbox: Apple Pay always succeeds, card 4242 4242 4242 4242).

package/skills/cdp-policies/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: cdp-policies
+description: Creates transaction policies with accept/reject rules, attaches them to accounts, and tests enforcement. Supports value, address, and network criteria.
+---
+
+# cdp-policies
+
+Policy CRUD and enforcement testing.
+
+## Create policy
+
+MUST include both accept AND reject rules (default when no rule matches is deny):
+
+```
+cdp policy-engine policies create scope=account \
+  'rules:=[
+    {"action":"accept","operation":"sendEvmTransaction","criteria":[{"type":"ethValue","ethValue":"50000000000000","operator":"<"}]},
+    {"action":"reject","operation":"sendEvmTransaction","criteria":[{"type":"ethValue","ethValue":"50000000000000","operator":">="}]}
+  ]'
+```
+
+## Project-scoped policy
+
+Only one project-level policy can exist at a time. Applies to all accounts.
+
+```
+cdp policy-engine policies create scope=project \
+  'rules:=[{"action":"accept","operation":"sendEvmTransaction","criteria":[{"type":"ethValue","ethValue":"100000000000000","operator":"<"}]}]'
+```
+
+## Attach to account
+
+On create: `cdp evm accounts create name=<name> accountPolicy=<policyId>`
+On existing: `cdp evm accounts update <address> accountPolicy=<policyId>`
+
+Verify attachment: `cdp evm accounts get <address>` — check `accountPolicy` field.
+
+## Test enforcement
+
+1. Fund the account → `/cdp-accounts-create`
+2. Under threshold (should PASS):
+   Send `0.00001ether` via `/cdp-accounts-send` → assert `transactionHash` returned.
+3. At/over threshold (should REJECT):
+   Send `0.0001ether` via `/cdp-accounts-send` → assert `policy_violation` error.
+
+## Update policy
+
+```
+cdp policy-engine policies update <policyId> 'rules:=[...]'
+```
+Re-test: previously rejected value should now succeed (re-encode tx for fresh nonce).
+
+## CRUD
+
+- List: `cdp policy-engine policies list scope==account` (note: `==` for query param)
+- Get: `cdp policy-engine policies get <policyId>`
+- Delete: detach first (`cdp evm accounts update <address> accountPolicy=""`), then:
+  ```
+  cdp policy-engine policies delete <policyId>
+  ```
+
+## Supported operations
+
+`signEvmTransaction`, `sendEvmTransaction`, `signEvmMessage`, `signEvmTypedData`, `signEvmHash`,
+`signSolTransaction`, `sendSolTransaction`, `signSolMessage`,
+`prepareUserOperation`, `sendUserOperation`,
+`signEndUserEvmTransaction`, `sendEndUserEvmTransaction` (and Solana equivalents)
+
+## Criteria types
+
+`ethValue` (operators: `<`, `<=`, `>`, `>=`, `==`), `evmAddress` (`in`, `notIn`),
+`evmNetwork`, `evmData` (`startsWith`, `equals`), `netUSDChange`,
+`solValue`, `solAddress`, `solNetwork`, `solData`, `programId`, `splAddress`, `splValue`,
+`evmMessage`, `solMessage`
+
+## Notes
+
+- Rules are chain-specific: `ethValue` on `sendSolTransaction` will not match.
+- Default threshold of 50000000000000 wei = 0.00005 ETH. Use `0.00001ether` for passing sends.