| name | agentic-gateway |
| description | Lets agents access Alchemy APIs without an API key using wallet-based SIWE authentication and x402 USDC payments. Default path when $ALCHEMY_API_KEY is not set. Use when user asks to query blockchain data, check token balances, look up NFTs, fetch prices, or call Alchemy APIs without an API key, or mentions "SIWE", "x402", "agentic gateway", or "wallet-based auth". |
| license | MIT |
| compatibility | Requires network access, Node.js (npx), and an Ethereum wallet funded with USDC on Base. Works across Claude.ai, Claude Code, and API. |
| 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.
Troubleshooting
401 Unauthorized
MISSING_AUTH: Add Authorization: SIWE <token> header to your requestMESSAGE_EXPIRED: Regenerate token with npx @alchemy/x402 sign-siwe --private-key ./wallet-key.txtINVALID_SIGNATURE or INVALID_DOMAIN: Check that the SIWE message uses domain x402.alchemy.com and chainId 8453- See authentication for the full list of auth error codes
402 Payment Required
- This is expected on first use. Run
npx @alchemy/x402 pay --private-key ./wallet-key.txt --payment-required '<PAYMENT-REQUIRED header>'
- Ensure your wallet has sufficient USDC on Base Mainnet (or Base Sepolia for testnet)
- After payment, subsequent requests with the same SIWE token return 200
- See payment for manual payment creation
Wallet setup issues
- Never read or write wallet key files with Read/Write/Edit tools
- Always ask the user about wallet choice before proceeding
- See wallet-bootstrap for the three wallet setup paths
