agentic-gateway

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:

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

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.
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

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

Gateway route	API methods	Reference file
/{chainNetwork}/v2	eth_* standard RPC	references/node-json-rpc.md
/{chainNetwork}/v2	alchemy_getTokenBalances, alchemy_getTokenMetadata, alchemy_getTokenAllowance	references/data-token-api.md
/{chainNetwork}/v2	alchemy_getAssetTransfers	references/data-transfers-api.md
/{chainNetwork}/v2	alchemy_simulateAssetChanges, alchemy_simulateExecution	references/data-simulation-api.md
/{chainNetwork}/nft/v3/*	getNFTsForOwner, getNFTMetadata, etc.	references/data-nft-api.md
/prices/v1/*	tokens/by-symbol, tokens/by-address, tokens/historical	references/data-prices-api.md
/data/v1/*	assets/tokens/by-address, assets/nfts/by-address, etc.	references/data-portfolio-apis.md

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