Revamp Build with AI docs section

content/docs.yml

@@ -83,16 +83,22 @@ navigation:
         slug: pricing-resources
       - section: Build with AI
         contents:
-          - page: AI-powered IDEs
-            path: tutorials/build-with-ai/ai-prompting.mdx
-          - page: Add Alchemy RPC To Any Project
-            path: tutorials/build-with-ai/add-alchemy-rpc-to-any-project.mdx
-          - page: Build a Web3 Dashboard
-            path: tutorials/build-with-ai/web3-dashboard-prompt.mdx
-          - page: Learning Alchemy's Data APIs using Cursor
-            path: tutorials/build-with-ai/data-apis-with-cursor.mdx
+          - page: Overview
+            path: tutorials/build-with-ai/overview.mdx
+          - page: Agent Skills
+            path: tutorials/build-with-ai/alchemy-agent-skills.mdx
+          - page: Agent Authentication and Payment
+            path: tutorials/build-with-ai/alchemy-for-agents.mdx
           - page: Alchemy MCP Server
             path: tutorials/build-with-ai/alchemy-mcp-server.mdx
+          - section: Tutorials
+            contents:
+              - page: Add Alchemy RPC To Any Project
+                path: tutorials/build-with-ai/add-alchemy-rpc-to-any-project.mdx
+              - page: Build a Web3 Dashboard
+                path: tutorials/build-with-ai/web3-dashboard-prompt.mdx
+              - page: Learning Alchemy's Data APIs using Cursor
+                path: tutorials/build-with-ai/data-apis-with-cursor.mdx
       - section: Tools
         contents:
           - page: Tools Quickstart

content/tutorials/build-with-ai/alchemy-agent-skills.mdx

@@ -0,0 +1,82 @@
+---
+title: Alchemy Agent Skills
+description: Give your AI coding agent full knowledge of every Alchemy API with a single command. Once installed, your agent knows every endpoint, authentication method, pagination pattern, and error handling strategy without any manual prompting.
+subtitle: Give your AI coding agent full knowledge of every Alchemy API with a single command. Once installed, your agent knows every endpoint, authentication method, pagination pattern, and error handling strategy without any manual prompting.
+slug: docs/alchemy-agent-skills
+---
+
+Skills work with [Claude Code](https://www.anthropic.com/claude-code), [Codex](https://openai.com/index/codex/), [Cursor](https://cursor.com), [VS Code Copilot](https://code.visualstudio.com/docs/copilot/overview), and any AI tool that supports the [Agent Skills specification](https://agentskills.io).
+
+## Install the skills
+
+```bash
+npx skills add alchemyplatform/skills --yes
+```
+
+This installs two skills:
+
+| Skill | Auth method | Best for |
+|---|---|---|
+| `alchemy-api` | API key | You have an [Alchemy API key](https://dashboard.alchemy.com/) and you're building a server or dApp |
+| `agentic-gateway` | Wallet + x402 | Your agent needs to access Alchemy without an API key |
+
+After installation, your agent will ask which path you want before making any API requests.
+
+## What's included
+
+Both skills cover the full Alchemy API surface:
+
+* **Node RPC:** EVM JSON-RPC methods (`eth_*`) and Alchemy-enhanced methods across Ethereum, Base, Arbitrum, BNB, and more
+* **Token API:** `alchemy_getTokenBalances`, `alchemy_getTokenMetadata`, allowances
+* **NFT API:** Ownership lookups, metadata, contract data, spam filtering
+* **Transfers API:** `alchemy_getAssetTransfers` with filtering and pagination
+* **Prices API:** Spot prices by symbol/address, historical price data
+* **Portfolio API:** Multi-chain token balances and NFT data
+* **Simulation API:** `alchemy_simulateAssetChanges` for transaction previews
+* **Webhooks:** Address activity monitoring, webhook creation and signature verification
+* **Solana:** RPC, DAS API (`getAssetsByOwner`), and gRPC streams
+
+Each skill includes endpoint URLs, authentication patterns, code examples, pagination limits, error handling guidance, and network naming conventions.
+
+## Use the `alchemy-api` skill
+
+The `alchemy-api` skill is for developers who have an [Alchemy API key](https://dashboard.alchemy.com/). Set `ALCHEMY_API_KEY` as an environment variable, and your agent handles the rest: it knows every endpoint URL, authentication pattern, and request format across all Alchemy APIs.
+
+If you don't have an API key, create one for free at the [Alchemy Dashboard](https://dashboard.alchemy.com/).
+
+## Use the `agentic-gateway` skill
+
+The `agentic-gateway` skill activates when `$ALCHEMY_API_KEY` isn't set. It teaches your agent how to access Alchemy APIs autonomously using a crypto wallet and the [x402 payment protocol](https://www.x402.org/).
+
+Your agent will walk you through wallet setup and handle the rest:
+
+* **Create or import a wallet:** your agent can set up an EVM wallet (pays USDC on Base) or a Solana wallet (pays USDC on Solana)
+* **Authenticate:** your agent generates a signed token using [SIWE](https://eips.ethereum.org/EIPS/eip-4361) (EVM) or SIWS (Solana) and includes it in API requests
+* **Purchase credits:** your agent buys 1 USDC worth of credits from your wallet. When credits run out, your agent purchases another 1 USDC of credits automatically
+
+Your wallet type only determines authentication and payment. Either wallet type can query any chain across [all networks Alchemy supports](docs/reference/node-supported-chains).
+
+For a full walkthrough of the authentication and payment flow, see [Agent Authentication and Payment](docs/alchemy-for-agents).
+
+## How skills work
+
+Agent Skills follow an open specification. A skill is a Markdown file (`SKILL.md`) that contains structured knowledge (API docs, code examples, decision trees, and rules) that an AI agent reads and follows.
+
+When you run `npx skills add`, the skill files are added to your project. Your AI agent reads these files and uses them as context when writing code or making API requests.
+
+Skills are different from MCP servers:
+
+| | Agent Skills | MCP Server |
+|---|---|---|
+| **What it does** | Teaches the agent *how* to use APIs | Gives the agent *tools* to call APIs directly |
+| **When it's used** | When the agent writes code that uses Alchemy APIs | When the agent needs to query live blockchain data |
+| **Output** | The agent writes code using Alchemy APIs | The agent gets blockchain data back in the conversation |
+
+You can use both together: Skills for API knowledge and MCP for live data queries.
+
+## Next steps
+
+* [GitHub: alchemyplatform/skills](https://github.com/alchemyplatform/skills)
+* [Alchemy Dashboard](https://dashboard.alchemy.com/)
+* [Agent Authentication and Payment](docs/alchemy-for-agents)
+* [Alchemy MCP Server](docs/alchemy-mcp-server)

content/tutorials/build-with-ai/alchemy-for-agents.mdx

@@ -0,0 +1,70 @@
+---
+title: Agent Authentication and Payment
+description: Authenticate your AI agent with an EVM or Solana wallet instead of an API key using SIWE and SIWS. Your agent purchases credits with USDC via the x402 payment protocol.
+subtitle: Authenticate your AI agent with an EVM or Solana wallet instead of an API key using SIWE and SIWS. Your agent purchases credits with USDC via the x402 payment protocol.
+slug: docs/alchemy-for-agents
+---
+
+## How it works
+
+x402 wallet authentication uses three open standards:
+
+* **[SIWE (Sign-In With Ethereum)](https://eips.ethereum.org/EIPS/eip-4361):** Your agent authenticates by signing a message with an EVM wallet.
+* **[SIWS (Sign-In With Solana)](https://phantom.com/learn/developers/sign-in-with-solana):** Adapted from EIP-4361 for Solana's ed25519 signatures. Your agent authenticates with a Solana wallet.
+* **[x402](https://www.x402.org/):** An open protocol for HTTP-native payments. When your agent's credits run out, the server responds with HTTP 402, your agent purchases more credits and retries the request. Zero protocol fees.
+
+## The flow
+
+When your agent needs to access Alchemy APIs without an API key, it handles the full wallet authentication flow:
+
+1. **Wallet setup:** Your agent creates a new wallet or imports an existing one. You choose between an EVM wallet (USDC on Base) or a Solana wallet (USDC on Solana).
+2. **Authentication:** Your agent generates a signed auth token using SIWE (EVM) or SIWS (Solana) and includes it in every API request.
+3. **Credits:** Your agent purchases 1 USDC worth of credits from your wallet. When credits run out, the server responds with HTTP 402, and your agent purchases another 1 USDC of credits automatically.
+
+Your wallet type only determines authentication and payment. Either wallet type can query any chain across [all networks Alchemy supports](docs/reference/node-supported-chains).
+
+## What your agent can access
+
+All standard Alchemy APIs are available through the x402 gateway:
+
+* **Node RPC:** Standard Ethereum JSON-RPC methods (`eth_*`) plus Alchemy-enhanced methods, across 100+ chains
+* **Token API:** Token balances, metadata, and allowances
+* **NFT API:** NFT ownership, metadata, sales, and spam detection
+* **Transfers API:** Asset transfer history with filtering
+* **Prices API:** Spot and historical token prices
+* **Portfolio API:** Multi-chain balances and portfolio data
+* **Simulation API:** Transaction simulation and outcome prediction
+
+These are the same APIs available with a standard API key. The only difference is the authentication and payment mechanism.
+
+## EVM vs Solana wallets
+
+| | EVM wallet | Solana wallet |
+|---|---|---|
+| **Standard** | SIWE (EIP-4361) | SIWS |
+| **Signature** | secp256k1 | ed25519 |
+| **Payment** | USDC on Base | USDC on Solana |
+| **Queryable chains** | [All supported networks](docs/reference/node-supported-chains) | [All supported networks](docs/reference/node-supported-chains) |
+
+## Install as an agent skill
+
+Install the `agentic-gateway` [agent skill](docs/alchemy-agent-skills) so your AI coding agent learns this flow automatically:
+
+```bash
+npx skills add alchemyplatform/skills --yes
+```
+
+Your agent will walk you through wallet setup and handle authentication and payments from there.
+
+## Watch it in action
+
+<div style={{ position: "relative", paddingBottom: "56.25%", height: 0, overflow: "hidden" }}>
+  <iframe style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: "none" }} src="https://player.cloudinary.com/embed/?cloud_name=alchemyapi&private_cdn=true&public_id=docs%2Ftutorials%2Fbuild-with-ai%2Fagent-video_vrudof&profile=cld-default" allow="autoplay; fullscreen; encrypted-media; picture-in-picture" allowFullScreen />
+</div>
+
+## Next steps
+
+* [agents.alchemy.com](https://agents.alchemy.com/)
+* [x402.org](https://www.x402.org/)
+* [EIP-4361: SIWE](https://eips.ethereum.org/EIPS/eip-4361)
+* [Agent Skills](docs/alchemy-agent-skills)

content/tutorials/build-with-ai/alchemy-mcp-server.mdx

@@ -1,17 +1,15 @@
 ---
 title: Alchemy MCP Server
-description: Get started with the Alchemy Model Context Protocol (MCP) server.
-subtitle: Get started with the Alchemy Model Context Protocol (MCP) server.
+description: Query blockchain data from your AI tool with the Alchemy MCP server.
+subtitle: Query blockchain data from your AI tool with the Alchemy MCP server.
 slug: docs/alchemy-mcp-server
 ---
 
-The Model Context Protocol (MCP) is an open protocol designed to allow AI agents, IDEs, and automation tools to consume, query, and analyze structured data through context-aware APIs.
+The [Alchemy MCP Server](https://github.com/alchemyplatform/alchemy-mcp-server) gives your AI tools direct access to blockchain data through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Query token prices, NFT ownership, transaction history, and more as tool calls, with no code required.
 
-This server exposes Alchemy's APIs through the MCP protocol, allowing AI agents and tools to directly query and analyze blockchain data.
+## Add the server to your MCP config
 
-## Quick Setup
-
-To quickly set up the Alchemy MCP server, add this configuration to your MCP config file (typically found in Claude Desktop or Cursor settings):
+Add this configuration to your MCP config file:
 
 ```json
 {
@@ -30,34 +28,88 @@ To quickly set up the Alchemy MCP server, add this configuration to your MCP con
 }
 ```
 
-> The Alchemy MCP server currently only supports [STDIO transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) for local MCP client use. Remote connection to the MCP server via [Streamable-Http transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) is currently in development.
+Get your API key at the [Alchemy Dashboard](https://dashboard.alchemy.com/).
+
+> The Alchemy MCP server currently only supports [STDIO transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) for local MCP client use. Remote connection via [Streamable-HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) is in development.
+
+## Configure your client
+
+### Claude Desktop
+
+Add the configuration above to your Claude Desktop config file:
+
+* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Restart Claude Desktop after saving.
+
+### Cursor
+
+Add the configuration to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-level).
+
+### Claude Code
+
+```bash
+claude mcp add-json "alchemy" '{"command":"npx","args":["-y","@alchemy/mcp-server"],"env":{"ALCHEMY_API_KEY":"YOUR_API_KEY"}}'
+```
+
+### VS Code Copilot
+
+Add to `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "alchemy": {
+      "command": "npx",
+      "args": ["-y", "@alchemy/mcp-server"],
+      "env": {
+        "ALCHEMY_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add the configuration to your Windsurf MCP config file:
+
+* **macOS:** `~/.codeium/windsurf/mcp_config.json`
+* **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
 
-> Want to learn more about Alchemy's MCP Server? Visit the official repo [here](https://github.com/alchemyplatform/alchemy-mcp-server) or read more below!
+## Available tools
 
-## Key Features of Alchemy MCP Server
+The MCP server exposes the following tools:
 
-* Query token prices and price history (including flexible time frame queries)
-* Get NFT ownership information and contract data
-* View transaction history across multiple networks
-* Check token balances across multiple blockchain networks
-* Retrieve detailed asset transfers with filtering
+**Token prices**
+* `fetchTokenPriceBySymbol`: Get current token prices by symbol
+* `fetchTokenPriceByAddress`: Get current token prices by contract address
+* `fetchTokenPriceHistoryBySymbol`: Get historical price data over time
+* `fetchTokenPriceHistoryByTimeFrame`: Get historical price data using flexible time frames or natural language
 
-## How You Would Use The Alchemy MCP Server
+**Token balances**
+* `fetchTokensOwnedByMultichainAddresses`: Get token balances across multiple chains
 
-AI agents like Claude, Cursor, and ChatGPT are “chat agents” by default. To work with MCP, they act as **MCP clients**.
+**Transactions and transfers**
+* `fetchAddressTransactionHistory`: Get single-address transaction history
+* `fetchTransfers`: Get token transfer data with filtering
 
-Within an MCP client like Cursor, you can define an `mcp.json` configuration file that specifies:
+**NFTs**
+* `fetchNftsOwnedByMultichainAddresses`: Get NFT ownership across chains with spam filtering
+* `fetchNftContractDataByMultichainAddress`: Get NFT collection data
 
-* Which MCP servers the agent should connect to
-* What environment variables and arguments to pass so the server runs correctly
+## Supported chains
 
-Once connected, the client instantly gains access to all the tools defined in the server, enabling the LLM to use them in real time.
+We support 50+ blockchains including Ethereum, Base, Polygon, Arbitrum, Optimism, Solana, Starknet, and more.
 
-The main focus right now for Alchemy MCP is on:
+## Watch the walkthrough
 
-* Local developers using Claude Code or Cursor
-* Developers running AI agents locally that need access to blockchain data
+<div style={{ position: "relative", paddingBottom: "56.25%", height: 0, overflow: "hidden" }}>
+  <iframe style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: "none" }} src="https://www.youtube.com/embed/ZhR9O5mC_3Q" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerPolicy="strict-origin-when-cross-origin" allowFullScreen />
+</div>
 
-## Alchemy MCP Video Walkthrough
+## Next steps
 
-<iframe width="560" height="315" src="https://www.youtube.com/embed/ZhR9O5mC_3Q" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+* [GitHub: alchemyplatform/alchemy-mcp-server](https://github.com/alchemyplatform/alchemy-mcp-server)
+* [npm: @alchemy/mcp-server](https://www.npmjs.com/package/@alchemy/mcp-server)