x402 Quickstart - GoldRush API Documentation

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

yarn add @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"
);

Tier	Items
Small	up to 50
Medium	up to 200
Large	up to 500
XL	up 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

​1. Discover endpoints (free)

​2. Set up a wallet

​3. Install the x402 client

​4. Make your first request

​5. Use tiers for variable-length data

​Response headers

1. Discover endpoints (free)

2. Set up a wallet

3. Install the x402 client

4. Make your first request

5. Use tiers for variable-length data

Response headers