Skip to main content

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.

This GraphQL query provides a list of wallets with the highest trading volume for a specific token over the last 30 days, along with detailed information about their holdings, transaction activity, realized and unrealized profit/loss metrics.

Credit Cost

TBD

Supported Chains

  • BASE_MAINNET
  • BSC_MAINNET
  • ETH_MAINNET
  • GNOSIS_MAINNET
  • MEGAETH_MAINNET
  • OPTIMISM_MAINNET
  • POLYGON_MAINNET
This query is currently in Beta. It is stable for testing and evaluation but may undergo changes in schema or behavior as we continue to improve it. No API credits are currently charged.We welcome your feedback so please reach out to us directly to report issues or request features.

​
Parameters

​
chain_name
enum
required
Blockchain network to filter eventsType: ChainNameUpnl
​
token_address
string
required
Token contract address on a supported DEX and chain

​
Query

You can query the upnlForToken endpoint to retrieve top wallet trading data. 
query {
  upnlForToken(
    chain_name: ETH_MAINNET
    token_address: "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D"
  ) {
    volume
    wallet_address
    transactions_count
    balance
    contract_metadata {
      contract_name
      contract_address
      contract_decimals
      contract_ticker_symbol
    }
    token_address
    pnl_realized_usd
    pnl_unrealized_usd
    marketcap_usd
    balance_pretty
  }
}

​
Response Format

Here’s an example of the response data structure: 
{
  "data": {
    "upnlForToken": [
      {
        "token_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d",
        "wallet_address": "0x91d40e4818f4d4c57b4578d9eca6afc92ac8debe",
        "volume": "56708716",
        "transactions_count": 554,
        "pnl_realized_usd": -43239.81,
        "balance": "32944375440228563000000000",
        "balance_pretty": "32944375.4402",
        "pnl_unrealized_usd": 535182,
        "contract_metadata": {
          "contract_address": "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D",
          "contract_name": "Covalent X Token",
          "contract_ticker_symbol": "CXT",
          "contract_decimals": 18
        }
      },
      {
        "token_address": "0x7abc8a5768e6be61a6c693a6e4eacb5b60602c4d",
        "wallet_address": "0xfe97b0c517a84f98fc6ede3cd26b43012d31992a",
        "volume": "39102028",
        "transactions_count": 241,
        "pnl_realized_usd": 8799.58,
        "balance": "323138960338677960000000000",
        "balance_pretty": "323138960.3387",
        "pnl_unrealized_usd": 6417132,
        "contract_metadata": {
          "contract_address": "0x7ABc8A5768E6bE61A6c693a6e4EAcb5B60602C4D",
          "contract_name": "Covalent X Token",
          "contract_ticker_symbol": "CXT",
          "contract_decimals": 18
        }
      }
    ]
  }
}

​
Field Descriptions

​
volume
string
Total volume of tokens transferred (string to avoid JS precision loss)
​
wallet_address
string
Wallet address of the token holder (lowercase with 0x prefix)
​
transactions_count
int
Total number of transactions
​
balance
string
Current token balance (string to avoid JS precision loss)
​
contract_metadata
object
Token contract metadataType: TokenContractMetadata
​
token_address
string
Token contract address (lowercase with 0x prefix)
​
pnl_realized_usd
float
Realized profit and loss in USD
​
pnl_unrealized_usd
float
Unrealized profit and loss in USD
​
marketcap_usd
string
Market capitalization in USD
​
balance_pretty
string
Human-readable token balance with proper decimal places