GoldRush x402
Pay-per-request access to GoldRush blockchain data using the x402 protocol. No API key, no signup, no billing — just a funded wallet. Provides access to Foundational API endpoints through a transparent reverse proxy.
Quick Start
CODEBLOCK0
Install: INLINECODE0
How x402 Works
CODEBLOCK1
The x402 client libraries handle steps 2-3 automatically. From your code, it's just a GET request.
Key safety feature: The proxy validates your request before charging. Malformed addresses, unsupported chains, or bad parameters get a clear error — you pay nothing.
Payment: USDC on Base Sepolia (testnet). Base mainnet support coming soon.
Cross-Reference
x402 serves the same endpoints as the Foundational API with the same parameters and response format. For detailed endpoint documentation (parameters, response schemas, use cases), see the goldrush-foundational-api skill.
Base URL mapping:
- - Foundational API: INLINECODE1
- x402 proxy: INLINECODE2
Pricing Summary
| Model | Description | Example |
|---|
| Fixed | One price per call | Token balances, NFT holdings, block details |
| Tiered |
Price by data volume | Transactions, event logs |
Tiers (for variable-length data)
| Tier | Items | Use Case |
|---|
| Small | 1-50 | Quick lookups, recent activity |
| Medium |
51-200 | Standard queries |
| Large | 201-500 | Detailed analysis |
| XL | 501+ | Full history |
Select tier via query parameter: INLINECODE3
Response Caching
Cached responses cost less. Cache TTLs:
- - Balances: 30 seconds
- Pricing data: 5 minutes
AI Agent Workflow
1. Discover (free)
CODEBLOCK2
2. Evaluate
curl https://x402.goldrush.dev/v1/x402/endpoints/get-token-balances-for-address | jq
Returns credit rate, pricing model, supported chains — everything to decide what to call.
3. Pay & consume
CODEBLOCK4
Reference Files
Read the relevant reference file when you need details beyond what this index provides.
Building an autonomous agent — four-step workflow, x402 vs API key comparison, rate limits |
|
endpoints.md | Need the discovery API details (free), or the catalog of available data endpoints |
GoldRush x402
使用x402协议按请求付费访问GoldRush区块链数据。无需API密钥、无需注册、无需账单——只需一个已注资的钱包。通过透明反向代理提供对基础API端点的访问。
快速开始
typescript
import { HTTPClient } from @x402/core;
import { ExactEvmScheme } from @x402/evm;
const client = new HTTPClient({
scheme: new ExactEvmScheme({
network: eip155:84532, // Base Sepolia
privateKey: process.env.WALLETPRIVATEKEY,
}),
});
// 获取代币余额——支付自动处理
const balances = await client.get(
https://x402.goldrush.dev/v1/eth-mainnet/address/demo.eth/balances_v2/
);
console.log(balances);
安装： npm install @x402/core @x402/evm
x402工作原理
- 1. 请求 → 代理调用端点，无需支付
- 402 → 服务器响应支付指令（金额、代币、接收方）
- 支付 → 代理使用Base上的稳定币签署支付，附带证明重试
- 数据 → 服务器在扣费前验证请求，返回数据
x402客户端库自动处理步骤2-3。从你的代码角度看，这只是一个GET请求。
关键安全特性： 代理在扣费前验证你的请求。格式错误的地址、不支持的链或错误参数会返回明确的错误——你无需支付任何费用。
支付： Base Sepolia（测试网）上的USDC。Base主网支持即将推出。
交叉参考
x402提供与基础API相同的端点，具有相同的参数和响应格式。有关详细的端点文档（参数、响应模式、用例），请参阅goldrush-foundational-api技能。
基础URL映射：
- - 基础API：https://api.covalenthq.com/v1/...
- x402代理：https://x402.goldrush.dev/v1/...
定价摘要
| 模式 | 描述 | 示例 |
|---|
| 固定 | 每次调用固定价格 | 代币余额、NFT持仓、区块详情 |
| 分层 |
按数据量定价 | 交易、事件日志 |
分层（针对可变长度数据）
51-200 | 标准查询 |
| 大 | 201-500 | 详细分析 |
| 超大 | 501+ | 完整历史 |
通过查询参数选择层级：?tier=small
响应缓存
缓存响应成本更低。缓存TTL：
AI代理工作流程
1. 发现（免费）
bash
curl https://x402.goldrush.dev/v1/x402/endpoints | jq
curl https://x402.goldrush.dev/v1/x402/search?q=balance | jq
2. 评估
bash
curl https://x402.goldrush.dev/v1/x402/endpoints/get-token-balances-for-address | jq
返回信用费率、定价模型、支持的链——决定调用所需的一切信息。
3. 支付与消费
typescript
const balances = await client.get(
https://x402.goldrush.dev/v1/eth-mainnet/address/${wallet}/balances_v2/
);
// 与标准GoldRush API相同的JSON格式
参考文件
当需要超出本索引提供的详细信息时，请阅读相关参考文件。
构建自主代理——四步工作流程、x402与API密钥对比、速率限制 |
|
endpoints.md | 需要发现API详情（免费）或可用数据端点目录 |
