Back to Details

agentic-gateway

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Alchemy Agentic Gateway

Alchemy Agentic 网关

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.
注意： 本仓库为实验性版本，可能会未经通知就进行变更。使用本仓库中的功能和技能，即表示您同意Alchemy的服务条款和隐私政策。
这是一项能让Agent轻松访问Alchemy开发者平台的技能。该网关通过SIWE（Sign-In With Ethereum）令牌对调用者进行身份验证，并使用Base主网和Base Sepolia上的USDC，通过x402协议处理支付。

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.
当因缺少API密钥而选择此技能时，请勿使用其他Alchemy端点作为优化手段。 必需流程：钱包 -> SIWE -> 请求 -> 处理402支付 -> 重试相同请求。
逃生通道： 只有当用户明确要求切换到带API密钥的
alchemy-api
技能时，才能退出网关流程。环境或对话中出现密钥并不会自动触发切换——必须由用户主动提出。
重复安装处理： 若此技能同时在本地和全局安装，本地副本将覆盖全局副本。请勿混合不同副本的行为。

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
  • 当需要走网关流程时，使用
    eth-mainnet.g.alchemy.com/v2/demo
    端点
  • 切换到无关目录/密钥以规避网关流程
  • 用未验证的快捷方式替代必需的身份验证/支付步骤

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.
在首次发起网络调用前，需内部评估：
  1. 是否未设置
    ALCHEMY_API_KEY
    ？若已设置，则此技能不适用。
  2. 是否已与用户确认钱包信息？若未确认，则设置
    wallet=pending
    。
若适用网关路径，则禁止使用演示和公共端点。 若
wallet=pending
，您必须遵循钱包引导流程，并等待用户确认后再继续。请勿读取钱包文件或生成密钥。
请勿将此检查过程告知用户。

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
  • 绝不能对可能包含私钥的文件（如
    wallet.json
    、
    wallet-key.txt
    、
    .env
    ）使用读取、写入或编辑工具
  • 在继续操作前，必须询问用户选择的钱包——详见钱包引导流程

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
  • Agent需要访问Alchemy API，但未设置
    ALCHEMY_API_KEY
    环境变量时
  • 通过Alchemy网关发起区块链RPC调用（无需API密钥）时
  • 通过NFT API查询NFT数据（所有权、元数据、交易记录、垃圾检测）时
  • 通过Portfolio API获取多链资产组合数据（代币余额、NFT）时
  • 通过Prices API获取代币价格时
  • 为网关设置SIWE身份验证时
  • 处理x402支付流程（402 Payment Required）时
  • 使用
    @alchemy/x402
    CLI进行临时钱包、身份验证和支付操作时
  • 在应用开发中集成
    @alchemy/x402
    库以及
    @x402/fetch
    或
    @x402/axios
    时
  • 使用curl或bash快速回答区块链相关问题时
  • 查询网关端点、支持的网络或USDC地址时

Gateway Base URLs

网关基础URL

ProductGateway URLNotes
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)
产品网关URL说明
Node JSON-RPC
https://x402.alchemy.com/{chainNetwork}/v2
标准增强型RPC（包含Token API、Transfers API、模拟功能）
NFT API
https://x402.alchemy.com/{chainNetwork}/nft/v3/*
REST NFT端点
Prices API
https://x402.alchemy.com/prices/v1/*
代币价格（与链无关）
Portfolio API
https://x402.alchemy.com/data/v1/*
多链资产组合（与链无关）

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)
  1. 设置钱包 — 阻塞操作：继续前需询问用户。请勿读取现有钱包文件。详见钱包引导流程。
  2. 充值USDC — 在Base主网（或测试网Base Sepolia）中充值USDC
  3. 创建SIWE令牌 — 执行
    npx @alchemy/x402 sign-siwe --private-key ./wallet-key.txt
    （详见身份验证规则）
  4. 发送请求 — 使用
    Authorization: SIWE <token>
    请求头。如需SDK自动支付，详见发起请求规则。如需快速curl查询，详见curl工作流。
  5. 处理402响应 — 执行
    npx @alchemy/x402 pay
    或在代码中使用
    createPayment()
    （详见支付规则）

Rules

规则列表

RuleDescription
wallet-bootstrapSet up a wallet (existing or new) and fund it with USDC
overviewWhat the gateway is, end-to-end flow, required packages
authenticationSIWE token creation and SIWE message signing
making-requestsSending JSON-RPC requests with 
@x402/fetch
or 
@x402/axios
curl-workflowQuick RPC calls via curl with token caching (no SDK setup)
paymentManual x402 payment creation from a 402 response
referenceEndpoints, networks, USDC addresses, headers, status codes
规则描述
wallet-bootstrap设置钱包（现有或新建）并充值USDC
overview网关介绍、端到端流程、必需依赖包
authenticationSIWE令牌创建与SIWE消息签名
making-requests使用
@x402/fetch
或
@x402/axios
发送JSON-RPC请求
curl-workflow通过curl快速发起RPC调用并缓存令牌（无需SDK配置）
payment从402响应中手动创建x402支付
reference端点、支持网络、USDC地址、请求头、状态码参考

References

参考文档

Gateway routeAPI methodsReference 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.
网关路径API方法参考文件
/{chainNetwork}/v2
eth_*
标准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
等		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
等		references/data-portfolio-apis.md
如需了解Alchemy APIs的全部功能（如webhooks、Solana、钱包等），请查看
alchemy-api
技能。