<!-- Generated by scripts/generate-agent-discovery.mjs from https://goldrush.dev/docs/api-reference/openapi.json. Do not edit by hand. -->

# GoldRush for AI Agents

> GoldRush by Covalent is a multichain blockchain data API. It supports **x402 pay-per-request**, so an autonomous agent can fetch onchain data with no signup, no API key and no credit card, paying per request from its own wallet.

This file is generated from the published [OpenAPI schema](https://goldrush.dev/docs/api-reference/openapi.json), so an endpoint that leaves the API contract also leaves this page. For human documentation see [goldrush.dev/docs](https://goldrush.dev/docs/).

## Quick start (with an API key)

Free-tier keys need no credit card: [goldrush.dev/platform/auth/register](https://goldrush.dev/platform/auth/register/).

```bash
export GOLDRUSH_API_KEY="cqt_xxx"
curl -H "Authorization: Bearer $GOLDRUSH_API_KEY" \
  https://api.covalenthq.com/v1/eth-mainnet/address/vitalik.eth/balances_v2/
```

## Quick start (x402, no signup)

Pay-per-request runs on a separate host. Requests to `api.covalenthq.com` without a key return `401`, not a payment challenge — use the x402 base URL instead:

```bash
curl https://x402.goldrush.dev/v1/eth-mainnet/address/vitalik.eth/balances_v2/
# HTTP 402 Payment Required, with the x402 challenge. Settle onchain and retry.
```

Take any path from the table below and replace its leading `/v1` with `https://x402.goldrush.dev/v1`. Reference clients: [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) (drop-in `fetch()`) and [`@x402/evm`](https://www.npmjs.com/package/@x402/evm). See the [x402 documentation](https://goldrush.dev/docs/goldrush-x402/overview) for networks, pricing and limits.

## REST operations

Generated from OpenAPI version `1.0.0`. Base URL `https://api.covalenthq.com`. Paths and chain names are case-sensitive.

| Operation                                   | Method | Path                                                                                       | Description                                                                                                                                                                    |
| ------------------------------------------- | -----: | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Get Address Activity                        |  `GET` | `/v1/address/{walletAddress}/activity/`                                                    | Locates the chains an address is active on, with a single API call.                                                                                                            |
| Get Allchains Balances                      |  `GET` | `/v1/allchains/address/{walletAddress}/balances/`                                          | Fetch paginated spot & historical native and token balances for a single address on up to 10 EVM chains with one API call.                                                     |
| Get Allchains Transactions                  |  `GET` | `/v1/allchains/transactions/`                                                              | Fetch paginated transactions for up to 10 EVM addresses and 10 EVM chains with one API call. Useful for building Activity Feeds.                                               |
| Get Bitcoin Balance For Address             |  `GET` | `/v1/btc-mainnet/address/{walletAddress}/balances_v2/`                                     | Fetch Bitcoin balance for a non-HD address. Response includes spot prices and other metadata.                                                                                  |
| Get Bitcoin Balances For Hd Address         |  `GET` | `/v1/btc-mainnet/address/{walletAddress}/hd_wallets/`                                      | Fetch balances for each active child address derived from a Bitcoin HD wallet.                                                                                                 |
| Get Historical Bitcoin Balance For Address  |  `GET` | `/v1/btc-mainnet/address/{walletAddress}/historical_balances/`                             | Fetches the historical Bitcoin balance held by an address at a given block height or date. Response includes daily prices and other metadata.                                  |
| Get All Chains                              |  `GET` | `/v1/chains/`                                                                              | Returns all supported chains. Useful for building internal dashboards.                                                                                                         |
| Get All Chain Statuses                      |  `GET` | `/v1/chains/status/`                                                                       | Returns the status of all supported chains. Useful for building internal status dashboards.                                                                                    |
| Get Transactions For Bitcoin Address        |  `GET` | `/v1/cq/covalent/app/bitcoin/transactions/`                                                | Fetches the full transaction history of a Bitcoin non-HD wallet address.                                                                                                       |
| Get Historical Token Prices                 |  `GET` | `/v1/pricing/historical_by_addresses_v2/{chainName}/{quoteCurrency}/{contractAddress}/`    | Get the historical prices of one (or many) large cap ERC20 tokens between specified date ranges. Also supports native tokens.                                                  |
| Get Pool Spot Prices                        |  `GET` | `/v1/pricing/spot_prices/{chainName}/pools/{contractAddress}/`                             | Get the spot token pair prices for a specified pool contract address. Supports pools on Uniswap V2, V3 and their forks.                                                        |
| Get Native Token Balance                    |  `GET` | `/v1/{chainName}/address/{walletAddress}/balances_native/`                                 | Lightweight endpoint to just get the native token balance for an EVM address.                                                                                                  |
| Get Nfts For Address                        |  `GET` | `/v1/{chainName}/address/{walletAddress}/balances_nft/`                                    | Returns the NFTs (including ERC721 and ERC1155) held by an address.                                                                                                            |
| Get Token Balances For Address              |  `GET` | `/v1/{chainName}/address/{walletAddress}/balances_v2/`                                     | Fetches the native and fungible (ERC20) tokens held by an address. Response includes spot prices and other metadata.                                                           |
| Check Ownership In Nft Collection           |  `GET` | `/v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/`                 | Verifies ownership of NFTs (including ERC-721 and ERC-1155) within a collection.                                                                                               |
| Check Ownership In Nft Collection Token     |  `GET` | `/v1/{chainName}/address/{walletAddress}/collection/{collectionContract}/token/{tokenId}/` | Verifies ownership of a specific token (ERC-721 or ERC-1155) within a collection.                                                                                              |
| Get Historical Token Balances For Address   |  `GET` | `/v1/{chainName}/address/{walletAddress}/historical_balances/`                             | Fetches the historical native and fungible (ERC20) tokens held by an address at a given block height or date. Response includes daily prices and other metadata.               |
| Get Historical Portfolio Value Over Time    |  `GET` | `/v1/{chainName}/address/{walletAddress}/portfolio_v2/`                                    | Returns a daily portfolio balance for an address, broken down by token. The timeframe is user-configurable and defaults to 30 days.                                            |
| Get Resolved Address For Registered Address |  `GET` | `/v1/{chainName}/address/{walletAddress}/resolve_address/`                                 | Resolves ENS, RNS and Unstoppable Domains addresses. Only supports the resolution of a registered domain to an address.                                                        |
| Get Transaction Summary For Address         |  `GET` | `/v1/{chainName}/address/{walletAddress}/transactions_summary/`                            | Fetches the earliest and latest transactions, and the transaction count, for a wallet. Also enriched with gas expenditure details and total ERC20 token transfers count.       |
| Get Recent Transactions For Address V3      |  `GET` | `/v1/{chainName}/address/{walletAddress}/transactions_v3/`                                 | Fetches the most recent transactions involving an address. Frequently seen in wallet applications.                                                                             |
| Get Paginated Transactions For Address V3   |  `GET` | `/v1/{chainName}/address/{walletAddress}/transactions_v3/page/{page}/`                     | Fetches the transactions involving an address, including the decoded log events, in a paginated fashion.                                                                       |
| Get Erc20 Token Transfers For Address       |  `GET` | `/v1/{chainName}/address/{walletAddress}/transfers_v2/`                                    | Returns the transfer-in and transfer-out of a token for an address, along with historical prices.                                                                              |
| Get Token Approvals For Address             |  `GET` | `/v1/{chainName}/approvals/{walletAddress}/`                                               | Returns a list of approvals across all token contracts, categorized by spenders, for a wallet’s assets.                                                                        |
| Get All Transactions In A Block             |  `GET` | `/v1/{chainName}/block/{blockHeight}/transactions_v3/`                                     | Fetches all transactions in a block, including their decoded log events. Useful for flagging interesting wallets or transactions.                                              |
| Get All Transactions In A Block By Page     |  `GET` | `/v1/{chainName}/block/{blockHeight}/transactions_v3/page/{page}/`                         | Fetches all transactions in a block, one page at a time, including their decoded log events. Useful for flagging interesting wallets or transactions.                          |
| Get All Transactions In A Block             |  `GET` | `/v1/{chainName}/block_hash/{blockHash}/transactions_v3/`                                  | Fetches all transactions in a block, including their decoded log events. Useful for flagging interesting wallets or transactions.                                              |
| Get A Block                                 |  `GET` | `/v1/{chainName}/block_v2/{blockHeight}/`                                                  | Fetches a single block, for example to render it in a block explorer.                                                                                                          |
| Get Block Heights                           |  `GET` | `/v1/{chainName}/block_v2/{startDate}/{endDate}/`                                          | Returns all the block heights within a particular date range. Useful for rendering a display where you sort blocks by day.                                                     |
| Get Earliest Transactions For Address V3    |  `GET` | `/v1/{chainName}/bulk/transactions/{walletAddress}/`                                       | Fetches the earliest transactions involving an address. Frequently seen in wallet applications.                                                                                |
| Get Time Bucket Transactions For Address V3 |  `GET` | `/v1/{chainName}/bulk/transactions/{walletAddress}/{timeBucket}/`                          | Fetches all transactions, including their decoded log events, in a 15-minute time bucket interval.                                                                             |
| Get Gas Prices                              |  `GET` | `/v1/{chainName}/event/{eventType}/gas_prices/`                                            | Get real-time gas estimates for different transaction speeds on a specific network, enabling users to optimize transaction costs and confirmation times.                       |
| Get Logs                                    |  `GET` | `/v1/{chainName}/events/`                                                                  | Returns all the event logs of the latest block, or for a range of blocks. Includes sender contract metadata as well as decoded logs.                                           |
| Get Log Events By Contract Address          |  `GET` | `/v1/{chainName}/events/address/{contractAddress}/`                                        | Returns all the event logs emitted from a particular contract address. Useful for building dashboards that examine on-chain interactions.                                      |
| Get Log Events By Topic Hash                |  `GET` | `/v1/{chainName}/events/topics/{topicHash}/`                                               | Returns all event logs of the same topic hash across all contracts within a particular chain. Useful for cross-sectional analysis of event logs that are emitted on-chain.     |
| Get Token Holders As Of Any Block Height V2 |  `GET` | `/v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/`                                  | Returns a paginated list of current or historical token holders for a specified ERC20 or ERC721 token.                                                                         |
| Get A Transaction                           |  `GET` | `/v1/{chainName}/transaction_v2/{txHash}/`                                                 | Fetches a single transaction, including its decoded event logs. For foundational chains, can also retrieve internal transactions, state changes and method ID where available. |

## Other endpoints

These surfaces are served on their own hosts and are not part of the OpenAPI schema above.

| Surface                       | Endpoint                                       | Description                                                                                                                                                                                                                                                                                       |
| ----------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| JSON-RPC                      | `POST https://rpc.goldrushdata.com/v1/{chain}` | Standard EVM JSON-RPC across 30+ chains (eth_call, eth_getLogs, eth_getBlockByNumber, and the rest). Substitute the GoldRush chain name for {chain}.                                                                                                                                              |
| Hyperliquid HyperCore info    | `POST https://hypercore.goldrushdata.com/info` | HyperCore clearinghouse state, user fills, vaults, L2/L4 order book, HIP-3 perp DEXs and HIP-4 outcome markets. Drop-in replacement for POST api.hyperliquid.xyz/info with no rate limits. Select the dataset with the JSON body field "type", e.g. {"type":"clearinghouseState","user":"0x..."}. |
| Hyperliquid HyperCore streams | `WSS wss://hypercore.goldrushdata.com/ws`      | HyperCore streaming over WebSocket. Takes the same subscription payloads as wss://api.hyperliquid.xyz/ws with no 1000-subscription-per-IP cap, plus the GoldRush-native l2BookDiff and l4Book order-level streams.                                                                                |

## Supported chains

Do not copy a chain list; it goes stale. Query `GET /v1/chains/` or read the current [supported chains page](https://goldrush.dev/chains/). Chain identifiers look like `eth-mainnet` and `solana-mainnet`.

## Pricing and limits

Rate limits and credit costs change independently of the API contract, so they are not reproduced here. Read the machine-readable [pricing page](https://goldrush.dev/pricing.md) or [goldrush.dev/pricing](https://goldrush.dev/pricing/).

## Machine-readable resources

- [OpenAPI schema](https://goldrush.dev/docs/api-reference/openapi.json) — canonical REST API contract
- [API catalog](https://goldrush.dev/.well-known/agent.json) — this page, as JSON, generated from that contract
- [OpenAI plugin manifest](https://goldrush.dev/.well-known/ai-plugin.json)
- [LLM documentation index](https://goldrush.dev/llms.txt) and [full corpus](https://goldrush.dev/llms-full.txt)
- [Machine-readable pricing](https://goldrush.dev/pricing.md)
- [Sitemap](https://goldrush.dev/sitemap.xml)

## Comparison to alternatives

- **vs Alchemy, QuickNode, Infura.** Those are JSON-RPC node providers. GoldRush is a decoded-data layer above RPC — wallet, NFT and pricing primitives that would otherwise take several raw RPC calls plus your own indexing. GoldRush also serves JSON-RPC directly, see the table above.
- **vs Moralis, Bitquery.** Native x402 support and a transparent credit model. Side-by-side detail at [/compare](https://goldrush.dev/compare/).
- **vs The Graph.** API-first, with no subgraph to write or deploy.

## Support and terms

- Support: [sales@goldrush.dev](mailto:sales@goldrush.dev) — billing, integration, enterprise
- Community: [Discord](https://discord.gg/8ZWgu2pWY4), open to everyone including the free tier
- [Terms of service](https://goldrush.dev/terms-of-use/) · [Privacy policy](https://goldrush.dev/privacy-policy/)