# Agentic Gateway

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

- Skill: `vahagn-madatyan/agentic-gateway` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add vahagn-madatyan/agentic-gateway`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vahagn-madatyan/agentic-gateway/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: vahagn-madatyan (https://skillmd.com/u/vahagn-madatyan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vahagn-madatyan/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.

## Troubleshooting

### 401 Unauthorized
- `MISSING_AUTH`: Add `Authorization: SIWE <token>` header to your request
- `MESSAGE_EXPIRED`: Regenerate token with `npx @alchemy/x402 sign-siwe --private-key ./wallet-key.txt`
- `INVALID_SIGNATURE` or `INVALID_DOMAIN`: Check that the SIWE message uses domain `x402.alchemy.com` and chainId `8453`
- See [authentication](rules/authentication.md) 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](rules/payment.md) 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](rules/wallet-bootstrap.md) for the three wallet setup paths