让开源，少一点语言距离。
npm包中文文档

@alch/alchemy-web3

中文文档
1.4.7发布于 2022/10/29MITTypeScriptESM + CJS近 30 天下载 1.4万

Web3客户端与Alchemy和浏览器提供者集成后扩展.

中文使用文档
中文原文
文档目录25 节
  1. 维护模式
  2. 导言
  3. 安装
  4. 有软件包管理器
  5. 浏览器中带有 CDN
  6. 使用量
  7. 基本用途
  8. 使用浏览器提供程序
  9. 与自定义提供者
  10. 自动检索
  11. 斯图迪耶 WebSockets
  12. 炼金术转移API
  13. web3.alchemy.getAssetTransfers({fromBlock, toBlock, fromAdd…
  14. 炼金术强化API
  15. web3.alchemy.getTokenAllowance({contract, owner, spender})
  16. web3.alchemy.getTokenBalances(address, contractAddresses)
  17. web3.alchemy.getTokenMetadata(address)
  18. web3.alchemy.getNfts({owner, pageKey, contractAddresses})
  19. web3.alchemy.getNftMetadata({contractAddress, tokenId, toke…
  20. web3.alchemy.getTransactionReceipts({blockNumber | blockHas…
  21. web3.eth.subscribe("alchemy_fullPendingTransactions")
  22. web3.eth.subscribe("alchemy_filteredFullPendingTransactions…
  23. EIP 1559
  24. web3.eth.getFeeHistory(blockRange, startingBlock, percentil…
  25. web3.eth.getMaxPriorityFeePerGas()

炼金术网络3

Web3客户端与Alchemy和浏览器提供者集成后扩展.

维护模式

截止2022年7月,这款雷波现在处于维护状态. 基于乙醚的新SDK. js现在可用 GitHub 图像 或者说 国家预防机制它具有与该图书馆平等的特点,以及更好的打字、更多的抽象和更多的文件.

展望未来,将尽最大努力更新该图书馆。 如果您看到错误或有特性请求, 请打开一个问题或拉动请求 Github 问题 节.

导言

Alchemy Web3 向网站作者提供一个空投替换器,用于 网络3.js Ethereum API客户端. 它能产生 匹配 web3.js 的客户端,但带来多种优势来使用 化学 API数字 :

  • 根据需要使用Alchemy或注射提供者. 大多数请求将发出 但涉及签名和发送交易的请求 通过浏览器提供者发送 元数据 或者说 信托 钱包 如果用户已安装,或通过 选项中指定的自定义提供者 .

  • 易取Alchemy更高水平API. 客户端暴露的方法 称为"炼金术"的独有特征.

  • 自动重试速率有限请求 . 如果Alchemy返回一个429个响应(速率有限),在短暂延迟后自动重试. 这个 行为可塑.

  • 强大的 WebSocket 订阅 它不会错过事件 如果 WebSocket 需要重新连接.

Alchemy Web3的设计要求最小配置,以便开始使用 放在你的应用程序里.

安装

有软件包管理器

与雅尔:

yarn add @alch/alchemy-web3

或与国家预防机制:

npm install @alch/alchemy-web3

浏览器中带有 CDN

或者在页面上添加以下一个脚本标签:

<!-- Minified -->
<script src="https://cdn.jsdelivr.net/npm/@alch/alchemy-web3@latest/dist/alchemyWeb3.min.js"></script>

<!-- Unminified -->
<script src="https://cdn.jsdelivr.net/npm/@alch/alchemy-web3@latest/dist/alchemyWeb3.js"></script>

当使用此选项时, 您可以使用全局变量创建 Alchemy- Web3 实例 AlchemyWeb3.createAlchemyWeb3。 。 。 .

使用量

基本用途

您需要一个Alchemy账户来访问Alchemy API. 如果你没有 有一个还没有, 在这儿报名。 。 。 .

通过导入函数创建客户端 createAlchemyWeb3 然后经过 它是你的Alchemy app的 URL 和可选的配置对象.

import { createAlchemyWeb3 } from "@alch/alchemy-web3";

// Using HTTPS
const web3 = createAlchemyWeb3(
  "https://eth-mainnet.alchemyapi.io/v2/<api-key>",
);

或者说

// Using WebSockets
const web3 = createAlchemyWeb3(
  "wss://eth-mainnet.ws.alchemyapi.io/ws/<api-key>",
);

您可以使用其中描述的任何方法 网络3.js API 密码 他们将请求 炼金术 :

// Many web3.js methods return promises.
web3.eth.getBlock("latest").then((block) => {
  /* … */
});

web3.eth
  .estimateGas({
    from: "0xge61df…",
    to: "0x087a5c…",
    data: "0xa9059c…",
    gasPrice: "0xa994f8…",
  })
  .then((gasAmount) => {
    /* … */
  });

使用浏览器提供程序

如果用户在其浏览器中有一个提供者,则在 window.ethereum,则 涉及用户账户或签名的任何方法都将自动使用. 这个提供者可能由 元数据, (中文(简体) ), 信托 钱包 如果 用户已经安装了它们。 例如,下面将使用来自 用户浏览器 :

web3.eth.getAccounts().then((accounts) => {
  web3.eth.sendTransaction({
    from: accounts[0],
    to: "0x6A823E…",
    value: "1000000000000000000",
  });
});

关于使用元掩码的说明

正如刚才所讨论的,Metamask将自动用于账户和签名 如果安装。 但是,要做到这一点 您必须先请求 用户访问Metamask账户的许可。这是 metamask 要求的安全限制: 细节可以找到 这里。 。 。 .

要启用 Metamask, 您必须拨打 ethereum.enable()。 。 。 . 这方面的一个例子如下:

if (window.ethereum) {
  ethereum
    .enable()
    .then((accounts) => {
      // Metamask is ready to go!
    })
    .catch((reason) => {
      // Handle error. Likely the user rejected the login.
    });
} else {
  // The user doesn't have Metamask installed.
}

请注意, 如果用户没有, 则会向用户显示一个 Metamask 对话框 已经看到并被接受,所以您可以选择等待启用 Metamask 直至 用户将要执行需要它的行动。 这也是为什么 Alchemy Web3 不会自动启用页面加载的Metamask.

与自定义提供者

您也可以选择将自己的提供者带去写作,而不是依赖 一个在浏览器环境中。 要做到这一点,使用 writeProvider 选项

const web3 = createAlchemyWeb3(ALCHEMY_URL, { writeProvider: provider });

你的供应商至少应该暴露其中之一 sendAsync() 或者说 send(),作为 指定于 爱德华王子岛 1193号。 。 。 .

您可以随时通过调用自定义提供者来交换 setWriteProvider() 方法 :

web3.setWriteProvider(provider);

您也可以通过传递一个值来完全禁用写入提供者 null。 。 。 .

自动检索

如果Alchemy Web3遇到速率有限的响应,它将自动重试 请求经过短暂延迟。 此行为可以通过传递 创建客户端时遵循选项。 要禁用重试, 设置 maxRetries 改为 0.

maxRetries

客户端在放弃前会尝试重发一个速率有限请求的次数. 默认: 3.

retryInterval

在连续的重试中等待的时间最少,以毫秒计。 默认值:1000.

retryJitter

在重试后添加随机时间, 帮助避免额外 因过多的并行连接而导致的速率差错,选择为若干 0到这个值之间的毫秒. 默认:250.

斯图迪耶 WebSockets

Alchemy Web3 带来了多个改进以确保正确的WebSocket行为 或中断连接。 和任何东西一样 网络连接, 您不应该假设一个 WebSocket 仍然打开 永远不中断,但正确处理掉的连接和 手动重接可能很难做到正确 人工智能网络3 自动 添加处理这些故障而不需要配置 .

如果您在初始化时使用 WebSocket URL, 那么当您创建时 使用 web3.eth.subscribe(),Alchemy Web3将带来 以下优于标准Web3订阅:

  • 与标准 Web3 不同的是, 您不会永久错过在 支持的 WebSocket 暂时下架. 相反,你会得到这些 当连接重新打开时立即发生事件。 注意如果连接是 下行120多条路(约20分钟),你可能仍会错过 一些事件不是最近120个街区的一部分.

  • 与标准 Web3 相比, 发送请求时故障率降低 关闭连接时使用 WebSocket 。 Alchemy Web3 将试图发送 重开连接后的请求。 请注意,这仍然是可能的, 发出的请求丢失的可能性较小,所以你还是 处理错误 .

炼金术转移API

制作的客户还提供方便 进入Alchemy的 传输 API。 。 。 .

web3.alchemy.getAssetTransfers({fromBlock, toBlock, fromAddress, toAddress, contractAddresses, excludeZeroValue, maxCount, category, pageKey})

根据指定的参数返回一系列资产转移.

参数:

以下字段为对象:

  • fromBlock: 包含从十六进制字符串块中的可选内容( 默认最近)
  • toBlock: 可选包含于十六进制字符串块( 默认最近)
  • order:可选字符串,按块号指定结果的顺序. 必须是["asc","desc" (默认"asc")之一
  • fromAddress: 从十六进制字符串地址( 默认通配符) 可选
  • toAddress: 可选的十六进制字符串地址( 默认通配符) 注: fromAddress 与 toAddress
  • contractAddresses: "token" 传输(默认通配符) 可选的六进制字符串合同地址 注: contractAddresses 合并排列
  • excludeZeroValue: 可选布尔以排除零值的转移( 默认为真)
  • maxCount: 限制有效载荷大小的可选编号(默认和最大为1000个)
  • category: 可选类别数组(默认为以下类别: ["外部","内部","托肯"])
  • pageKey: 可选的uuid pageKey 以获取下一个有效载荷

回返情况:

以下字段为对象:

  • pageKey: 下页结果的Uuid(结果最后一页未定义).
  • transfers: 一组对象,按块数排列,按上升顺序排列如下:
    • category:"外部","内部","托肯","erc20","erc721","erc1155" - 转让标签
    • blockNum: 发生转移的块(hex string).
    • from: 从传输地址(hex字符串).
    • to: 用于地址传输(hex string). null 如果创建合同.
    • value: 转换后的资产转移值作为数字(原始值除以十进制合同). null 如果erc721转出或收缩小数不可用.
    • erc721TokenId: Raw erc721 sorder id (hex string). 克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克. null 如果不是 erc721 转让
    • erc1155Metadata: 包含 erc1155 的天体列表 tokenId (hex 字符串)和 value (hex 字符串). null 如果不是 erc1155 转让
    • asset:"ETH"或指代符号. null (a) 如果合同中未作界定,且无法从其他来源获得.
    • hash: 交易散列(hex string).
    • rawContract: 原始值的对象 :
      • value: Raw 传输值(hex string). null 如果 erc721 或 erc1155 转让
      • address: 合同地址(hex字符串). null 如果“外部”或“内部”
      • decimal: 合同小数(hex string). null (a) 如果合同中未作界定,且无法从其他来源获得.

炼金术强化API

制作的客户还提供方便 进入Alchemy的 增强 API。 。 。 .

web3.alchemy.getTokenAllowance({contract, owner, spender})

返回给定合同清单的特定地址的符号余额.

参数:

以下字段为对象:

  • contract:指代合同的地址.
  • owner:指代物主的地址.
  • spender:指代花花人的地址.

回返情况:

津贴数额,作为代表10个基数的字符串.

web3.alchemy.getTokenBalances(address, contractAddresses)

返回给定合同清单的特定地址的符号余额.

参数:

  1. address: 将检查符号余额的地址.
  2. contractAddresses: 一组可选的合同地址。 不指定将返回所有符号余额 .

回返情况:

以下字段为对象:

  • address: 核对符号余额的地址.
  • tokenBalances: 一系列符号平衡对象。 每个对象包含:
    • contractAddress:合同地址.
    • tokenBalance:合同的余额,作为代表a的字符串 基数-10.
    • error: 一个错误字符串。 其中一个或 tokenBalance 将会是 null。 。 。 .

web3.alchemy.getTokenMetadata(address)

返回给定符号合同地址的元数据(名称、符号、小数、标志).

参数:

address:指代合同的地址.

回返情况:

以下字段为对象:

  • name:指证名. null (a) 如果合同中未作界定,且无法从其他来源获得.
  • symbol:指使符号. null (a) 如果合同中未作界定,且无法从其他来源获得.
  • decimals:指使为十进制. null (a) 如果合同中未作界定,且无法从其他来源获得.
  • logo:指使标志图像的URL. null 如果无法使用.

web3.alchemy.getNfts({owner, pageKey, contractAddresses})

参数:

以下字段为对象:

  • owner: 您想要获取 NFT 的地址 .
  • pageKey: (可选)获取下一页结果的密钥.
  • contractAddresses: (可选) 一系列合同地址来过滤所有者的结果 .
  • withMetadata: (备选)如果 false,返回的 NFT 将省略元数据。 默认为 true。 。 。 .

回返情况:

当包含元数据时,返回对象有以下字段:

  • ownedNfts:地址拥有的NFT对象阵列. 每个NFT对象的结构如下.
    • contract数字 :
      • address:NFT所属的合同或收藏的地址.
    • id数字 :
      • tokenId: Raw sorders id. (原始内容存档于2018-09-29).
      • tokenMetadata数字 :
        • tokenType:作为请求的一部分发送的令牌类型(可以是 ["erc721"-"erc1155").
    • title: NFT 的标题,如果没有标题,则为空字符串.
    • description: NFT 的描述,如果没有描述,则为空字符串.
    • tokenUri: (可选)
      • raw: Uri代表NFT最初元数据blob的位置. 这是供您分析的备份 当 metadata 字段不会自动显示.
      • gateway(原始内容存档于2017-09-26) (英语). : Public gate uri for the 生入入入出出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出.
    • media: (可选) 具有下列结构的一系列对象.
      • uri页:1 tokenUri 如上所述.
    • metadata: (可选)
      • image: (可选)一个可用于 标签.
      • attributes: (可选) NFT 元数据中的一系列属性. 每个属性是一个字典,其中 未知的键和值,因为它们直接取决于合同.
    • timeLastUpdated: 在元数据字段中返回信息的最后一个缓存更新的ISO时间戳.
  • pageKey: (可选)一个键来获取下一页的结果,如果适用的话.
  • totalCount:结果集中NFT的总数.

如果省略了元数据,则返回具有以下字段的对象:

  • ownedNfts:地址拥有的NFT对象阵列. 每个NFT对象的结构如下.
    • contract数字 :
      • address:NFT所属的合同或收藏的地址.
    • id数字 :
      • tokenId: Raw sorders id. (原始内容存档于2018-09-29).
      • tokenMetadata数字 :
        • tokenType:作为请求的一部分发送的令牌类型(可以是 ["erc721"-"erc1155").
  • pageKey: (可选)一个键来获取下一页的结果,如果适用的话.
  • totalCount:结果集中NFT的总数.

web3.alchemy.getNftMetadata({contractAddress, tokenId, tokenType})

参数:

以下字段为对象:

  • contract:指代合同的地址.
  • tokenId: Raw sorders id (hex string). (原始内容存档于2018-09-29).
  • tokenType: (可选)作为请求的一部分发送的令牌类型(可以是 ["erc721" →"erc1155"]之一).

回返情况:

以下字段为对象:

  • contract数字 :
    • address:合同中"token"转账地址的十六进制字符串.
  • id数字 :
    • tokenId: Raw sorders id. (原始内容存档于2018-09-29).
    • tokenMetadata数字 :
      • tokenType:作为请求的一部分发送的令牌类型(可以是 ["erc721"-"erc1155").
  • title名称:NFT.
  • description:从合同元数据取自NFT的简要说明.
  • tokenUri: (可选)
    • raw: Uri代表NFT最初元数据blob的位置. 这是供您分析 metadata 字段不会自动显示.
    • gateway(原始内容存档于2017-09-26) (英语). : Public gate uri for the 生入入入出出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出.
  • media: (可选) 具有下列结构的一系列对象.
    • uri页:1 tokenUri 如上所述.
  • metadata: (可选)
    • image: (可选)一个可用于 标签.
    • attributes: (可选) NFT 元数据中的一系列属性. 每个属性都是有未知密钥和值的词典,因为它们直接依赖于合同.
  • timeLastUpdated: 在元数据字段中返回信息的最后一个缓存更新的ISO时间戳.

web3.alchemy.getTransactionReceipts({blockNumber | blockHash})

获取块号或块散列的所有交易收据.

参数:

  • 块数 - (hex) 获取交易收据的块号
  • 块Hash - 获取交易收据的块散列

请注意 blockNumber 或者说 blockHash 可以设定.

回返情况:

  • {receipts: TransactionReceipt[]} | null - 一系列交易收据,或 null 如果块编号或散列 无法找到.

返回的对象是本块中每项交易的交易收据列表. 见 获取交易检索( G) 个人交易收据的有效载荷.

web3.eth.subscribe("alchemy_fullPendingTransactions")

订阅待决交易, 类似于标准的 Web3 调用 web3.eth.subscribe("pendingTransactions")但不同之处在于它释放出 全部交易信息,而不只是交易散列.

请注意,赋予这一职能的论据是允许的 "alchemy_fullPendingTransactions" 或者说 "alchemy_newFullPendingTransactions", (中文(简体) ), 具有同样效果。 后者是原始中使用的字符串 eth_subscribe JSON-RPC呼叫,而前者则符合现有的Web3.js 订阅 API(例如, web3.eth.subscribe("pendingTransactions") 对应类型的原始 JSON- RPC 调用 newPendingTransactions) (中文(简体) ). 虽然 可惜这很混乱,支持两条线的平衡 一致性和方便性.

web3.eth.subscribe("alchemy_filteredFullPendingTransactions", options)

就像一个 alchemy_fullPendingTransactions 订阅,但也允许通过 a 一个 options 包含一个参数 address 要过滤返回的字段 交易到来自或到指定地址的交易。 选项参数是 说明 文件 这里。 。 。 .

与前一点类似,请注意,这一论点转而适用于这一职能 可以是其中之一 "alchemy_filteredFullPendingTransactions" 或者说 "alchemy_filteredNewPendingTransactions"。 。 。 .


版权:"2019"Alchemy Insights Inc.

EIP 1559

web3.eth.getFeeHistory(blockRange, startingBlock, percentiles[])

按 光谱。 。 。 .

参数

  • blockRange:用来收取历史费用的区块数目。 可以是整数或六分弦.
  • startingBlock: 开始搜索的块. 结果从这里往后看。 可以是十六进制字符串,也可以是预先定义的块字符串,例如"latest".
  • percentiles: (可选) 定义每个区块的奖励值百分位数的一系列数字.

回返

以下字段为对象:

  • oldestBlock: 收费历史被退回范围内最古老的块.
  • baseFeePerGas: 查看范围内每个区块的一系列基本收费。 这些值与块中返回的值相同,用于 eth_getBlockByNumber 方法.
  • gasUsedRatio:每个区块所使用的气体与气体限制的比例的数组.
  • reward: 只有在提供了百分位参数的情况下才返回。 每个区块都将有一个与所提供的百分位相对应的阵列. 每个嵌入式阵列的每个元素都会为给定百分位数的矿工提供尖端. 因此,如果你提供[50,90]作为百分位数,那么每个街区将获得50%的奖励和90%的奖励.

示例

方法调用

web3.eth.getFeeHistory(4, "latest", [25, 50, 75]).then(console.log);

日志响应

{
  oldestBlock: 12930639,
  reward: [
    [ '0x649534e00', '0x66720b300', '0x826299e00' ],
    [ '0x649534e00', '0x684ee1800', '0x7ea8ed400' ],
    [ '0x5ea8dd480', '0x60db88400', '0x684ee1800' ],
    [ '0x59682f000', '0x5d21dba00', '0x5d21dba00' ]
  ],
  baseFeePerGas: [ '0x0', '0x0', '0x0', '0x0', '0x0' ],
  gasUsedRatio: [ 0.9992898398856537, 0.9999566454373825, 0.9999516, 0.9999378 ]
}

web3.eth.getMaxPriorityFeePerGas()

返回快速估计数 maxPriorityFeePerGas eIP 1559交易。 而不是使用 feeHistory 你可以用这种方法来快速估算 注意:这是只用一种方法, 但Alchemy在幕后处理.

参数

没有!

回返

一个螺旋,这就是 maxPriorityFeePerGas 建议。 您可以直接插入到您的交易域中 .

示例

方法调用

web3.eth.getMaxPriorityFeePerGas().then(console.log);

日志响应

0x560de0700

版本与发布记录

@alch/alchemy-web3 共发布 61 个版本，首次发布于 2019/04/24；过去 12 个月发布了 0 个版本。

版本发布日期距今
1.4.7latest2022/10/294 年前
1.4.62022/07/154 年前
1.4.42022/06/214 年前
1.4.3-betabeta2022/06/214 年前
1.4.32022/06/214 年前
1.4.22022/04/284 年前

关于 @alch/alchemy-web3 的常见问题

@alch/alchemy-web3 是什么？

Web3客户端与Alchemy和浏览器提供者集成后扩展.

如何安装 @alch/alchemy-web3？

在项目目录运行 npm install @alch/alchemy-web3，或使用 pnpm add / yarn add / bun add。

@alch/alchemy-web3 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@alch/alchemy-web3 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require() 都可以使用，打包工具会自动选择合适的版本。

@alch/alchemy-web3 可以商用吗？

@alch/alchemy-web3 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@alch/alchemy-web3 的下载量有多少？

根据 npm 官方下载统计，@alch/alchemy-web3 在 2026/10/06 – 2026/11/04 这 30 天内被下载 13,776 次，日均约 459 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@alch/alchemy-web3 还在维护吗？

最新版本 1.4.7 发布于 2022/10/29（4 年前）；至今共发布 61 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/04/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。