openapi: 3.1.0
info:
title: GoldRush Foundational API
description: >
Structured historical blockchain data across 100+ chains via REST. Resource
families include Balances (native, ERC20, ERC721, ERC1155, historical
portfolios, token holders), Transactions (v3 paginated, time-bucketed,
by-block), NFTs, Base service (blocks, logs, gas prices, address
resolution), Cross-Chain Activity, Pricing, and Security (token approvals).
version: v1
contact:
name: GoldRush Support
url: https://goldrush.dev/support/
license:
name: Covalent Terms of Service
url: https://www.covalenthq.com/terms-of-service/
servers:
- url: https://api.covalenthq.com
description: GoldRush production server
security:
- BearerAuth: []
tags:
- name: Balances
description: Native, ERC20, ERC721, ERC1155, and historical token balances.
- name: Transactions
description: Transaction lookups by address, block, and time bucket.
- name: NFT
description: NFTs held by an address and collection ownership checks.
- name: Base
description: Blocks, gas prices, log events, address resolution, chain status.
- name: Cross-Chain
description: Discover an address's activity across all supported chains.
- name: Pricing
description: Historical token prices and pool spot prices.
- name: Security
description: Token approvals across ERC20 and NFT contracts.
- name: Bitcoin
description: Bitcoin balance and transaction lookups (HD and non-HD).
paths:
/v1/{chainName}/address/{walletAddress}/balances_v2/:
get:
summary: Get Token Balances For Address
description: Returns native + ERC20 token balances for an address on the given chain.
operationId: getTokenBalancesForAddress
tags: [Balances]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
- name: quote-currency
in: query
schema: { type: string, default: USD }
- name: nft
in: query
schema: { type: boolean }
- name: no-nft-fetch
in: query
schema: { type: boolean }
responses:
'200':
description: Token balance response
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceResponse'
'401': { $ref: '#/components/responses/Unauthorized' }
'429': { $ref: '#/components/responses/RateLimited' }
/v1/{chainName}/address/{walletAddress}/balances_native/:
get:
summary: Get Native Token Balance For Address
description: Returns the native token balance (e.g., ETH) for an address.
operationId: getNativeTokenBalanceForAddress
tags: [Balances]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/BalanceResponse' } } } }
/v1/{chainName}/address/{walletAddress}/historical_balances/:
get:
summary: Get Historical Token Balances For Address
description: Historical token balances at a specific block height or timestamp.
operationId: getHistoricalTokenBalancesForAddress
tags: [Balances]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
- name: block-height
in: query
schema: { type: integer }
responses:
'200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/BalanceResponse' } } } }
/v1/{chainName}/address/{walletAddress}/portfolio_v2/:
get:
summary: Get Historical Portfolio Value Over Time
description: Time-series portfolio value broken down by token holding.
operationId: getHistoricalPortfolioValueOverTime
tags: [Balances]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
- name: days
in: query
schema: { type: integer }
responses:
'200': { description: OK }
/v1/{chainName}/address/{walletAddress}/transfers_v2/:
get:
summary: Get ERC20 Token Transfers For Address
description: ERC20 transfer history for an address, filterable by contract.
operationId: getErc20TokenTransfersForAddress
tags: [Balances, Transactions]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
- name: contract-address
in: query
required: true
schema: { type: string }
responses:
'200': { description: OK }
/v1/{chainName}/tokens/{tokenAddress}/token_holders_v2/:
get:
summary: Get Token Holders As Of Any Block Height (v2)
description: List token holders of an ERC20/721/1155 contract at a block height.
operationId: getTokenHoldersAsOfBlockHeight
tags: [Balances]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: tokenAddress
in: path
required: true
schema: { type: string }
- name: block-height
in: query
schema: { type: integer }
responses:
'200': { description: OK }
/v1/{chainName}/address/{walletAddress}/transactions_v3/:
get:
summary: Get Recent Transactions For Address (v3)
description: Recent transactions for an address.
operationId: getRecentTransactionsForAddressV3
tags: [Transactions]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/TransactionResponse' } } } }
/v1/{chainName}/address/{walletAddress}/transactions_v3/page/{page}/:
get:
summary: Get Paginated Transactions For Address (v3)
operationId: getPaginatedTransactionsForAddressV3
tags: [Transactions]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
- name: page
in: path
required: true
schema: { type: integer }
responses:
'200': { description: OK }
/v1/{chainName}/address/{walletAddress}/transactions_v3/earliest/:
get:
summary: Get Earliest Transactions For Address (v3)
operationId: getEarliestTransactionsForAddressV3
tags: [Transactions]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/{chainName}/bulk/transactions/{walletAddress}/{timeBucket}/:
get:
summary: Get Bulk Time Bucket Transactions For Address (v3)
description: Returns a bulk time-bucketed window of transactions.
operationId: getBulkTimeBucketTransactionsForAddressV3
tags: [Transactions]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
- name: timeBucket
in: path
required: true
schema: { type: integer }
responses:
'200': { description: OK }
/v1/{chainName}/address/{walletAddress}/transactions_summary/:
get:
summary: Get Transaction Summary For Address
operationId: getTransactionSummaryForAddress
tags: [Transactions]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/{chainName}/transaction_v2/{txHash}/:
get:
summary: Get A Transaction
operationId: getTransaction
tags: [Transactions]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: txHash
in: path
required: true
schema: { type: string }
responses:
'200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/TransactionResponse' } } } }
/v1/{chainName}/block/{blockHeight}/transactions_v3/:
get:
summary: Get All Transactions In A Block (v3)
operationId: getAllTransactionsInBlockV3
tags: [Transactions]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: blockHeight
in: path
required: true
schema: { type: integer }
responses:
'200': { description: OK }
/v1/{chainName}/block/{blockHeight}/transactions_v3/page/{page}/:
get:
summary: Get All Transactions In A Block By Page (v3)
operationId: getAllTransactionsInBlockByPageV3
tags: [Transactions]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: blockHeight
in: path
required: true
schema: { type: integer }
- name: page
in: path
required: true
schema: { type: integer }
responses:
'200': { description: OK }
/v1/{chainName}/address/{walletAddress}/balances_nft/:
get:
summary: Get NFTs For Address
operationId: getNftsForAddress
tags: [NFT]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/{chainName}/tokens/{collectionContract}/nft_token_ids/{tokenId}/check_ownership/{walletAddress}/:
get:
summary: Check Ownership In NFT Collection For Specific Token
operationId: checkOwnershipInNftCollectionForToken
tags: [NFT]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: collectionContract
in: path
required: true
schema: { type: string }
- name: tokenId
in: path
required: true
schema: { type: string }
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/{chainName}/tokens/{collectionContract}/check_ownership/{walletAddress}/:
get:
summary: Check Ownership In NFT Collection
operationId: checkOwnershipInNftCollection
tags: [NFT]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: collectionContract
in: path
required: true
schema: { type: string }
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/{chainName}/block_v2/{blockHeight}/:
get:
summary: Get A Block
operationId: getBlock
tags: [Base]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: blockHeight
in: path
required: true
schema: { type: string }
responses:
'200': { description: OK }
/v1/{chainName}/block_v2/{startDate}/{endDate}/:
get:
summary: Get Block Heights
operationId: getBlockHeights
tags: [Base]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: startDate
in: path
required: true
schema: { type: string, format: date }
- name: endDate
in: path
required: true
schema: { type: string, format: date }
responses:
'200': { description: OK }
/v1/chains/:
get:
summary: Get All Chains
operationId: getAllChains
tags: [Base]
responses:
'200': { description: OK }
/v1/chains/status/:
get:
summary: Get All Chain Statuses
operationId: getAllChainStatuses
tags: [Base]
responses:
'200': { description: OK }
/v1/{chainName}/event/topics/{topicHash}/:
get:
summary: Get Log Events By Topic Hash(es)
operationId: getLogEventsByTopicHash
tags: [Base]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: topicHash
in: path
required: true
schema: { type: string }
responses:
'200': { description: OK }
/v1/{chainName}/events/address/{contractAddress}/:
get:
summary: Get Log Events By Contract Address
operationId: getLogEventsByContractAddress
tags: [Base]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: contractAddress
in: path
required: true
schema: { type: string }
responses:
'200': { description: OK }
/v1/{chainName}/events/:
get:
summary: Get Logs
operationId: getLogs
tags: [Base]
parameters:
- $ref: '#/components/parameters/ChainName'
responses:
'200': { description: OK }
/v1/{chainName}/gas_prices/{eventType}/:
get:
summary: Get Gas Prices
operationId: getGasPrices
tags: [Base]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: eventType
in: path
required: true
schema: { type: string, enum: [erc20transfers, nativetokens, uniswapv3] }
responses:
'200': { description: OK }
/v1/{chainName}/address/{addressName}/resolve_address/:
get:
summary: Get Resolved Address For Registered Address
operationId: getResolvedAddress
tags: [Base]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: addressName
in: path
required: true
schema: { type: string }
responses:
'200': { description: OK }
/v1/address/{walletAddress}/activity/:
get:
summary: Get Activity Across All Chains For Address
operationId: getActivityAcrossAllChainsForAddress
tags: [Cross-Chain]
parameters:
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/allchains/address/{walletAddress}/balances/:
get:
summary: Get Multichain Balances
operationId: getMultichainBalances
tags: [Cross-Chain]
parameters:
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/allchains/transactions/:
get:
summary: Get Multichain Multiaddress Transactions
operationId: getMultichainMultiaddressTransactions
tags: [Cross-Chain]
responses:
'200': { description: OK }
/v1/pricing/historical_by_addresses_v2/{chainName}/{quoteCurrency}/{contractAddresses}/:
get:
summary: Get Historical Token Prices
operationId: getHistoricalTokenPrices
tags: [Pricing]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: quoteCurrency
in: path
required: true
schema: { type: string }
- name: contractAddresses
in: path
required: true
schema: { type: string }
- name: from
in: query
schema: { type: string, format: date }
- name: to
in: query
schema: { type: string, format: date }
responses:
'200': { description: OK }
/v1/{chainName}/xy=k/{dexName}/pool/{poolAddress}/spot_prices/:
get:
summary: Get Pool Spot Prices
operationId: getPoolSpotPrices
tags: [Pricing]
parameters:
- $ref: '#/components/parameters/ChainName'
- name: dexName
in: path
required: true
schema: { type: string }
- name: poolAddress
in: path
required: true
schema: { type: string }
responses:
'200': { description: OK }
/v1/{chainName}/approvals/{walletAddress}/:
get:
summary: Get Token Approvals For Address
operationId: getTokenApprovalsForAddress
tags: [Security]
parameters:
- $ref: '#/components/parameters/ChainName'
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/bitcoin-mainnet/address/{walletAddress}/balances_v2/:
get:
summary: Get Bitcoin Balance For Non-HD Address
operationId: getBitcoinBalanceForNonHdAddress
tags: [Bitcoin]
parameters:
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/bitcoin-hd-mainnet/address/{walletAddress}/balances_v2/:
get:
summary: Get Bitcoin Balances For HD Address
operationId: getBitcoinBalancesForHdAddress
tags: [Bitcoin]
parameters:
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/bitcoin-mainnet/address/{walletAddress}/historical_balances/:
get:
summary: Get Historical Bitcoin Balance For Non-HD Address
operationId: getHistoricalBitcoinBalanceForNonHdAddress
tags: [Bitcoin]
parameters:
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
/v1/bitcoin-mainnet/address/{walletAddress}/transactions_v2/:
get:
summary: Get Bitcoin Transactions For Non-HD Address
operationId: getBitcoinTransactionsForNonHdAddress
tags: [Bitcoin]
parameters:
- $ref: '#/components/parameters/WalletAddress'
responses:
'200': { description: OK }
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: "GoldRush API key, sent as `Authorization: Bearer <key>`."
parameters:
ChainName:
name: chainName
in: path
required: true
description: Chain slug (e.g., `eth-mainnet`, `base-mainnet`, `solana-mainnet`, `polygon-mainnet`) or numeric chain ID.
schema: { type: string }
WalletAddress:
name: walletAddress
in: path
required: true
description: Wallet address. EVM 0x-prefixed; ENS / Lens / Unstoppable names also accepted on Base service.
schema: { type: string }
responses:
Unauthorized:
description: Unauthorized - missing or invalid Bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: Too Many Requests - rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
error: { type: boolean }
error_message: { type: string }
error_code: { type: integer }
BalanceResponse:
type: object
properties:
data:
type: object
properties:
address: { type: string }
updated_at: { type: string, format: date-time }
next_update_at: { type: string, format: date-time }
quote_currency: { type: string }
chain_id: { type: integer }
chain_name: { type: string }
items:
type: array
items: { $ref: '#/components/schemas/BalanceItem' }
error: { type: boolean }
error_message: { type: string, nullable: true }
error_code: { type: integer, nullable: true }
BalanceItem:
type: object
properties:
contract_decimals: { type: integer }
contract_name: { type: string }
contract_ticker_symbol: { type: string }
contract_address: { type: string }
supports_erc: { type: array, items: { type: string } }
logo_url: { type: string }
last_transferred_at: { type: string, format: date-time, nullable: true }
native_token: { type: boolean }
type: { type: string }
balance: { type: string }
balance_24h: { type: string, nullable: true }
quote_rate: { type: number, nullable: true }
quote_rate_24h: { type: number, nullable: true }
quote: { type: number }
quote_24h: { type: number, nullable: true }
pretty_quote: { type: string }
pretty_quote_24h: { type: string, nullable: true }
TransactionResponse:
type: object
properties:
data:
type: object
properties:
address: { type: string }
updated_at: { type: string, format: date-time }
next_update_at: { type: string, format: date-time }
quote_currency: { type: string }
chain_id: { type: integer }
chain_name: { type: string }
current_page: { type: integer }
links:
type: object
properties:
prev: { type: string, nullable: true }
next: { type: string, nullable: true }
items:
type: array
items: { $ref: '#/components/schemas/TransactionItem' }
TransactionItem:
type: object
properties:
block_signed_at: { type: string, format: date-time }
block_height: { type: integer }
block_hash: { type: string }
tx_hash: { type: string }
tx_offset: { type: integer }
successful: { type: boolean }
from_address: { type: string }
from_address_label: { type: string, nullable: true }
to_address: { type: string }
to_address_label: { type: string, nullable: true }
value: { type: string }
value_quote: { type: number }
pretty_value_quote: { type: string }
gas_offered: { type: integer }
gas_spent: { type: integer }
gas_price: { type: integer }
gas_quote: { type: number }
gas_quote_rate: { type: number }
log_events:
type: array
items: { type: object }