> ## Documentation Index
> Fetch the complete documentation index at: https://goldrush.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Quickstart

> Start making pay-per-call requests to the GoldRush API using the x402 protocol. From discovery to your first paid request in minutes.

## 1. Discover endpoints (free)

The discovery API requires no payment. Use it to explore available endpoints and pricing.

```bash theme={null}
# 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.

<Warning>
  Never commit your private key to source control. Use environment variables or a secrets manager.
</Warning>

```bash theme={null}
export WALLET_PRIVATE_KEY="your-base-sepolia-private-key"
```

## 3. Install the x402 client

<CodeGroup>
  ```bash npm theme={null}
  npm install @x402/core @x402/evm @x402/fetch
  ```

  ```bash yarn theme={null}
  yarn add @x402/core @x402/evm @x402/fetch
  ```
</CodeGroup>

## 4. Make your first request

```typescript theme={null}
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:

```typescript theme={null}
// 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
```