The Wallet Activity stream provides real-time updates on wallet transactions, token transfers, and interactions with smart contracts . This documentation follows our standard Streaming API structure.

Credit Cost

TBD

Supported Chains

  • Base Mainnet
  • Base Sepolia Testnet
  • BSC Mainnet
  • BSC Testnet
  • Ethereum Mainnet
  • Ethereum Sepolia Testnet

This stream 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.

Authentication

Using any of the GoldRush developer tools requires an API key.

Get Started

Sign up for a free API key to get started with GoldRush.

Supported Actions

All transactions are returned as raw data, but the following transaction types are decoded:

Authentication

Using any of the GoldRush developer tools requires an API key.

Get Started

Sign up for a free API key to get started with GoldRush.

Parameters

ParameterTypeRequiredDescription
chain_nameenumYesChain name to filter events (e.g. BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
wallet_addressesarray<string>YesAddresses to track

Connection

If you’re not using the graphql-ws package, you must set the WebSocket protocol header:

"Sec-WebSocket-Protocol" : "graphql-transport-ws"

This header is required for the server to properly recognize and handle your GraphQL subscription requests.

The WebSocket uses the GraphQL query or subscription protocol. Here are examples of how one can connect with different languages:

import { createClient } from "graphql-ws";

const CONNECTION_URL = "wss://gr-staging.streaming.covalenthq.com/graphql";

const client = createClient({
  url: CONNECTION_URL,
  shouldRetry: (retries) => retries < 5,
  on: {
    connecting: () => {
      console.log("⏳ WebSocket connecting...");
    },
    opened: () => {
      console.log("✅ WebSocket connection established");
    },
    closed: () => {
      console.log("❌ WebSocket connection closed");
    },
    error: (err) => {
      console.error("⚠️ WebSocket error:", err);
    },
  },
});

Subscription

Once connected, you can subscribe to the walletTxs endpoint to receive notifications.

Basic Subscription Query

subscription {
  walletTxs(
    chain_name: BASE_MAINNET, 
    wallet_addresses: [
        "0x4200000000000000000000000000000000000006",
        "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    ]) {
        block_signed_at
        block_height
        tx_hash
        tx_offset
        successful
        decoded_type        
  }
}

Complete Subscription Query

subscription {
  walletTxs(
    chain_name: BASE_MAINNET,
    wallet_addresses: [
      "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
      "0x4200000000000000000000000000000000000006"
    ]
  ) {
    tx_hash
    from_address
    to_address
    value
    chain_name
    block_signed_at
    block_height
    block_hash
    miner_address
    gas_used
    tx_offset
    successful
    decoded_type

    decoded_details {
      ... on TransferTransaction {
        from
        to
        amount
        quote_usd
        quote_rate_usd
        contract_metadata {
          contract_name
          contract_address
          contract_decimals
          contract_ticker_symbol
        }
      }
      ... on SwapTransaction {
        token_in
        token_out
        amount_in
        amount_out
      }
      ... on BridgeTransaction {
        type
        typeString
        from
        to
        amount
        quote_usd
        quote_rate_usd
        contract_metadata {
          contract_name
          contract_address
          contract_decimals
          contract_ticker_symbol
        }
      }
      ... on DepositTransaction {
        from
        to
        amount
        quote_usd
        quote_rate_usd
        contract_metadata {
          contract_name
          contract_address
          contract_decimals
          contract_ticker_symbol
        }
      }
      ... on WithdrawTransaction {
        from
        to
        amount
        quote_usd
        quote_rate_usd
        contract_metadata {
          contract_name
          contract_address
          contract_decimals
          contract_ticker_symbol
        }
      }
      ... on ApproveTransaction {
        spender
        amount
        quote_usd
        quote_rate_usd
        contract_metadata {
          contract_name
          contract_address
          contract_decimals
          contract_ticker_symbol
        }
      }
      ... on ErrorDetails {
        message
      }
    }

    logs {
      emitter_address
      log_offset
      data
      topics
    }
  }
}

Implementation

client.subscribe({
    query: SUBSCRIPTION_QUERY
}, {
    next: (data) => {
        console.log(JSON.stringify(data));
    },
    error: (err) => console.error("⚠️ Subscription error:", err),
    complete: () => console.log("✅ Subscription completed"),
})

Decoded Events

Note from the Complete Subscription Query, this stream decodes events which you can fetch with fragment spreads. See the full schema of available decoded events.

Response Format

Here’s an example of the response data structure:

{
  "data": {
    "walletTxs": [
      {
        "tx_hash": "0x23a4f9710c23678a8c6ae25d7e3aa75a82866231e9bd541114046c5a710a8355",
        "from_address": "0xd2216ed62a5c84f285a051839e808902fe8fc90b",
        "to_address": "0x198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
        "value": 0,
        "chain_name": "base-mainnet",
        "block_signed_at": "2025-05-29T19:27:25Z",
        "block_height": 30878749,
        "block_hash": "0x2435aec7c20678ee82ae251ab1066e15ed3dac7ff0ea086c44ee8476a721abde",
        "miner_address": "0x4200000000000000000000000000000000000011",
        "gas_used": 195861,
        "tx_offset": 118,
        "successful": true,
        "decoded_type": "SWAP",
        "decoded": {
          "token_in": "0x4200000000000000000000000000000000000006",
          "amount_in": 1.157920892373162e+77,
          "token_out": "0x14b2f229097df3c92b43ea871860e3fae08d7f06",
          "amount_out": 1.0002764028751458e+23
        },
        "logs": [
          {
            "emitter": "0x4200000000000000000000000000000000000006",
            "topics": [
              "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
              "0x000000000000000000000000286f3add5dd41ba6e208f9f9a68533107fd0d0fa",
              "0x000000000000000000000000198ef79f1f515f02dfe9e3115ed9fc07183f02fc"
            ]
          },
          {
            "emitter": "0x14b2f229097df3c92b43ea871860e3fae08d7f06",
            "topics": [
              "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
              "0x000000000000000000000000d2216ed62a5c84f285a051839e808902fe8fc90b",
              "0x000000000000000000000000286f3add5dd41ba6e208f9f9a68533107fd0d0fa"
            ]
          },
          {
            "emitter": "0x286f3add5dd41ba6e208f9f9a68533107fd0d0fa",
            "topics": [
              "0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67",
              "0x000000000000000000000000198ef79f1f515f02dfe9e3115ed9fc07183f02fc",
              "0x000000000000000000000000198ef79f1f515f02dfe9e3115ed9fc07183f02fc"
            ]
          },
          {
            "emitter": "0x4200000000000000000000000000000000000006",
            "topics": [
              "0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65",
              "0x000000000000000000000000198ef79f1f515f02dfe9e3115ed9fc07183f02fc"
            ]
          }
        ]
      }
    ]
  }
}

Response Fields

FieldTypeDescription
tx_hashstringThe transaction hash
from_addressstringThe sender’s address
to_addressstringThe recipient’s address
valueintegerThe transaction value in native currency
chain_namestringThe blockchain network where the transaction occurred
block_signed_atstringISO timestamp of when the block was signed
block_heightintegerThe block number where the transaction was included
block_hashstringThe hash of the block containing the transaction
miner_addressstringThe address of the block miner
gas_usedintegerThe amount of gas used by the transaction
tx_offsetintegerThe position of the transaction in the block
successfulbooleanWhether the transaction was successful
decoded_typestringThe type of decoded event (e.g., “SWAP”)
decodedobjectThe decoded event data (varies by event type)
logsarrayArray of event logs emitted during the transaction

GraphQL Playground