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.
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
1---2name: agentic-gateway3description: 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".4license: MIT5---6# Alchemy Agentic Gateway78> **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).910A 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.1112## Non-Bypass Rule1314When this skill is selected due to missing API key, do not use alternative Alchemy endpoints as an optimization.15Required flow: wallet -> SIWE -> request -> handle 402 payment -> retry same request.1617**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.1819**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.2021## Forbidden Optimizations2223- Using `eth-mainnet.g.alchemy.com/v2/demo` when gateway flow is required24- Switching to unrelated directories/keys to avoid gateway flow25- Replacing mandatory auth/payment steps with unauthenticated shortcuts2627## Required Preflight Check2829Before the first network call, internally evaluate:301. Is `ALCHEMY_API_KEY` absent? If no, this skill does not apply.312. Is a wallet confirmed with the user? If no, set `wallet=pending`.3233If the gateway route applies, demo and public endpoints are disallowed.34If `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.3536Do not output this check to the user.3738## Hard Requirements3940- NEVER use Read, Write, or Edit tools on files that may contain private keys (`wallet.json`, `wallet-key.txt`, `.env`)41- ALWAYS ask the user about wallet choice before proceeding — see [wallet-bootstrap](rules/wallet-bootstrap.md)4243## Use when4445- An agent needs Alchemy API access but no `ALCHEMY_API_KEY` environment variable is set46- Making blockchain RPC calls through Alchemy's gateway (no API key needed)47- Querying NFT data (ownership, metadata, sales, spam detection) via the NFT API48- Fetching multi-chain portfolio data (token balances, NFTs) via the Portfolio API49- Fetching token prices via the Prices API50- Setting up SIWE authentication for the gateway51- Handling x402 payment flows (402 Payment Required)52- Using `@alchemy/x402` CLI for ad-hoc wallet, auth, and payment operations53- Integrating with `@alchemy/x402` library and `@x402/fetch` or `@x402/axios` for app development54- Answering blockchain questions quickly using curl or bash55- Looking up gateway endpoints, supported networks, or USDC addresses5657## Gateway Base URLs5859| Product | Gateway URL | Notes |60| --- | --- | --- |61| Node JSON-RPC | `https://x402.alchemy.com/{chainNetwork}/v2` | Standard + enhanced RPC (Token API, Transfers API, Simulation) |62| NFT API | `https://x402.alchemy.com/{chainNetwork}/nft/v3/*` | REST NFT endpoints |63| Prices API | `https://x402.alchemy.com/prices/v1/*` | Token prices (not chain-specific) |64| Portfolio API | `https://x402.alchemy.com/data/v1/*` | Multi-chain portfolio (not chain-specific) |6566## Quick Start67681. **Set up a wallet** — BLOCKING: Ask the user before proceeding. Do not read existing wallet files. See [wallet-bootstrap](rules/wallet-bootstrap.md).692. **Fund with USDC** — Load USDC on Base Mainnet (or Base Sepolia for testnet)703. **Create a SIWE token** — `npx @alchemy/x402 sign-siwe --private-key ./wallet-key.txt` (see [authentication](rules/authentication.md))714. **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).725. **Handle 402** — `npx @alchemy/x402 pay` or use `createPayment()` in code (see [payment](rules/payment.md))7374## Rules7576| Rule | Description |77|------|-------------|78| [wallet-bootstrap](rules/wallet-bootstrap.md) | Set up a wallet (existing or new) and fund it with USDC |79| [overview](rules/overview.md) | What the gateway is, end-to-end flow, required packages |80| [authentication](rules/authentication.md) | SIWE token creation and SIWE message signing |81| [making-requests](rules/making-requests.md) | Sending JSON-RPC requests with `@x402/fetch` or `@x402/axios` |82| [curl-workflow](rules/curl-workflow.md) | Quick RPC calls via curl with token caching (no SDK setup) |83| [payment](rules/payment.md) | Manual x402 payment creation from a 402 response |84| [reference](rules/reference.md) | Endpoints, networks, USDC addresses, headers, status codes |8586## References8788| Gateway route | API methods | Reference file |89|---|---|---|90| `/{chainNetwork}/v2` | `eth_*` standard RPC | [references/node-json-rpc.md](references/node-json-rpc.md) |91| `/{chainNetwork}/v2` | `alchemy_getTokenBalances`, `alchemy_getTokenMetadata`, `alchemy_getTokenAllowance` | [references/data-token-api.md](references/data-token-api.md) |92| `/{chainNetwork}/v2` | `alchemy_getAssetTransfers` | [references/data-transfers-api.md](references/data-transfers-api.md) |93| `/{chainNetwork}/v2` | `alchemy_simulateAssetChanges`, `alchemy_simulateExecution` | [references/data-simulation-api.md](references/data-simulation-api.md) |94| `/{chainNetwork}/nft/v3/*` | `getNFTsForOwner`, `getNFTMetadata`, etc. | [references/data-nft-api.md](references/data-nft-api.md) |95| `/prices/v1/*` | `tokens/by-symbol`, `tokens/by-address`, `tokens/historical` | [references/data-prices-api.md](references/data-prices-api.md) |96| `/data/v1/*` | `assets/tokens/by-address`, `assets/nfts/by-address`, etc. | [references/data-portfolio-apis.md](references/data-portfolio-apis.md) |9798> For the full breadth of Alchemy APIs (webhooks, Solana, wallets, etc.), see the `alchemy-api` skill.99100## Troubleshooting101102### 401 Unauthorized103- `MISSING_AUTH`: Add `Authorization: SIWE <token>` header to your request104- `MESSAGE_EXPIRED`: Regenerate token with `npx @alchemy/x402 sign-siwe --private-key ./wallet-key.txt`105- `INVALID_SIGNATURE` or `INVALID_DOMAIN`: Check that the SIWE message uses domain `x402.alchemy.com` and chainId `8453`106- See [authentication](rules/authentication.md) for the full list of auth error codes107108### 402 Payment Required109- This is expected on first use. Run `npx @alchemy/x402 pay --private-key ./wallet-key.txt --payment-required '<PAYMENT-REQUIRED header>'`110- Ensure your wallet has sufficient USDC on Base Mainnet (or Base Sepolia for testnet)111- After payment, subsequent requests with the same SIWE token return 200112- See [payment](rules/payment.md) for manual payment creation113114### Wallet setup issues115- Never read or write wallet key files with Read/Write/Edit tools116- Always ask the user about wallet choice before proceeding117- See [wallet-bootstrap](rules/wallet-bootstrap.md) for the three wallet setup paths118
vahagn-madatyan