1. Discover endpoints (free)
The discovery API requires no payment. Use it to explore available endpoints and pricing.
# List all endpoints with pricing
curl https://x402.goldrush.dev/v1/x402/endpoints | jq
# Search for specific functionality
curl https://x402.goldrush.dev/v1/x402/search?q=balance | jq
# Get details for a specific endpoint
curl https://x402.goldrush.dev/v1/x402/endpoints/get-token-balances-for-address | jq
2. Set up a wallet
You need a wallet with testnet USDC on Base Sepolia. You’ll use the wallet’s private key to sign x402 payments.
Never commit your private key to source control. Use environment variables or a secrets manager.
export WALLET_PRIVATE_KEY="your-base-sepolia-private-key"
3. Install the x402 client
npm install @x402/core @x402/evm
4. Make your first request
import { HTTPClient } from "@x402/core";
import { ExactEvmScheme } from "@x402/evm";
const client = new HTTPClient({
scheme: new ExactEvmScheme({
network: "eip155:84532", // Base Sepolia (testnet)
privateKey: process.env.WALLET_PRIVATE_KEY,
}),
});
// Get token balances - payment is handled automatically
const balances = await client.get(
"https://x402.goldrush.dev/v1/eth-mainnet/address/demo.eth/balances_v2/"
);
console.log(balances);
402, it reads the payment instructions, signs a transaction, and retries. From your code’s perspective, it’s just a GET request.
5. Use tiers for variable-length data
Endpoints with dynamic pricing (transactions, event logs) require a tier parameter:
// Get transactions with tier selection
const txns = await client.get(
"https://x402.goldrush.dev/v1/eth-mainnet/address/demo.eth/transactions_v3/?tier=medium"
);
| Tier | Items |
|---|
| Small | up to 50 |
| Medium | up to 200 |
| Large | up to 500 |
| XL | up to 1000 |
402 indicating the correct tier.
Every paid response includes pricing metadata:
X-Pricing-Model: fixed
X-Base-Price: 0.000001
X-Cache: MISS
X-RateLimit-Remaining: 97
X-Item-Count: 42
X-Actual-Price: 0.000042
X-Paid-Price: 0.000050
X-Selected-Tier: small
