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
| 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.
1---2name: agentic-gateway3description: 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.4---5# Alchemy Agentic Gateway67> **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).89A 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.1011## Non-Bypass Rule1213When this skill is selected due to missing API key, do not use alternative Alchemy endpoints as an optimization.14Required flow: wallet -> SIWE -> request -> handle 402 payment -> retry same request.1516**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.1718**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.1920## Forbidden Optimizations2122- Using `eth-mainnet.g.alchemy.com/v2/demo` when gateway flow is required23- Switching to unrelated directories/keys to avoid gateway flow24- Replacing mandatory auth/payment steps with unauthenticated shortcuts2526## Required Preflight Check2728Before the first network call, internally evaluate:291. Is `ALCHEMY_API_KEY` absent? If no, this skill does not apply.302. Is a wallet confirmed with the user? If no, set `wallet=pending`.3132If the gateway route applies, demo and public endpoints are disallowed.33If `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.3435Do not output this check to the user.3637## Hard Requirements3839- NEVER use Read, Write, or Edit tools on files that may contain private keys (`wallet.json`, `wallet-key.txt`, `.env`)40- ALWAYS ask the user about wallet choice before proceeding — see [wallet-bootstrap](rules/wallet-bootstrap.md)4142## Use when4344- An agent needs Alchemy API access but no `ALCHEMY_API_KEY` environment variable is set45- Making blockchain RPC calls through Alchemy's gateway (no API key needed)46- Querying NFT data (ownership, metadata, sales, spam detection) via the NFT API47- Fetching multi-chain portfolio data (token balances, NFTs) via the Portfolio API48- Fetching token prices via the Prices API49- Setting up SIWE authentication for the gateway50- Handling x402 payment flows (402 Payment Required)51- Using `@alchemy/x402` CLI for ad-hoc wallet, auth, and payment operations52- Integrating with `@alchemy/x402` library and `@x402/fetch` or `@x402/axios` for app development53- Answering blockchain questions quickly using curl or bash54- Looking up gateway endpoints, supported networks, or USDC addresses5556## Gateway Base URLs5758| Product | Gateway URL | Notes |59| --- | --- | --- |60| Node JSON-RPC | `https://x402.alchemy.com/{chainNetwork}/v2` | Standard + enhanced RPC (Token API, Transfers API, Simulation) |61| NFT API | `https://x402.alchemy.com/{chainNetwork}/nft/v3/*` | REST NFT endpoints |62| Prices API | `https://x402.alchemy.com/prices/v1/*` | Token prices (not chain-specific) |63| Portfolio API | `https://x402.alchemy.com/data/v1/*` | Multi-chain portfolio (not chain-specific) |6465## Quick Start66671. **Set up a wallet** — BLOCKING: Ask the user before proceeding. Do not read existing wallet files. See [wallet-bootstrap](rules/wallet-bootstrap.md).682. **Fund with USDC** — Load USDC on Base Mainnet (or Base Sepolia for testnet)693. **Create a SIWE token** — `npx @alchemy/x402 sign-siwe --private-key ./wallet-key.txt` (see [authentication](rules/authentication.md))704. **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).715. **Handle 402** — `npx @alchemy/x402 pay` or use `createPayment()` in code (see [payment](rules/payment.md))7273## Rules7475| Rule | Description |76|------|-------------|77| [wallet-bootstrap](rules/wallet-bootstrap.md) | Set up a wallet (existing or new) and fund it with USDC |78| [overview](rules/overview.md) | What the gateway is, end-to-end flow, required packages |79| [authentication](rules/authentication.md) | SIWE token creation and SIWE message signing |80| [making-requests](rules/making-requests.md) | Sending JSON-RPC requests with `@x402/fetch` or `@x402/axios` |81| [curl-workflow](rules/curl-workflow.md) | Quick RPC calls via curl with token caching (no SDK setup) |82| [payment](rules/payment.md) | Manual x402 payment creation from a 402 response |83| [reference](rules/reference.md) | Endpoints, networks, USDC addresses, headers, status codes |8485## References8687| Gateway route | API methods | Reference file |88|---|---|---|89| `/{chainNetwork}/v2` | `eth_*` standard RPC | [references/node-json-rpc.md](references/node-json-rpc.md) |90| `/{chainNetwork}/v2` | `alchemy_getTokenBalances`, `alchemy_getTokenMetadata`, `alchemy_getTokenAllowance` | [references/data-token-api.md](references/data-token-api.md) |91| `/{chainNetwork}/v2` | `alchemy_getAssetTransfers` | [references/data-transfers-api.md](references/data-transfers-api.md) |92| `/{chainNetwork}/v2` | `alchemy_simulateAssetChanges`, `alchemy_simulateExecution` | [references/data-simulation-api.md](references/data-simulation-api.md) |93| `/{chainNetwork}/nft/v3/*` | `getNFTsForOwner`, `getNFTMetadata`, etc. | [references/data-nft-api.md](references/data-nft-api.md) |94| `/prices/v1/*` | `tokens/by-symbol`, `tokens/by-address`, `tokens/historical` | [references/data-prices-api.md](references/data-prices-api.md) |95| `/data/v1/*` | `assets/tokens/by-address`, `assets/nfts/by-address`, etc. | [references/data-portfolio-apis.md](references/data-portfolio-apis.md) |9697> For the full breadth of Alchemy APIs (webhooks, Solana, wallets, etc.), see the `alchemy-api` skill.98
sentientsprite