Skip to main content

​
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

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.WALLET_PRIVATE_KEY,
  }),
});

// Get token balances — payment handled automatically
const balances = await client.get(
  "https://x402.goldrush.dev/v1/eth-mainnet/address/demo.eth/balances_v2/"
);
console.log(balances);
Install: npm install @x402/core @x402/evm

​
How x402 Works

1. REQUEST  → Agent calls endpoint without payment
2. 402      → Server responds with payment instructions (amount, token, recipient)
3. PAY      → Agent signs payment with stablecoins on Base, retries with proof
4. DATA     → Server validates request *before* charging, returns data
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: https://api.covalenthq.com/v1/...
  • x402 proxy: https://x402.goldrush.dev/v1/...

​
Pricing Summary

ModelDescriptionExample
FixedOne price per callToken balances, NFT holdings, block details
TieredPrice by data volumeTransactions, event logs

​
Tiers (for variable-length data)

TierItemsUse Case
Small1-50Quick lookups, recent activity
Medium51-200Standard queries
Large201-500Detailed analysis
XL501+Full history
Select tier via query parameter: ?tier=small

​
Response Caching

Cached responses cost less. Cache TTLs:
  • Balances: 30 seconds
  • Pricing data: 5 minutes

​
AI Agent Workflow

​
1. Discover (free)

curl https://x402.goldrush.dev/v1/x402/endpoints | jq
curl https://x402.goldrush.dev/v1/x402/search?q=balance | jq

​
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

const balances = await client.get(
  `https://x402.goldrush.dev/v1/eth-mainnet/address/${wallet}/balances_v2/`
);
// Same JSON format as standard GoldRush API

​
Reference Files

Read the relevant reference file when you need details beyond what this index provides.
FileWhen to read
overview.mdNeed x402 protocol details, pricing model breakdown, or quickstart code
ai-agents.mdBuilding an autonomous agent — four-step workflow, x402 vs API key comparison, rate limits
endpoints.mdNeed the discovery API details (free), or the catalog of available data endpoints