Skill: gane5h/goldrush-x402 (version 3.0.5)

--- name: goldrush-x402 description: "GoldRush x402 — pay-per-request blockchain data access using the x402 protocol (HTTP 402 Payment Required). Use this skill whenever the user is building an AI agent that needs blockchain data without API keys, wants wallet-based micropayments for on-chain data, needs autonomous or no-account access to the GoldRush API, mentions the x402 protocol, or wants no-signup/no-onboarding blockchain data access. This is the right skill for autonomous agents, serverless applications, and prototyping without onboarding. Provides access to 60+ Foundational API endpoints through a transparent reverse proxy with stablecoin payments on Base. If the user needs a traditional API key with monthly billing, use goldrush-foundational-api instead. If the user needs real-time streaming data via WebSocket, use goldrush-streaming-api instead." --- # GoldRush x402 Pay-per-request access to GoldRush blockchain data using the x402 protocol. No API key, no signup, no billing — just a funded wallet. Provides access to Foundational API endpoints through a transparent reverse proxy. ## Quick Start ```typescript import { HTTPClient } from "@x402/core"; import { ExactEvmScheme } from "@x402/evm"; const client = new HTTPClient({ scheme: new ExactEvmScheme({ network: "eip155:84532", // Base Sepolia privateKey: process.env.WALLET_PRIVATE_KEY, }), }); // Get token balances — payment handled automatically const balances = await client.get( "https://x402.goldrush.dev/v1/eth-mainnet/address/demo.eth/balances_v2/" ); console.log(balances); ``` **Install:** `npm install @x402/core @x402/evm` ## How x402 Works ``` 1. REQUEST → Agent calls endpoint without payment 2. 402 → Server responds with payment instructions (amount, token, recipient) 3. PAY → Agent signs payment with stablecoins on Base, retries with proof 4. DATA → Server validates request *before* charging, returns data ``` The x402 client libraries handle steps 2-3 automatically. From your code, it's just a GET request. **Key safety feature:** The proxy validates your request before charging. Malformed addresses, unsupported chains, or bad parameters get a clear error — you pay nothing. **Payment:** USDC on Base Sepolia (testnet). Base mainnet support coming soon. ## Cross-Reference x402 serves the **same endpoints** as the Foundational API with the same parameters and response format. For detailed endpoint documentation (parameters, response schemas, use cases), see the **goldrush-foundational-api** skill. **Base URL mapping:** - Foundational API: `https://api.covalenthq.com/v1/...` - x402 proxy: `https://x402.goldrush.dev/v1/...` ## Pricing Summary | Model | Description | Example | |-------|-------------|---------| | **Fixed** | One price per call | Token balances, NFT holdings, block details | | **Tiered** | Price by data volume | Transactions, event logs | ### Tiers (for variable-length data) | Tier | Items | Use Case | |------|-------|----------| | Small | 1-50 | Quick lookups, recent activity | | Medium | 51-200 | Standard queries | | Large | 201-500 | Detailed analysis | | XL | 501+ | Full history | Select tier via query parameter: `?tier=small` ### Response Caching Cached responses cost less. Cache TTLs: - **Balances:** 30 seconds - **Pricing data:** 5 minutes ## AI Agent Workflow ### 1. Discover (free) ```bash curl https://x402.goldrush.dev/v1/x402/endpoints | jq curl https://x402.goldrush.dev/v1/x402/search?q=balance | jq ``` ### 2. Evaluate ```bash curl https://x402.goldrush.dev/v1/x402/endpoints/get-token-balances-for-address | jq ``` Returns credit rate, pricing model, supported chains — everything to decide what to call. ### 3. Pay & consume ```typescript const balances = await client.get( `https://x402.goldrush.dev/v1/eth-mainnet/address/${wallet}/balances_v2/` ); // Same JSON format as standard GoldRush API ``` ## Reference Files Read the relevant reference file when you need details beyond what this index provides. | File | When to read | |------|-------------| | [overview.md](references/overview.md) | Need x402 protocol details, pricing model breakdown, or quickstart code | | [ai-agents.md](references/ai-agents.md) | Building an autonomous agent — four-step workflow, x402 vs API key comparison, rate limits | | [endpoints.md](references/endpoints.md) | Need the discovery API details (free), or the catalog of available data endpoints |

path: references/ai-agents.md
content: # x402 for AI Agents

## Agent Workflow

1. **Discover** — Call free discovery API to find endpoints
2. **Evaluate** — Search and check pricing before committing
3. **Pay** — Sign payment and get data in single request-response cycle
4. **Consume** — Parse standard GoldRush JSON responses

## x402 vs API Key for Agents

| Concern | API Key | x402 |
|---------|---------|------|
| Provisioning | Requires signup, key management | 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

100 requests/minute per wallet. Check `X-RateLimit-Remaining` response header.

---

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
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
# 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
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,
  }),
});

const balances = await client.get(
  "https://x402.goldrush.dev/v1/eth-mainnet/address/0x742d.../balances_v2/"
);
```

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.

path: references/endpoints.md
content: # x402 Endpoints

## Discovery Endpoints (Free)

These endpoints require no payment and help agents explore available x402 endpoints.

### List All Available Endpoints

**Endpoint:** `GET /v1/x402/endpoints`
**Cost:** Free

```bash
curl https://x402.goldrush.dev/v1/x402/endpoints | jq
```

### Search Endpoints by Keyword

**Endpoint:** `GET /v1/x402/search?q={query}`
**Cost:** Free

```bash
curl https://x402.goldrush.dev/v1/x402/search?q=balance | jq
```

### Get Endpoint Details

**Endpoint:** `GET /v1/x402/endpoints/{endpoint-name}`
**Cost:** Free

```bash
curl https://x402.goldrush.dev/v1/x402/endpoints/get-token-balances-for-address | jq
```

---

## Data Endpoints (Paid via x402)

All 60+ Foundational API endpoints are available through the x402 proxy. Endpoint paths mirror the Foundational API.

**Base URL:** `https://x402.goldrush.dev/v1` (replaces `https://api.covalenthq.com/v1`)

### Key Data Endpoints

| Endpoint | Path | Pricing |
|----------|------|---------|
| Token Balances | `/v1/{chain}/address/{wallet}/balances_v2/` | Fixed |
| Native Balance | `/v1/{chain}/address/{wallet}/balances_native/` | Fixed |
| Transaction History | `/v1/{chain}/address/{wallet}/transactions_v3/?tier={tier}` | Tiered |
| Recent Transactions | `/v1/{chain}/address/{wallet}/transactions_v3/?tier=small` | Tiered |
| Single Transaction | `/v1/{chain}/transaction_v2/{txHash}/` | Fixed |
| NFT Holdings | `/v1/{chain}/address/{wallet}/balances_nft/` | Fixed |
| Token Prices | `/v1/pricing/historical_by_addresses_v2/{chain}/{currency}/{contract}/` | Fixed |
| Block Details | `/v1/{chain}/block_v2/{blockHeight}/` | Fixed |
| Token Approvals | `/v1/{chain}/approvals/{wallet}/` | Fixed |
| ERC20 Transfers | `/v1/{chain}/address/{wallet}/transfers_v2/` | Tiered |
| Cross-Chain Activity | `/v1/address/{wallet}/activity/` | Fixed |
| Multi-Chain Balances | `/v1/address/{wallet}/balances_multi/` | Fixed |

For the complete list, use: `GET /v1/x402/endpoints`

---

> **Note:** For detailed endpoint documentation (parameters, response schemas, use cases),
> see the **GoldRush Foundational API** skill reference files. The x402 proxy serves the
> exact same endpoints with the same parameters and response format.

path: references/overview.md
content: # GoldRush x402 Overview

## Quick Reference

| Item | Value |
|------|-------|
| **Base URL** | `https://x402.goldrush.dev/v1` |
| **Protocol** | x402 (HTTP 402 Payment Required) |
| **Authentication** | None — wallet-based micropayments replace API keys |
| **Payment Network** | Base Sepolia testnet (Base mainnet coming soon) |
| **Payment Method** | Stablecoins on Base |
| **Rate Limit** | 100 requests/minute per wallet |
| **Available Endpoints** | 60+ Foundational API endpoints |
| **Client Libraries** | `@x402/core`, `@x402/evm` |

## Pricing Model

- **Fixed-Price:** One price per call (e.g., token balances, NFT holdings)
- **Tiered Pricing:** For variable-length data — Small (1-50), Medium (51-200), Large (201-500), XL (501+)
- **Response Caching:** Cached responses cost less (TTLs: 30s for balances, 5m for pricing)

## Response Headers

```
X-Pricing-Model: fixed
X-Base-Price: 0.000001
X-Cache: MISS
X-RateLimit-Remaining: 97
```

---

GoldRush x402 lets you access the full GoldRush blockchain data API by paying per request using the [x402 protocol](https://x402.org). No account, no API key, no billing page - just pay for exactly what you use, directly from a wallet.

> **Note:** GoldRush x402 is live on **Base Sepolia testnet**. Mainnet support is coming soon.

## What is x402?

HTTP status code `402 Payment Required` has existed since 1997, reserved for "future use." The [x402 protocol](https://x402.org) makes it real - enabling native payments over HTTP using stablecoins.

When you call a GoldRush x402 endpoint without payment, the server responds with `402 Payment Required` along with payment instructions. Your client pays using stablecoins on Base, retries the request with proof of payment, and gets the data - all in a single request-response cycle.

## How it works

GoldRush x402 is a transparent reverse proxy in front of `api.covalenthq.com`. It exposes the same paths and returns the same responses - the only difference is how you authenticate. Instead of an API key, you attach a micropayment.

```
Your App -- x402 payment --> GoldRush x402 Proxy --> api.covalenthq.com
                                    |
                              validates request
                              verifies payment
                              caches response
                              returns data
```

The proxy validates your request **before** charging you. If the chain doesn't exist, the address is malformed, or the endpoint doesn't support that network - you get a clear error and pay nothing.

## What's supported

- **60+ endpoints** covering balances, NFTs, transactions, blocks, DEX data, pricing, security, and cross-chain operations
- **100+ blockchain networks** including Ethereum, Base, Arbitrum, Optimism, Polygon, Solana, Bitcoin, and more
- **Response caching** with intelligent TTLs (30s for balances, 5m for pricing data) - cached responses cost less
- **Per-wallet rate limiting** at 100 requests per minute
- **Request validation** before payment - you never pay for a request that would fail

## Pricing

Every endpoint has a credit rate. The price per call is:

```
Price = creditRate x $0.000001
```

### Fixed pricing

Most endpoints have a fixed cost per request. Token balances, NFT holdings, block details - one price, one call, one response.

### Dynamic pricing

Endpoints that return variable-length data (transaction histories, event logs) use tiered pricing. You select a tier upfront based on how much data you expect:

| Tier   | Items    | You pay for ... |
|--------|----------|----------------------|
| Small  | 1-50     | 50 items             |
| Medium | 51-200   | 200 items            |
| Large  | 201-500  | 500 items            |
| XL     | 501+     | 1000 items           |

If the response contains fewer items than your tier covers, you overpaid slightly but get the data immediately. If it contains more, you get a `402` telling you exactly which tier you need.

## x402 vs API key

**x402 (Pay-per-call):** - No signup or account needed
  - Pay per request with a wallet
  - Ideal for AI agents and autonomous workflows
  - Live on Base Sepolia testnet

**API Key (Subscription):** - Predictable monthly cost
  - API key for any project
  - Ideal for apps with steady usage
  - For Vibe Coders or Teams

Both paths give you the same data, the same endpoints, and the same response format. Pick the one that fits how you build.

---

## 1. Discover endpoints (free)

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

```bash
# 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.

```bash
export WALLET_PRIVATE_KEY="your-base-sepolia-private-key"
```

## 3. Install the x402 client

```bash npm
npm install @x402/core @x402/evm
```

```bash yarn
yarn add @x402/core @x402/evm
```

## 4. Make your first request

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

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
// 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   |

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

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)