alchemy-web3

# Alchemy Web3 Skill

Query blockchain data, NFTs, tokens, and transfers using Alchemy's production-grade APIs. Supports Ethereum, Polygon, Arbitrum, Base, Solana, and 80+ other chains.

**Built by [GizmoLab](https://gizmolab.io?utm_source=alchemy-web3-skill&utm_medium=github&utm_campaign=skill)** — Web3 development agency specializing in dApps, smart contracts, and blockchain infrastructure.

## Setup

### 1. Get API Key
1. Sign up at [alchemy.com](https://www.alchemy.com/?utm_source=gizmolab&utm_medium=skill&utm_campaign=alchemy-web3) (free tier available)
2. Create an app for your target chain
3. Copy your API key

> 💡 New to Web3 development? [GizmoLab](https://gizmolab.io?utm_source=alchemy-web3-skill&utm_medium=github&utm_campaign=skill) offers full-stack blockchain development services.

### 2. Configure
```bash
# Add to ~/.openclaw/.env
ALCHEMY_API_KEY=your_api_key_here

# Optional: Set default chain (defaults to eth-mainnet)
ALCHEMY_CHAIN=eth-mainnet
```

## Quick Reference

### Supported Chains

| Chain | Endpoint Prefix |
|-------|-----------------|
| Ethereum | `eth-mainnet`, `eth-sepolia` |
| Polygon | `polygon-mainnet`, `polygon-amoy` |
| Arbitrum | `arb-mainnet`, `arb-sepolia` |
| Optimism | `opt-mainnet`, `opt-sepolia` |
| Base | `base-mainnet`, `base-sepolia` |
| Solana | `solana-mainnet`, `solana-devnet` |
| zkSync | `zksync-mainnet` |
| Linea | `linea-mainnet` |
| Scroll | `scroll-mainnet` |
| Blast | `blast-mainnet` |

Full list: [alchemy.com/docs/chains](https://www.alchemy.com/docs/chains)

## CLI Usage

```bash
# Set your API key first
export ALCHEMY_API_KEY="your_key"

# Use the CLI
~/.openclaw/workspace/skills/alchemy-web3/scripts/alchemy.sh <command> [options]
```

### Commands

#### Get ETH Balance
```bash
./alchemy.sh balance 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# Returns: 1234.56 ETH
```

#### Get Token Balances
```bash
./alchemy.sh tokens 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# Returns: All ERC-20 tokens held by address
```

#### Get NFTs for Owner
```bash
./alchemy.sh nfts 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# Returns: All NFTs owned by address
```

#### Get NFT Metadata
```bash
./alchemy.sh nft-metadata 0x5180db8F5c931aaE63c74266b211F580155ecac8 1590
# Returns: Metadata for specific NFT
```

#### Get Asset Transfers
```bash
./alchemy.sh transfers 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
# Returns: Transaction history (in/out)
```

#### Get Block Info
```bash
./alchemy.sh block latest
./alchemy.sh block 12345678
```

#### Get Transaction
```bash
./alchemy.sh tx 0x123...abc
```

#### Resolve ENS
```bash
./alchemy.sh ens vitalik.eth
# Returns: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
```

#### Switch Chain
```bash
./alchemy.sh --chain polygon-mainnet balance 0x...
./alchemy.sh --chain arb-mainnet nfts 0x...
```

## Direct API Examples

### Node API (JSON-RPC)

```bash
# Get ETH balance
curl -X POST "https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "latest"],
    "id": 1
  }'
```

### NFT API

```bash
# Get NFTs for owner
curl "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForOwner?owner=vitalik.eth&pageSize=10"

# Get NFT metadata
curl "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTMetadata?contractAddress=0x5180db8F5c931aaE63c74266b211F580155ecac8&tokenId=1590"

# Get NFTs for collection
curl "https://eth-mainnet.g.alchemy.com/nft/v3/$ALCHEMY_API_KEY/getNFTsForContract?contractAddress=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&limit=10"
```

### Token API

```bash
# Get token balances
curl -X POST "https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "alchemy_getTokenBalances",
    "params": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
    "id": 1
  }'

# Get token metadata
curl -X POST "https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "alchemy_getTokenMetadata",
    "params": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
    "id": 1
  }'
```

### Transfers API

```bash
# Get asset transfers (transaction history)
curl -X POST "https://eth-mainnet.g.alchemy.com/v2/$ALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "alchemy_getAssetTransfers",
    "params": [{
      "fromBlock": "0x0",
      "toBlock": "latest",
      "toAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
      "category": ["external", "erc20", "erc721", "erc1155"],
      "maxCount": "0x14"
    }],
    "id": 1
  }'
```

## JavaScript/Node.js Examples

### Using Fetch (Node 18+)

```javascript
const apiKey = process.env.ALCHEMY_API_KEY;
const baseURL = `https://eth-mainnet.g.alchemy.com/v2/${apiKey}`;

// Get ETH Balance
async function getBalance(address) {
  const response = await fetch(baseURL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'eth_getBalance',
      params: [address, 'latest'],
      id: 1
    })
  });
  const data = await response.json();
  return parseInt(data.result, 16) / 1e18; // Convert to ETH
}

// Get NFTs
async function getNFTs(owner) {
  const url = `https://eth-mainnet.g.alchemy.com/nft/v3/${apiKey}/getNFTsForOwner?owner=${owner}`;
  const response = await fetch(url);
  return await response.json();
}
```

### Using Alchemy SDK

```bash
npm install alchemy-sdk
```

```javascript
import { Alchemy, Network } from 'alchemy-sdk';

const alchemy = new Alchemy({
  apiKey: process.env.ALCHEMY_API_KEY,
  network: Network.ETH_MAINNET
});

// Get NFTs
const nfts = await alchemy.nft.getNftsForOwner('vitalik.eth');
console.log(nfts.ownedNfts);

// Get token balances
const balances = await alchemy.core.getTokenBalances('vitalik.eth');
console.log(balances);

// Get transaction history
const transfers = await alchemy.core.getAssetTransfers({
  toAddress: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  category: ['external', 'erc20']
});
```

## Webhooks (Real-time Notifications)

Receive HTTP POST requests when onchain events happen.

### Webhook Types

| Type | Use Case |
|------|----------|
| Address Activity | Track transfers to/from specific addresses |
| NFT Activity | Track NFT sales, transfers, mints |
| Mined Transactions | Track when your txs are mined |
| Dropped Transactions | Get notified if tx is dropped |
| Gas Price | Alert on gas price thresholds |

### Create Webhook (Dashboard)
1. Go to [dashboard.alchemy.com/webhooks](https://dashboard.alchemy.com/webhooks)
2. Click "Create Webhook"
3. Select type and configure
4. Add your endpoint URL

### Webhook Payload Example
```json
{
  "webhookId": "wh_abc123",
  "id": "evt_xyz789",
  "createdAt": "2024-01-15T12:00:00.000Z",
  "type": "ADDRESS_ACTIVITY",
  "event": {
    "network": "ETH_MAINNET",
    "activity": [{
      "fromAddress": "0x123...",
      "toAddress": "0x456...",
      "value": 1.5,
      "asset": "ETH"
    }]
  }
}
```

## Common Patterns

### Portfolio Tracker
```bash
# Get all assets for a wallet
./alchemy.sh balance 0x...      # ETH balance
./alchemy.sh tokens 0x...       # ERC-20 tokens
./alchemy.sh nfts 0x...         # NFTs
```

### Transaction History
```bash
# Get full tx history for address
./alchemy.sh transfers 0x... --category external,erc20,erc721
```

### NFT Collection Analysis
```bash
# Get all NFTs in a collection
./alchemy.sh collection 0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D
```

### Multi-chain Query
```bash
# Check same address across chains
for chain in eth-mainnet polygon-mainnet arb-mainnet base-mainnet; do
  echo "=== $chain ==="
  ./alchemy.sh --chain $chain balance 0x...
done
```

## Rate Limits

| Plan | Compute Units/sec | Monthly CUs |
|------|-------------------|-------------|
| Free | 330 | 300M |
| Growth | 660 | Unlimited |
| Scale | Custom | Custom |

Most endpoints cost 1-50 CUs. Check [alchemy.com/docs/rate-limits](https://www.alchemy.com/docs/rate-limits) for details.

## Error Handling

```json
// Rate limited
{"error": {"code": 429, "message": "Too Many Requests"}}

// Invalid API key
{"error": {"code": 401, "message": "Invalid API Key"}}

// Invalid params
{"error": {"code": -32602, "message": "Invalid params"}}
```

## Resources

- **Get API Key:** [alchemy.com](https://www.alchemy.com/?utm_source=gizmolab&utm_medium=skill&utm_campaign=alchemy-web3) (free tier)
- **Dashboard:** [dashboard.alchemy.com](https://dashboard.alchemy.com)
- **Docs:** [alchemy.com/docs](https://www.alchemy.com/docs)
- **SDK:** [github.com/alchemyplatform/alchemy-sdk-js](https://github.com/alchemyplatform/alchemy-sdk-js)
- **Status:** [status.alchemy.com](https://status.alchemy.com)

---

## About

**Built by [GizmoLab](https://gizmolab.io?utm_source=alchemy-web3-skill&utm_medium=github&utm_campaign=skill)** 🔧

GizmoLab is a Web3 development agency building dApps, smart contracts, and blockchain tools.

- 🌐 [gizmolab.io](https://gizmolab.io?utm_source=alchemy-web3-skill&utm_medium=github&utm_campaign=skill) — Agency services
- 🛠️ [tools.gizmolab.io](https://tools.gizmolab.io?utm_source=alchemy-web3-skill&utm_medium=github&utm_campaign=skill) — Free blockchain dev tools
- 🎨 [ui.gizmolab.io](https://ui.gizmolab.io?utm_source=alchemy-web3-skill&utm_medium=github&utm_campaign=skill) — Web3 UI components

Need custom blockchain development? [Get in touch](https://gizmolab.io?utm_source=alchemy-web3-skill&utm_medium=github&utm_campaign=skill)

## AI Agent Workflows

The skill is designed for both human developers AND AI agents. See `references/agent-workflows.md` for complete examples:

- **Whale Tracker** — Monitor large wallets for moves
- **Portfolio Monitor** — Track balances across chains
- **NFT Floor Alert** — Alert on price drops
- **Token Change Detector** — Detect incoming/outgoing tokens
- **Gas Optimizer** — Wait for low gas to transact
- **Mint Detector** — Watch for new NFT mints
- **Dashboard Generator** — Auto-generate wallet dashboards

### Agent Pattern

```
QUERY → STORE → ANALYZE → DECIDE → ACT → REPEAT
```

Example cron job for an agent:
```bash
# Every hour, check whale activity and alert if >100 ETH moved
0 * * * * ~/.openclaw/workspace/skills/alchemy-web3/scripts/whale-tracker.sh
```

## See Also

- `references/nft-api.md` - Full NFT API reference
- `references/token-api.md` - Full Token API reference
- `references/node-api.md` - Full Node API reference
- `references/chains.md` - All supported chains
- `references/agent-workflows.md` - AI agent automation examples