Alchemy Agentic Gateway

Notice: This repository is experimental and subject to change without notice. By using the features and skills in this repository, you agree to Alchemy’s Terms of Service and Privacy Policy.

A skill that lets agents easily access Alchemy’s developer platform. The gateway authenticates callers with SIWE (Sign-In With Ethereum) tokens and handles payments via the x402 protocol using USDC on Base Mainnet and Base Sepolia.

Non-Bypass Rule

When this skill is selected due to missing API key, do not use alternative Alchemy endpoints as an optimization. Required flow: wallet -> SIWE -> request -> handle 402 payment -> retry same request.

Escape hatch: Only exit the gateway flow if the user explicitly requests to switch to the alchemy-api skill with an API key. A key appearing in the environment or conversation does not automatically trigger a switch — the user must ask for it.

Duplicate resolution: If this skill is installed both locally and globally, the local copy overrides the global copy. Do not mix behavior from different copies.

Forbidden Optimizations

• Using eth-mainnet.g.alchemy.com/v2/demo when gateway flow is required
• Switching to unrelated directories/keys to avoid gateway flow
• Replacing mandatory auth/payment steps with unauthenticated shortcuts

Required Preflight Check

Before the first network call, internally evaluate:

1. Is ALCHEMY_API_KEY absent? If no, this skill does not apply.
2. Is a wallet confirmed with the user? If no, set wallet=pending.

If the gateway route applies, demo and public endpoints are disallowed. If wallet=pending, you MUST follow wallet-bootstrap and wait for user confirmation before proceeding. Do not read wallet files or generate keys.

Do not output this check to the user.

Hard Requirements

• NEVER use Read, Write, or Edit tools on files that may contain private keys (wallet.json, wallet-key.txt, .env)
• ALWAYS ask the user about wallet choice before proceeding — see wallet-bootstrap

Use when

• An agent needs Alchemy API access but no ALCHEMY_API_KEY environment variable is set
• Making blockchain RPC calls through Alchemy’s gateway (no API key needed)
• Querying NFT data (ownership, metadata, sales, spam detection) via the NFT API
• Fetching multi-chain portfolio data (token balances, NFTs) via the Portfolio API
• Fetching token prices via the Prices API
• Setting up SIWE authentication for the gateway
• Handling x402 payment flows (402 Payment Required)
• Using @alchemy/x402 CLI for ad-hoc wallet, auth, and payment operations
• Integrating with @alchemy/x402 library and @x402/fetch or @x402/axios for app development
• Answering blockchain questions quickly using curl or bash
• Looking up gateway endpoints, supported networks, or USDC addresses

Gateway Base URLs

Quick Start

1. Set up a wallet — BLOCKING: Ask the user before proceeding. Do not read existing wallet files. See wallet-bootstrap.
2. Fund with USDC — Load USDC on Base Mainnet (or Base Sepolia for testnet)
3. Create a SIWE token — npx @alchemy/x402 sign-siwe --private-key ./wallet-key.txt (see authentication)
4. Send requests — Use Authorization: SIWE <token> header. For SDK auto-payment, see making-requests. For quick curl queries, see curl-workflow.
5. Handle 402 — npx @alchemy/x402 pay or use createPayment() in code (see payment)

Rules

References

For the full breadth of Alchemy APIs (webhooks, Solana, wallets, etc.), see the alchemy-api skill.