Skip to main content

​
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
Every endpoint returns its credit rate, pricing model, supported chains, and x402 payment instructions.

​
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 @x402/fetch

​
4. Make your first request

import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client().register("eip155:84532",
  new ExactEvmScheme(privateKeyToAccount(process.env.WALLET_PRIVATE_KEY))
);

const paidFetch = wrapFetchWithPayment(fetch, client);

const response = await paidFetch(
  "https://x402.goldrush.dev/v1/eth-mainnet/address/aave.eth/balances_v2/"
);

const balances = await response.json();

console.log(JSON.stringify({
  headers: Object.fromEntries(response.headers.entries()),
  body: balances,
}, null, 2));
The x402 client handles the full payment flow: if a request gets a 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 response = await paidFetch(
  "https://x402.goldrush.dev/v1/eth-mainnet/address/aave.eth/transactions_v3/?tier=medium"
);
TierItems
Smallup to 50
Mediumup to 200
Largeup to 500
XLup to 1000
If your selected tier is too small for the response, you’ll get a 402 indicating the correct tier.

​
Response headers

Every paid response includes pricing metadata: 
X-Pricing-Model: fixed
X-Base-Price: 0.000001
X-Cache: MISS
X-RateLimit-Remaining: 97
For dynamic-priced endpoints, you also get: 
X-Item-Count: 42
X-Actual-Price: 0.000042
X-Paid-Price: 0.000050
X-Selected-Tier: small