agentic-gateway

# 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](https://legal.alchemy.com/) and [Privacy Policy](https://legal.alchemy.com/#contract-sblyf8eub). 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](rules/wallet-bootstrap.md) 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](rules/wallet-bootstrap.md) ## 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 1. **Set up a wallet** — BLOCKING: Ask the user before proceeding. Do not read existing wallet files. See [wallet-bootstrap](rules/wallet-bootstrap.md). 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](rules/authentication.md)) 4. **Send requests** — Use `Authorization: SIWE <token>` header. For SDK auto-payment, see [making-requests](rules/making-requests.md). For quick curl queries, see [curl-workflow](rules/curl-workflow.md). 5. **Handle 402** — `npx @alchemy/x402 pay` or use `createPayment()` in code (see [payment](rules/payment.md)) ## Rules | Rule | Description | |------|-------------| | [wallet-bootstrap](rules/wallet-bootstrap.md) | Set up a wallet (existing or new) and fund it with USDC | | [overview](rules/overview.md) | What the gateway is, end-to-end flow, required packages | | [authentication](rules/authentication.md) | SIWE token creation and SIWE message signing | | [making-requests](rules/making-requests.md) | Sending JSON-RPC requests with `@x402/fetch` or `@x402/axios` | | [curl-workflow](rules/curl-workflow.md) | Quick RPC calls via curl with token caching (no SDK setup) | | [payment](rules/payment.md) | Manual x402 payment creation from a 402 response | | [reference](rules/reference.md) | Endpoints, networks, USDC addresses, headers, status codes | ## References | Gateway route | API methods | Reference file | |---|---|---| | `/{chainNetwork}/v2` | `eth_*` standard RPC | [references/node-json-rpc.md](references/node-json-rpc.md) | | `/{chainNetwork}/v2` | `alchemy_getTokenBalances`, `alchemy_getTokenMetadata`, `alchemy_getTokenAllowance` | [references/data-token-api.md](references/data-token-api.md) | | `/{chainNetwork}/v2` | `alchemy_getAssetTransfers` | [references/data-transfers-api.md](references/data-transfers-api.md) | | `/{chainNetwork}/v2` | `alchemy_simulateAssetChanges`, `alchemy_simulateExecution` | [references/data-simulation-api.md](references/data-simulation-api.md) | | `/{chainNetwork}/nft/v3/*` | `getNFTsForOwner`, `getNFTMetadata`, etc. | [references/data-nft-api.md](references/data-nft-api.md) | | `/prices/v1/*` | `tokens/by-symbol`, `tokens/by-address`, `tokens/historical` | [references/data-prices-api.md](references/data-prices-api.md) | | `/data/v1/*` | `assets/tokens/by-address`, `assets/nfts/by-address`, etc. | [references/data-portfolio-apis.md](references/data-portfolio-apis.md) | > For the full breadth of Alchemy APIs (webhooks, Solana, wallets, etc.), see the `alchemy-api` skill.