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 because the user chose the agentic flow or because no API key is available, 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:

Did the user explicitly choose the agentic gateway flow? If yes, this skill applies.

If not, 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

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

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