Wallet Activity Stream

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:

• Transfer
• Swap
• Bridge
• Deposit
• Withdraw
• Approve

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

Parameter	Type	Required	Description
chain_name	enum	Yes	Chain name to filter events (e.g. BASE_MAINNET, ETH_MAINNET, BSC_MAINNET)
wallet_addresses	array<string>	Yes	Addresses 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:

socket.ts ( graphql-ws )

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

Field	Type	Description
tx_hash	string	The transaction hash
from_address	string	The sender’s address
to_address	string	The recipient’s address
value	integer	The transaction value in native currency
chain_name	string	The blockchain network where the transaction occurred
block_signed_at	string	ISO timestamp of when the block was signed
block_height	integer	The block number where the transaction was included
block_hash	string	The hash of the block containing the transaction
miner_address	string	The address of the block miner
gas_used	integer	The amount of gas used by the transaction
tx_offset	integer	The position of the transaction in the block
successful	boolean	Whether the transaction was successful
decoded_type	string	The type of decoded event (e.g., “SWAP”)
decoded	object	The decoded event data (varies by event type)
logs	array	Array of event logs emitted during the transaction

GraphQL Playground