在没有真实货币的情况下测试代理支付。
Swap your API key for a sk_test_ key - that alone puts you on Base Sepolia. Fund the agent's wallet from the public Base Sepolia USDC faucet, make a real test payment with payments.create (test funds, no real money), and tunnel your local webhook through ngrok. The response shapes match live, so a flow that passes in test passes in production. Exercise the failure paths, not just the happy one.
在您开始之前。
- 一个有效的实时集成（或至少是实时形态） - 请参见 add-payments-to-agent。
- 一个来自仪表板的
sk_test_API 密钥和匹配的测试签名密钥。 - ngrok（或任何 HTTPS 隧道）用于开发时的 Webhook 交付。
- 一个独立的开发环境 - 不同的环境变量、不同的数据库（或至少不同的表）、不同的 Webhook URL。
- 对Webhook模式指南的熟悉 - 本指南假设您有一个处理程序进行测试。
切换到测试密钥。
一个 sk_test_ 密钥在 Base Sepolia 上交易；一个 sk_live_ 密钥在 Base 主网交易。前缀选择网络 - 没有单独的网络环境变量，测试密钥无法移动主网资金。因此，您为开发环境更改的只是密钥（和测试 webhook 密钥）。
# .env.development
# A sk_test_ key picks Base Sepolia automatically - there is no network env var.
BLOCKCHAIN0X_API_KEY=sk_test_01J9...
BLOCKCHAIN0X_WEBHOOK_SECRET=... # the test webhook's secret, from the dashboard从水龙头为代理的钱包提供资金。
测试 USDC 没有货币价值，但在其他方面表现得像真实的 USDC：相同的响应结构，相同的余额跟踪。没有 SDK 调用可以铸造它 - 您可以从公共 Base Sepolia USDC 水龙头为代理的钱包地址提供资金。在仪表板或代理的公共页面上找到地址（或使用 SDK 读取代理），然后将其粘贴到水龙头中。
import { createClient } from "@blockchain0x/node";
const client = createClient({ apiKey: process.env.BLOCKCHAIN0X_API_KEY! }); // sk_test_
// Look up the agent; its wallet address is shown in the dashboard and on the
// agent's public page. Fund THAT address from the Base Sepolia USDC faucet -
// there is no SDK call that mints test funds.
const agent = await client.agents.get("agt_123");
console.log(agent.id);from blockchain0x import Client
client = Client() # reads BLOCKCHAIN0X_API_KEY (sk_test_)
# The agent's wallet address is in the dashboard / on its public page.
# Paste it into the public Base Sepolia USDC faucet to fund it.
agent = client.agents.get("agt_123")
print(agent["id"])进行真实的测试支付。
在钱包资金到位后，调用您 sk_test_ 密钥上的 payments.create。这是使用测试资金在 Base Sepolia 上进行的真实转账，它会像主网一样触发 payment.received webhook - 因此您执行的是实际的代码路径，而不是模拟。观察事件在您的隧道处理程序中落地。
// On a sk_test_ key this is a REAL transfer on Base Sepolia (test funds, no
// real money). It fires the payment.received webhook just like mainnet does.
const tx = await client.payments.create({
agentId: "agt_123",
to: "0xRecipientOnSepolia",
amountWei: "10000", // 0.01 USDC
});
console.log(tx); // watch payment.received arrive at your webhooktx = client.payments.create(body={
"agentId": "agt_123",
"to": "0xRecipientOnSepolia",
"amountWei": "10000", # 0.01 USDC
})
print(tx) # watch payment.received arrive at your webhook至少要演练三种场景：一笔到账的付款（正常路径，payment.received），一笔永远无法到账的付款（将 webhook 指向一个死 URL，并确认您的对账清理捕获了卡住的作业 - 大多数团队忽略的路径），以及 webhook 重试（第一次强制 500，第二次 200，然后验证您的幂等性跳过了重复工作）。
将Webhook隧道到您的本地处理程序。
测试支付将真实的 webhook 发送到您为测试 webhook 配置的任何 URL。对于本地开发，给它一个到您笔记本电脑的 HTTPS 隧道。ngrok 是最简单的选项；任何反向隧道工具都可以使用。
# Tunnel your local webhook endpoint to a public HTTPS URL.
$ ngrok http 3000
# Forwarding https://abc123.ngrok.app -> http://localhost:3000
# Paste the URL in the dashboard under Webhooks for your test
# environment - test and live keep separate webhook config.测试和实时使用不同的密钥和不同的 webhook 配置，因此您可以将生产指向您的真实端点，而您的本地隧道处理测试事件。
在配置错误的密钥上快速失败。
与测试/实时密钥相关的最常见的生产事件是静默的：部署时使用了测试密钥，没有支付通过，警报仅在下一个工作日后触发。在启动时阻止此操作：如果环境和密钥前缀不匹配，则拒绝启动。
// Fail fast if test/live get mixed up.
const apiKey = process.env.BLOCKCHAIN0X_API_KEY!;
const env = process.env.NODE_ENV;
if (env === "production" && apiKey.startsWith("sk_test_")) {
throw new Error("Test key in production environment - aborting boot.");
}
if (env !== "production" && apiKey.startsWith("sk_live_")) {
throw new Error("Live key in non-production environment - aborting boot.");
}import os, sys
api_key = os.environ["BLOCKCHAIN0X_API_KEY"]
env = os.environ.get("ENV", "development")
if env == "production" and api_key.startswith("sk_test_"):
sys.exit("Test key in production environment - aborting boot.")
if env != "production" and api_key.startswith("sk_live_"):
sys.exit("Live key in non-production environment - aborting boot.")五个后续会造成麻烦的测试错误。
忘记Base Sepolia是其自己的链
一个 sk_test_ 密钥在 Base Sepolia 上交易，而不是在 Base 主网。区块浏览器、钱包地址和燃气代币都是分开的。一个常见的混淆是将真实的 Base 地址复制到测试中，看到它失败，然后认为 API 出了问题。从 Base Sepolia USDC 水龙头为代理的钱包地址提供资金，并支付存在于该链上的地址。
未测试失败路径
大多数团队测试快乐路径 - 一个触发payment.received的支付 - 然后发布，发现他们的未支付路径已损坏。进行测试：将webhook指向一个死URL，确认你的对账操作捕获了被卡住的工作，强制从你的处理程序返回500并验证重试是幂等的，并检查payments.create的503（链适配器未连接）是否被处理。测试环境便宜；生产调试昂贵。
Webhook URL仍指向生产中的ngrok
切换密钥前缀容易记住；更新Webhook URL容易忘记。如果您在URL仍指向您笔记本电脑的ngrok隧道时上线，第一次生产支付将Webhook发送到虚空。将Webhook URL的更改视为部署检查清单的一部分，而不是一次性设置。
将测试网时间视为实时时间的代理
Base Sepolia的行为与Base主网并不完全相同 - 块时间和拥堵情况不同。不要使用测试网来负载测试主网吞吐量，也不要假设您的测试网延迟就是您在生产中看到的情况。当您需要真实数据时，请使用sk_live_密钥运行小额主网烟雾测试。
将测试固定件留在共享数据库中
如果您的开发和生产环境共享数据库（不要），测试事件将落在与实时事件相同的表中，并破坏您的幂等性去重（事件ID前缀不同，但行是真实的）。至少，按环境隔离webhook_events表。更好：完全分离数据库。这是一个看似过分的规则，直到它咬到一次。
一旦测试循环进入你的开发周期。
在健康的测试循环中，剩下的工作主要是加固：在负载下可靠的 webhook 处理，最终的安全检查表，以及从您可能正在运行的任何先前支付提供商的迁移。
完整参考请访问docs.blockchain0x.com。测试网详情：Base链术语表。产品表面：支付API。