---
name: Coinbase
description: Use when building crypto infrastructure: wallets, payments, trading, stablecoins, onchain tools, and AI agents. Use CDP APIs to create non-custodial and custodial wallets, accept payments, manage transfers, onramp/offramp users, execute trades, deploy smart contracts, and build autonomous agents with blockchain capabilities.
metadata:
    mintlify-proj: coinbase
    version: "1.0"
---

# Coinbase Developer Platform (CDP) Skill

## Product Summary

Coinbase Developer Platform (CDP) is a unified API platform for building crypto infrastructure at scale. It provides wallets (non-custodial and custodial), payments, trading, stablecoins, onchain tools, and AI agent capabilities. Agents use CDP to create and manage wallets, send transactions, accept payments, onramp/offramp users, execute swaps, and build autonomous blockchain agents. Key resources: **CDP Portal** (https://portal.cdp.coinbase.com) for API key creation, **SDK packages** (TypeScript, Python, Go, Java, Ruby, PHP, C++, C#), **REST API** at `https://api.cdp.coinbase.com/platform/v2`, **Sandbox** at `https://sandbox.cdp.coinbase.com/platform` for testing, and **AgentKit** for AI agent development.

## When to Use

Reach for CDP when:
- **Building wallets**: Create non-custodial wallets for users (with social login, no seed phrases) or API key wallets for backend services
- **Accepting payments**: Set up payment sessions, authorizations, captures, refunds, and disbursements
- **Moving money**: Transfer funds between accounts, onramp/offramp users, settle to banks
- **Trading onchain**: Execute token swaps, get price quotes, manage portfolios
- **Building agents**: Create AI agents that can transact onchain, manage wallets, and execute complex workflows
- **Issuing stablecoins**: Launch branded stablecoins backed 1:1 by USDC
- **Sponsoring gas**: Cover network fees for users via Paymaster
- **Monitoring activity**: Subscribe to webhooks for transaction, signing, and delegation events

## Quick Reference

### Authentication

| Method | Use Case | Key Type |
|--------|----------|----------|
| **Secret API Key + JWT** | Server-to-server REST API calls | `KEY_ID` + `KEY_SECRET` (Ed25519 or ECDSA) |
| **Client API Key** | Client-side JSON-RPC requests | Embedded in RPC endpoint URL |
| **Wallet Secret** | Sensitive wallet operations (signing) | Additional requirement for signing endpoints |

### Environment Setup

```bash
# Create API key in CDP Portal: https://portal.cdp.coinbase.com/api-keys/secret
export KEY_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export KEY_SECRET="base64-encoded-secret"
export REQUEST_METHOD="GET"
export REQUEST_PATH="/platform/v2/evm/token-balances/base-sepolia/0x..."
export REQUEST_HOST="api.cdp.coinbase.com"
```

### SDK Installation

| Language | Command |
|----------|---------|
| **TypeScript** | `npm install @coinbase/cdp-sdk` |
| **Python** | `pip install cdp-sdk` |
| **Go** | `go get github.com/coinbase/cdp-sdk/go` |
| **Java** | Maven/Gradle: `com.coinbase:cdp-sdk` |

### API Conventions

| Element | Format | Example |
|---------|--------|---------|
| **Base URL** | Production: `https://api.cdp.coinbase.com/platform/v2` | `/v2/accounts` |
| **Sandbox** | `https://sandbox.cdp.coinbase.com/platform/v2` | Testing only, isolated |
| **Amounts** | String decimals (never floats) | `"100.00"` not `100.0` |
| **Assets** | Lowercase symbols | `usd`, `usdc`, `eth`, `btc` |
| **Timestamps** | ISO 8601 UTC with Z | `2023-10-08T14:30:00Z` |
| **Resource IDs** | Prefixed UUIDs | `account_af2937b0-...`, `transfer_af2937b0-...` |

### Common Wallet Operations

```typescript
// Create wallet
const account = await cdp.evm.getOrCreateAccount({ name: "MyWallet" });

// Get balance
const balance = await cdp.evm.getBalance({ address: account.address, network: "base" });

// Send transaction
const result = await cdp.evm.sendTransaction({
  address: account.address,
  network: "base-sepolia",
  transaction: { to: "0x...", value: parseEther("0.001") }
});

// Sign message
const signature = await cdp.evm.signMessage({
  address: account.address,
  message: "Hello, blockchain!"
});
```

### Webhook Events

| Event | Trigger | Use Case |
|-------|---------|----------|
| `wallet.transaction.created` | Transaction initiated | Track pending transactions |
| `wallet.transaction.confirmed` | Transaction finalized | Update UI, confirm receipt |
| `wallet.transaction.failed` | Transaction reverted | Alert user, retry logic |
| `wallet.message.signed` | Message signature complete | Verify authentication |
| `payments.transfers.completed` | Transfer settled | Confirm payment received |

## Decision Guidance

### When to Use Non-Custodial vs Custodial Wallets

| Scenario | Non-Custodial | Custodial |
|----------|---------------|-----------|
| **User-facing app** (consumer, gaming, social) | ✓ Users control keys, social login | ✗ |
| **Backend automation** (payouts, treasury) | ✗ | ✓ Easier account management |
| **API key access** | ✓ Server-side via API key | ✓ Verified business account required |
| **User authentication** | ✓ Email, SMS, social login | ✗ Not applicable |
| **Compliance** | ✓ User-custodied | ✓ Coinbase-custodied |

### When to Use Payment Acceptance vs Transfers

| Use Case | Payment Acceptance | Transfers |
|----------|-------------------|-----------|
| **Accept stablecoin payments** | ✓ Full payment stack (auth, capture, refund) | ✗ |
| **Move funds between accounts** | ✗ | ✓ Simple fund movement |
| **Fiat settlement** | ✓ Built-in settlement | ✓ With Payment Methods |
| **Disbursements** | ✓ Payout capability | ✓ Basic transfers |

### When to Use AgentKit vs Direct API

| Approach | AgentKit | Direct API |
|----------|----------|-----------|
| **AI agent framework** | ✓ LangChain, Vercel AI, Eliza | ✗ Manual integration |
| **Wallet management** | ✓ Built-in, abstracted | ✓ Full control |
| **Custom actions** | ✓ Extensible | ✓ Implement yourself |
| **MCP integration** | ✓ Native support | ✗ Manual setup |

## Workflow

### 1. Set Up Authentication

1. Navigate to **CDP Portal** (https://portal.cdp.coinbase.com)
2. Sign in (project auto-created on first login)
3. Go to **API Keys** → **Secret API Keys**
4. Click **Create API key**, name it, select signature algorithm (Ed25519 recommended)
5. Download JSON key file or copy KEY_ID and KEY_SECRET
6. Store securely in environment variables (never commit to version control)
7. Generate JWT using SDK: `generateJwt({ apiKeyId, apiKeySecret, requestMethod, requestHost, requestPath })`

### 2. Create and Manage Wallets

1. **Initialize SDK client** with API key
2. **Create account**: `cdp.evm.getOrCreateAccount({ name: "MyWallet" })`
3. **Get address**: `account.address`
4. **Check balance**: `cdp.evm.getBalance({ address, network })`
5. **Export keys** (if needed): `account.export()` — user retains custody
6. **Subscribe to webhooks** for transaction events

### 3. Send Transactions

1. **Build transaction object** with `to`, `value`, `data` (for contract calls)
2. **Call sendTransaction**: `cdp.evm.sendTransaction({ address, network, transaction })`
3. **SDK handles**: gas estimation, nonce management, signing, broadcasting
4. **Get result**: `transactionHash` for tracking
5. **Wait for confirmation**: `waitForTransactionReceipt(result)`
6. **Handle errors**: Implement exponential backoff for rate limits (HTTP 429)

### 4. Accept Payments

1. **Create payment session**: `POST /v2/payment-sessions` with amount, asset, metadata
2. **Authorize payment**: `POST /v2/payment-sessions/{id}/authorize` with wallet or Coinbase account
3. **Capture funds**: `POST /v2/payment-sessions/{id}/capture` to settle
4. **Handle refunds**: `POST /v2/payment-sessions/{id}/refund` if needed
5. **Subscribe to webhooks**: `payment-session.authorization.succeeded`, `payment-session.capture.succeeded`

### 5. Build an AI Agent

1. **Install AgentKit**: `npm install @coinbase/agentkit`
2. **Choose framework**: LangChain, Vercel AI SDK, or Model Context Protocol
3. **Initialize agent** with wallet provider (CDP, Viem, or Privy)
4. **Define actions**: transfer, swap, deploy contract, or custom actions
5. **Connect to LLM**: Claude, GPT-4, or other model
6. **Test in sandbox** before production
7. **Deploy**: Vercel, AWS Lambda, or self-hosted

## Common Gotchas

- **Never use floats for amounts**: Always use strings (`"100.00"` not `100.0`) to avoid precision loss
- **JWT expiration**: Default 120 seconds; regenerate for long-running operations
- **Rate limits**: Implement exponential backoff; 429 responses require retry with delay
- **Sandbox isolation**: API keys and resources are environment-scoped; can't mix sandbox and production
- **Wallet secrets required**: Signing operations need both Secret API Key AND Wallet Secret
- **Network-specific addresses**: USDC contract address differs by network (Base, Ethereum, etc.)
- **Solana blockhash**: Use placeholder `SysvarRecentB1ockHashes11111111111111111111` for Solana; SDK injects real blockhash
- **Webhook signature verification**: Always verify `X-Hook0-Signature` header using subscription secret
- **Pagination cursors**: Don't reorder results between pages; cursors encode ordering at first request
- **Missing nextPageToken**: Empty or missing token signals end of results, not an error
- **Custodial APIs require verification**: Transfers, payment acceptance, and accounts need verified business account
- **Non-custodial wallets are user-controlled**: You cannot force transactions; users must approve via their auth method

## Verification Checklist

Before submitting work with CDP:

- [ ] **Authentication**: API key created, stored in environment variables, never hardcoded
- [ ] **JWT generation**: Token generated with correct `requestMethod`, `requestHost`, `requestPath`
- [ ] **Network correct**: Using intended network (Base, Ethereum, Solana, testnet, sandbox)
- [ ] **Amounts as strings**: All monetary values are strings, not floats
- [ ] **Error handling**: Implement exponential backoff for rate limits (429)
- [ ] **Webhook verification**: Signature verified using subscription secret
- [ ] **Pagination**: Using `nextPageToken` correctly, stopping when empty
- [ ] **Wallet operations**: Correct account address, network, and transaction structure
- [ ] **Testing**: Verified in sandbox before production
- [ ] **Security**: No API keys in logs, no private keys in client code, Wallet Secret only for signing

## Resources

- **Comprehensive navigation**: https://docs.cdp.coinbase.com/llms.txt
- **CDP API Reference**: https://docs.cdp.coinbase.com/api-reference/v2/introduction
- **AgentKit Documentation**: https://docs.cdp.coinbase.com/agent-kit/welcome
- **Wallets Overview**: https://docs.cdp.coinbase.com/wallets/non-custodial-wallets/overview
- **Authentication Guide**: https://docs.cdp.coinbase.com/get-started/authentication/overview

---

> For additional documentation and navigation, see: https://docs.cdp.coinbase.com/llms.txt