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 }