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.

The Update Tokens stream provides real-time updates on the prices, volumes, market cap and liquidity of one or many tokens by tracking the highest-volume pool for each token. This documentation follows our standard streaming API structure. The token_addresses input is limited to a maximum of 5 addresses per subscription.

Credit Cost

1 per minute

Supported Chains

  • BASE_MAINNET
  • BSC_MAINNET
  • ETH_MAINNET
  • HYPEREVM_MAINNET
  • MEGAETH_MAINNET
  • MONAD_MAINNET
  • POLYGON_MAINNET
  • SOLANA_MAINNET

​
Parameters

​
chain_name
enum
required
Blockchain network to filter eventsType: ChainName
​
token_addresses
array<string>
required
Array of token addresses on supported DEXes and chains to track

​
Subscription

You can subscribe to the updateTokens endpoint to receive real-time swap updates for the highest-volume pool of each token. 
subscription {
  updateTokens(
    chain_name: BASE_MAINNET
    token_addresses: ["0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b"]
  ) {
    trader
    liquidity
    pair_address
    base_token {
      contract_name
      contract_address
      contract_decimals
      contract_ticker_symbol
    }
    last_5m {
      volume {
        previous_value
        pct_change
        current_value
      }
      unique_sellers {
        previous_value
        pct_change
        current_value
      }
      sell_count {
        previous_value
        pct_change
        current_value
      }
      price {
        previous_value
        pct_change
        current_value
      }
      buy_count {
        previous_value
        pct_change
        current_value
      }
      sell_volume {
        previous_value
        pct_change
        current_value
      }
      volume_usd {
        previous_value
        pct_change
        current_value
      }
      buy_volume {
        previous_value
        pct_change
        current_value
      }
      swap_count {
        previous_value
        pct_change
        current_value
      }
      unique_buyers {
        previous_value
        pct_change
        current_value
      }
    }
    last_6hr {
      volume {
        previous_value
        pct_change
        current_value
      }
      unique_sellers {
        previous_value
        pct_change
        current_value
      }
      sell_count {
        previous_value
        pct_change
        current_value
      }
      price {
        previous_value
        pct_change
        current_value
      }
      buy_count {
        previous_value
        pct_change
        current_value
      }
      sell_volume {
        previous_value
        pct_change
        current_value
      }
      volume_usd {
        previous_value
        pct_change
        current_value
      }
      buy_volume {
        previous_value
        pct_change
        current_value
      }
      swap_count {
        previous_value
        pct_change
        current_value
      }
      unique_buyers {
        previous_value
        pct_change
        current_value
      }
    }
    market_cap
    quote_rate
    last_24hr {
      volume {
        previous_value
        pct_change
        current_value
      }
      unique_sellers {
        previous_value
        pct_change
        current_value
      }
      sell_count {
        previous_value
        pct_change
        current_value
      }
      price {
        previous_value
        pct_change
        current_value
      }
      buy_count {
        previous_value
        pct_change
        current_value
      }
      sell_volume {
        previous_value
        pct_change
        current_value
      }
      volume_usd {
        previous_value
        pct_change
        current_value
      }
      buy_volume {
        previous_value
        pct_change
        current_value
      }
      swap_count {
        previous_value
        pct_change
        current_value
      }
      unique_buyers {
        previous_value
        pct_change
        current_value
      }
    }
    last_1hr {
      volume {
        previous_value
        pct_change
        current_value
      }
      unique_sellers {
        previous_value
        pct_change
        current_value
      }
      sell_count {
        previous_value
        pct_change
        current_value
      }
      price {
        previous_value
        pct_change
        current_value
      }
      buy_count {
        previous_value
        pct_change
        current_value
      }
      sell_volume {
        previous_value
        pct_change
        current_value
      }
      volume_usd {
        previous_value
        pct_change
        current_value
      }
      buy_volume {
        previous_value
        pct_change
        current_value
      }
      swap_count {
        previous_value
        pct_change
        current_value
      }
      unique_buyers {
        previous_value
        pct_change
        current_value
      }
    }
    quote_rate_usd
    sender
    quote_token {
      contract_name
      contract_address
      contract_decimals
      contract_ticker_symbol
    }
    id
    chain_name
    direction
    timestamp
  }
}

​
Response Format

Here’s an example of the response data structure: 
{
  "data": {
    "updateTokens": {
      "chain_name": "BASE_MAINNET",
      "pair_address": "0x9c087Eb773291e50CF6c6a90ef0F4500e349B903",
      "timestamp": "2025-06-28T14:30:00Z",
      "direction": "buy",
      "trader": "0xd2216ed62a5c84f285a051839e808902fe8fc90b",
      "sender": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
      "quote_rate": 0.0002962,
      "quote_rate_usd": 1.39,
      "volume": 0.2079461510855417,
      "volume_usd": 975.515187,
      "market_cap": 1390000,
      "liquidity": 450000,
      "base_token": {
        "contract_name": "Virtual Protocol",
        "contract_address": "0x0b3e328455c4059EEb9e3f84b5543F74E24e7E1b",
        "contract_decimals": 18,
        "contract_ticker_symbol": "VIRTUAL"
      },
      "quote_token": {
        "contract_name": "Wrapped Ether",
        "contract_address": "0x4200000000000000000000000000000000000006",
        "contract_decimals": 18,
        "contract_ticker_symbol": "WETH"
      },
      "last_5m": {
        "price_delta": { "current_value": 1.39, "previous_value": 1.38, "pct_change": 0.72 },
        "swap_count": { "current_value": 12, "previous_value": 8, "pct_change": 50 },
        "buy_volume": { "current_value": 500.25, "previous_value": 320.10, "pct_change": 56.3 },
        "sell_volume": { "current_value": 475.26, "previous_value": 290.50, "pct_change": 63.6 },
        "unique_traders": { "current_value": 5, "previous_value": 3, "pct_change": 66.7 },
        "total_buy_txns": { "current_value": 7, "previous_value": 5, "pct_change": 40 },
        "total_sell_txns": { "current_value": 5, "previous_value": 3, "pct_change": 66.7 }
      }
    }
  }
}

​
Field Descriptions

​
trader
string
Address of the trader who initiated the swap
​
liquidity
float
Total liquidity in the pool
​
pair_address
string
The address of the DEX pair
​
base_token
object
Information about the base token in the pairType: TokenContractMetadata
​
last_5m
object
Aggregated trading metrics for the last 5 minutesType: TimeframeMetrics
​
last_6hr
object
Aggregated trading metrics for the last 6 hoursType: TimeframeMetrics
​
market_cap
float
Market capitalization of the token pair
​
quote_rate
float
Exchange rate between base and quote tokens
​
last_24hr
object
Aggregated trading metrics for the last 24 hoursType: TimeframeMetrics
​
last_1hr
object
Aggregated trading metrics for the last 1 hourType: TimeframeMetrics
​
quote_rate_usd
float
Exchange rate between base and quote tokens in USD
​
sender
string
Address that sent the transaction
​
quote_token
object
Information about the quote token in the pairType: TokenContractMetadata
​
id
string
Unique identifier for this swap event
​
chain_name
enum
The blockchain network where the pair existsType: ChainName
​
direction
string
Swap direction: buy or sell
​
timestamp
string
Timestamp of the latest swap (ISO-8601)