| name | agentic-gateway |
| description | Use when an agent wants to access Alchemy APIs without an API key. This is the
default path when $ALCHEMY_API_KEY is not set. Covers SIWE authentication,
x402 payment flows, wallet setup, and gateway endpoints.
|
| metadata | {"author":"alchemyplatform","version":"1.0"} |
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:
- Is
ALCHEMY_API_KEY absent? If no, this skill does not apply.
- 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
| Product | Gateway URL | Notes |
|---|
| Node JSON-RPC | https://x402.alchemy.com/{chainNetwork}/v2 | Standard + enhanced RPC (Token API, Transfers API, Simulation) |
| NFT API | https://x402.alchemy.com/{chainNetwork}/nft/v3/* | REST NFT endpoints |
| Prices API | https://x402.alchemy.com/prices/v1/* | Token prices (not chain-specific) |
| Portfolio API | https://x402.alchemy.com/data/v1/* | Multi-chain portfolio (not chain-specific) |
Quick Start
- Set up a wallet — BLOCKING: Ask the user before proceeding. Do not read existing wallet files. See wallet-bootstrap.
- Fund with USDC — Load USDC on Base Mainnet (or Base Sepolia for testnet)
- Create a SIWE token —
npx @alchemy/x402 sign-siwe --private-key ./wallet-key.txt (see authentication)
- Send requests — Use
Authorization: SIWE <token> header. For SDK auto-payment, see making-requests. For quick curl queries, see curl-workflow.
- Handle 402 —
npx @alchemy/x402 pay or use createPayment() in code (see payment)
Rules
| Rule | Description |
|---|
| wallet-bootstrap | Set up a wallet (existing or new) and fund it with USDC |
| overview | What the gateway is, end-to-end flow, required packages |
| authentication | SIWE token creation and SIWE message signing |
| making-requests | Sending JSON-RPC requests with @x402/fetch or @x402/axios |
| curl-workflow | Quick RPC calls via curl with token caching (no SDK setup) |
| payment | Manual x402 payment creation from a 402 response |
| reference | Endpoints, networks, USDC addresses, headers, status codes |
References
For the full breadth of Alchemy APIs (webhooks, Solana, wallets, etc.), see the alchemy-api skill.
