> ## 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 for AI Agents

> Build AI agents that autonomously discover, evaluate, and pay for blockchain data using the x402 protocol - no API keys or human intervention required.

The x402 protocol was designed with machine-to-machine payments in mind. An AI agent with a funded wallet can autonomously access the full GoldRush API - no signup flow, no credentials to rotate, no billing portal, no human in the loop.

## Agent workflow

An AI agent interacting with GoldRush x402 follows four steps:

### 1. Discover

Call the free discovery API to find available endpoints:

```bash theme={null}
curl https://x402.goldrush.dev/v1/x402/endpoints | jq
```

The response includes endpoint names, descriptions, credit rates, pricing models, and supported chains - everything an agent needs to decide what to call.

### 2. Evaluate

Search for relevant endpoints and check pricing before committing:

```bash theme={null}
# Find balance-related endpoints
curl https://x402.goldrush.dev/v1/x402/search?q=balance | jq

# Check pricing for a specific endpoint
curl https://x402.goldrush.dev/v1/x402/endpoints/get-token-balances-for-address | jq
```

The agent can compare credit rates against its budget and select the right tier for variable-length responses.

### 3. Pay

Using the x402 client, the agent signs a payment and gets data in a single request-response cycle:

```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));
```

No OAuth, no API key provisioning - the agent just needs a funded wallet.

### 4. Consume

Responses use the same JSON format as the standard GoldRush API. Any existing parsing logic works unchanged.

## Why x402 for agents

| Concern           | API Key                                   | x402                            |
| ----------------- | ----------------------------------------- | ------------------------------- |
| Provisioning      | Requires signup, key management, rotation | Wallet is the credential        |
| Budget control    | Monthly plan, overage charges             | Pay exactly per request         |
| Human involvement | Account creation, billing setup           | None - fully autonomous         |
| Discovery         | Read docs or hardcode endpoints           | Programmatic endpoint discovery |
| Multi-agent       | Share key or provision per agent          | Each agent gets its own wallet  |

## Rate limits

Each wallet is rate-limited to **100 requests per minute**. The `X-RateLimit-Remaining` response header shows how many requests remain in the current window.