---
name: Base
description: Use when building onchain applications, deploying smart contracts, integrating user authentication and payments, creating AI agents with wallets, or implementing cross-chain functionality. Base is the primary platform for Ethereum Layer 2 development with integrated account abstraction, payments, and agent infrastructure.
metadata:
    mintlify-proj: base
    version: "1.0"
---

# Base Skill Reference

## Product summary

Base is an Ethereum Layer 2 blockchain optimized for low-cost, high-speed transactions. It provides three core products: **Base Chain** (the L2 network itself with RPC APIs), **Base Account** (ERC-4337 smart wallet SDK for authentication and USDC payments), and **AI Agents** (wallet infrastructure and x402 payment protocol for autonomous agents). Key files: `.env` for RPC configuration, smart contracts in `src/` (Foundry), SDK imports from `@base-org/account`. Primary CLI: `forge` (Foundry) for contract deployment. RPC endpoints: `https://mainnet.base.org` (mainnet, rate-limited), `https://sepolia.base.org` (testnet). Chain IDs: 8453 (mainnet), 84532 (testnet). See [docs.base.org](https://docs.base.org) for full documentation.

## When to use

- **Smart contract deployment:** Use when you need to deploy Solidity contracts to Base with low gas costs (<1 cent per transaction).
- **User authentication:** Use Base Account SDK when you need passkey-based sign-in that works across multiple apps and chains.
- **USDC payments:** Use Base Pay when accepting stablecoin payments from users with one-tap checkout and automatic gas sponsorship.
- **AI agent wallets:** Use when building autonomous agents that need to hold funds, sign transactions, and pay for services via x402 protocol.
- **Builder attribution:** Use Builder Codes when you want to track onchain activity generated by your app and unlock rewards.
- **Cross-chain operations:** Use when you need to bridge assets between Base and other EVM chains or Solana.

## Quick reference

### Network Configuration

| Network | Chain ID | RPC Endpoint | Block Explorer | Testnet Faucet |
|---------|----------|--------------|----------------|---|
| Base Mainnet | 8453 | `https://mainnet.base.org` | basescan.org | N/A |
| Base Sepolia | 84532 | `https://sepolia.base.org` | sepolia-explorer.base.org | [Circle Faucet](https://faucet.circle.com) |

### Base Account SDK (Browser)

```javascript
// Initialize SDK
const provider = window.createBaseAccountSDK({
  appName: "Your App",
  appLogoUrl: "https://example.com/logo.png"
}).getProvider();

// Sign in with passkey
const { accounts } = await provider.request({
  method: "wallet_connect",
  params: [{
    version: "1",
    capabilities: {
      signInWithEthereum: { nonce, chainId: "0x2105" }
    }
  }]
});

// One-tap USDC payment
const payment = await window.base.pay({
  amount: "5.00",
  to: "0xRecipient",
  testnet: true
});

// Check payment status
const status = await window.base.getPaymentStatus({
  id: payment.id,
  testnet: true
});
```

### Foundry Deployment

```bash
# Set up environment
mkdir my-base-project && cd my-base-project
curl -L https://foundry.paradigm.xyz | bash
foundryup
forge init

# Configure .env
export BASE_RPC_URL="https://sepolia.base.org"
export BASE_SEPOLIA_RPC_URL="https://sepolia.base.org"

# Store private key securely
cast wallet import deployer --interactive

# Deploy contract
forge create ./src/Counter.sol:Counter \
  --rpc-url $BASE_SEPOLIA_RPC_URL \
  --account deployer \
  --broadcast

# Verify deployment
cast call $COUNTER_CONTRACT_ADDRESS "number()(uint256)" \
  --rpc-url $BASE_SEPOLIA_RPC_URL
```

### AI Agent Wallet Setup

| Wallet | Setup | Best For | Docs |
|--------|-------|----------|------|
| **Bankr** | `install the bankr skill` from agent chat | Trading agents, cross-chain | bankr.bot |
| **CDP Agentic** | `npx skills add coinbase/agentic-wallet-skills` | Email OTP auth, x402 native | docs.cdp.coinbase.com |
| **Sponge** | `curl -X POST https://api.wallet.paysponge.com/api/agents/register` | x402 proxy, multi-chain | wallet.paysponge.com |

### x402 Payment Flow

```bash
# Agent makes request
curl https://api.example.com/data

# Server responds with 402 Payment Required
# Headers: PAYMENT-REQUIRED with amount, token, network

# Agent pays (automatic with wallet)
# Agent retries with PAYMENT-SIGNATURE header

# Server delivers data
```

### Builder Code Integration

```javascript
import { Attribution } from "ox/erc8021";

// Get your code from base.dev Settings → Builder Code
const builderCodeSuffix = Attribution.toDataSuffix({
  codes: ['bc_foobar']
});

await provider.request({
  method: "wallet_sendCalls",
  params: [{
    version: "1.0",
    chainId: "0x2105",
    from: userAddress,
    calls: [{ to: contractAddress, data: callData }],
    capabilities: {
      dataSuffix: {
        value: builderCodeSuffix,
        optional: true
      }
    }
  }]
});
```

## Decision guidance

### When to use Base Account vs traditional wallet connection

| Scenario | Use Base Account | Use Traditional Wallet |
|----------|------------------|----------------------|
| Consumer app needing frictionless onboarding | ✓ | |
| Accepting USDC payments | ✓ | |
| Collecting user email/shipping address | ✓ | |
| Power users with existing wallets | | ✓ |
| Multi-chain DeFi protocol | | ✓ |

### When to use x402 vs API keys

| Scenario | Use x402 | Use API Keys |
|----------|---------|-------------|
| Agent-to-agent payments | ✓ | |
| Per-request billing | ✓ | |
| No pre-existing relationship | ✓ | |
| Subscription model | | ✓ |
| Human user API access | | ✓ |

### When to use Flashblocks vs standard RPC

| Scenario | Use Flashblocks | Use Standard RPC |
|----------|-----------------|------------------|
| MEV-sensitive trading | ✓ | |
| Preconfirmation guarantees needed | ✓ | |
| Standard read/write operations | | ✓ |
| Cost-sensitive queries | | ✓ |

## Workflow

### Deploy a smart contract to Base

1. **Set up environment:** Install Foundry (`foundryup`), create project directory, run `forge init`.
2. **Configure network:** Create `.env` with `BASE_SEPOLIA_RPC_URL="https://sepolia.base.org"`, source it.
3. **Secure private key:** Run `cast wallet import deployer --interactive`, enter your private key and password (stored in `~/.foundry/keystores`).
4. **Write contract:** Place Solidity code in `src/` directory (e.g., `src/Counter.sol`).
5. **Dry run:** Execute `forge create ./src/Counter.sol:Counter --rpc-url $BASE_SEPOLIA_RPC_URL --account deployer` (no `--broadcast` flag).
6. **Deploy:** Add `--broadcast` flag to the same command to actually deploy.
7. **Verify:** Copy deployed contract address, add to `.env`, use `cast call` to test contract methods.
8. **Mainnet:** Switch RPC URL to `https://mainnet.base.org` and repeat (requires real ETH).

### Integrate Base Account for authentication and payments

1. **Install SDK:** Use CDN (`<script src="https://unpkg.com/@base-org/account/dist/base-account.min.js"></script>`) or npm (`npm install @base-org/account`).
2. **Initialize:** Call `createBaseAccountSDK({ appName, appLogoUrl })` to get provider.
3. **Sign in:** Call `provider.request({ method: "wallet_connect", params: [{ capabilities: { signInWithEthereum: { nonce, chainId } } }] })`.
4. **Accept payment:** Call `window.base.pay({ amount, to, testnet })` to trigger payment popup.
5. **Verify server-side:** Call `getPaymentStatus({ id, testnet })` on backend before fulfilling order.
6. **Prevent replay:** Track processed transaction IDs in database; verify sender matches authenticated user.
7. **Test:** Use Base Sepolia testnet with `testnet: true` parameter; get test USDC from Circle Faucet.

### Build an AI agent with wallet and x402 payments

1. **Choose wallet:** Select Bankr, CDP Agentic, or Sponge based on your needs (see Quick Reference table).
2. **Set up wallet:** Install skills (`npx skills add coinbase/agentic-wallet-skills`) or register agent (`curl -X POST https://api.wallet.paysponge.com/api/agents/register`).
3. **Authenticate:** For CDP, ask agent to sign in with email OTP; for Sponge, store returned `apiKey`.
4. **Register agent:** Call agent registration endpoint to publish identity onchain (ERC-8004 + Basename).
5. **Make x402 request:** Agent makes HTTP request to paid API; server responds with 402 Payment Required; agent signs payment; server delivers data.
6. **Gate your endpoint:** Use `monetize-service` skill or x402-express middleware to accept payments from other agents.
7. **Verify:** Check agent identity onchain; validate payment signatures before serving data.

### Register for Builder Code attribution

1. **Register app:** Go to [base.dev](https://base.dev), sign in, navigate to Settings → Builder Code.
2. **Copy code:** Note your unique code (e.g., `bc_foobar`).
3. **Integrate suffix:** Use `Attribution.toDataSuffix({ codes: ['bc_foobar'] })` from `ox/erc8021` package.
4. **Append to transactions:** Pass `dataSuffix` capability in `wallet_sendCalls` with `optional: true`.
5. **Verify attribution:** Check base.dev dashboard or use [Builder Code Validation Tool](https://builder-code-checker.vercel.app/).
6. **Track rewards:** Monitor transaction counts in base.dev; rewards unlock as program expands.

## Common gotchas

- **Private key in prompt history:** Never generate private keys in agent prompts. Use dedicated wallet services (Bankr, CDP, Sponge) that manage keys in secure infrastructure.
- **testnet parameter mismatch:** If you call `pay({ testnet: true })`, you must also call `getPaymentStatus({ testnet: true })`. Mismatched parameters cause status lookup failures.
- **Replay attacks on payments:** Always track processed transaction IDs in your database and verify the payment sender matches the authenticated user before fulfilling orders.
- **Builder Code gas cost:** ERC-8021 suffix adds ~16 gas per non-zero byte. Keep suffixes small; set `optional: true` if attribution is not critical.
- **Rate-limited public RPC:** `https://mainnet.base.org` and `https://sepolia.base.org` are rate-limited. Use node providers (Alchemy, Infura, Chainstack) or run your own node for production.
- **Smart contract doesn't ignore suffix:** Contracts execute normally with ERC-8021 suffix appended to calldata. No contract upgrades needed; indexers extract attribution offchain.
- **Missing --broadcast flag:** `forge create` without `--broadcast` only simulates deployment. Always add `--broadcast` to actually deploy to the network.
- **Unsupported wallet for ERC-8021:** Not all wallets support `dataSuffix` capability. EOAs support it by default; check wallet docs for smart wallet support (Privy, Turnkey, etc.).
- **x402 without funded wallet:** Agent must have USDC balance to pay for x402 requests. Fund wallet before making paid API calls.
- **Testnet ETH depletion:** Base Sepolia faucets have rate limits. Request test ETH during off-peak hours; use multiple faucets if needed.

## Verification checklist

Before submitting work:

- [ ] **Network configuration:** Verify RPC URL and chain ID match intended network (8453 for mainnet, 84532 for testnet).
- [ ] **Private key security:** Confirm private key is stored in `~/.foundry/keystores` (not in `.env` or code).
- [ ] **Contract deployment:** Check contract address on block explorer (basescan.org or sepolia-explorer.base.org).
- [ ] **SDK initialization:** Verify `createBaseAccountSDK` is called with `appName` and `appLogoUrl`.
- [ ] **Payment testnet flag:** Confirm `testnet: true` in both `pay()` and `getPaymentStatus()` calls for testnet; `false` or omitted for mainnet.
- [ ] **Server-side validation:** Verify backend checks payment status and prevents replay attacks before fulfilling orders.
- [ ] **Builder Code registration:** Confirm code is registered on base.dev and integrated with `dataSuffix` capability.
- [ ] **Agent wallet funded:** Check agent has USDC balance before making x402 requests.
- [ ] **Error handling:** Verify try-catch blocks handle payment failures, network errors, and signature validation errors.
- [ ] **Brand compliance:** If using BasePayButton or SignInWithBaseButton, follow [Brand Guidelines](/base-account/reference/ui-elements/brand-guidelines).

## Resources

- **Comprehensive navigation:** [docs.base.org/llms.txt](https://docs.base.org/llms.txt) — complete page-by-page listing for agent reference.
- **Base Account SDK:** [base-account/overview/what-is-base-account](/base-account/overview/what-is-base-account) — authentication, payments, and smart wallet features.
- **AI Agents:** [ai-agents/index](/ai-agents/index) — wallet setup, x402 protocol, trading, and agent registration.
- **Smart Contract Deployment:** [base-chain/quickstart/deploy-on-base](/base-chain/quickstart/deploy-on-base) — Foundry setup and contract deployment guide.

---

> For additional documentation and navigation, see: https://docs.base.org/llms.txt