On-Chain Agent: track Solana on-chain whale activity

The On-Chain Agent queries a Solana wallet’s token transfer history through the Helius API and filters for transfers that exceed whale thresholds — 100 SOL or 1,000,000 SPL token units by default. It separates inbound from outbound whale transfers and totals each side so you can assess accumulation or distribution pressure at a glance.

Requirements

You need a Helius API key to use this agent. Get one at helius.dev and set it in your environment:

export HELIUS_API_KEY=your_key_here

You can also pass the key directly as the api_key parameter. If the key is absent, the agent raises a HeliusAPIError rather than returning partial data.

CLI usage

Pass a Solana wallet address as the only argument:

python3 agents/onchain_agent.py <solana_wallet_address>

Example using the default demo wallet:

python3 agents/onchain_agent.py vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg

Python usage

from agents.onchain_agent import get_whale_activity_summary

summary = get_whale_activity_summary(
    wallet="vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg",
    limit=50,
    sol_threshold=100.0,
    token_threshold=1_000_000.0,
)

`get_whale_activity_summary()`

Fetches token transfers for the given wallet via Helius, applies whale threshold filters, and returns a summary with separate inbound and outbound lists and running totals. Signature

def get_whale_activity_summary(
    wallet: str,
    limit: int = 100,
    sol_threshold: float = 100.0,
    token_threshold: float = 1_000_000.0,
    api_key: str | None = None,
) -> dict[str, Any]

Parameters

string

required

Base58-encoded Solana wallet address to inspect.

number

default:"100"

Maximum number of token transfers to fetch from Helius. Clamped to the range 1–100 by the underlying collector.

number

default:"100.0"

Minimum SOL amount (in SOL, not lamports) for a native SOL transfer to be classified as a whale transfer. Transfers below this value are excluded from the results.

number

default:"1000000.0"

Minimum SPL token amount for a non-SOL token transfer to be classified as a whale transfer. The amount is compared against the raw token units returned by Helius.

string

Helius API key. If omitted, the function reads HELIUS_API_KEY from the environment. Raises HeliusAPIError if neither is present.

Threshold logic

Transfers are classified using the mint address to distinguish SOL from SPL tokens:

SOL transfers: mint equals So11111111111111111111111111111111111111112 → compared against sol_threshold
All other mints → compared against token_threshold

Return value

Returns dict[str, Any].

string

required

The wallet address that was queried.

object[]

required

Combined list of all whale transfers (inbound and outbound), in the order they were encountered. Each entry contains the fields below.

Show Transfer object fields

string

Solana transaction signature.

number

Unix timestamp of the transaction.

string

"in" for inbound transfers, "out" for outbound transfers.

number

Transfer amount in token units (SOL or SPL).

string

Token ticker symbol. Defaults to "UNKNOWN" if not present in the Helius response.

string

The other wallet address involved in the transfer.

object[]

required

Subset of whale_transfers where direction is "in".

object[]

required

Subset of whale_transfers where direction is "out".

number

required

Sum of all inbound whale transfer amounts, rounded to 4 decimal places.

number

required

Sum of all outbound whale transfer amounts, rounded to 4 decimal places.

number

required

Number of inbound whale transfers found.

number

required

Number of outbound whale transfers found.

number

required

The sol_threshold value used for this query, echoed back for reference.

number

required

The token_threshold value used for this query, echoed back for reference.

Example response

{
  "wallet": "vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg",
  "whale_transfers": [
    {
      "signature": "5xK9...",
      "timestamp": 1714000000,
      "direction": "in",
      "amount": 250.0,
      "symbol": "SOL",
      "counterparty": "3mNq..."
    }
  ],
  "whale_in": [
    {
      "signature": "5xK9...",
      "timestamp": 1714000000,
      "direction": "in",
      "amount": 250.0,
      "symbol": "SOL",
      "counterparty": "3mNq..."
    }
  ],
  "whale_out": [],
  "total_whale_in": 250.0,
  "total_whale_out": 0.0,
  "count_in": 1,
  "count_out": 0,
  "sol_threshold": 100.0,
  "token_threshold": 1000000.0
}

Graceful degradation

If the Helius API key is missing or the quota is exhausted, the agent raises an error. The full pipeline in main.py catches this and substitutes empty defaults so the remaining pipeline stages continue unaffected:

from agents.onchain_agent import get_whale_activity_summary

try:
    summary = get_whale_activity_summary(wallet="...", limit=50)
except Exception as e:
    print(f"On-chain data unavailable: {e}")
    summary = {"whale_in": 0, "whale_out": 0}

Helius free-tier accounts have usage limits. If you see a "max usage reached" error, upgrade your Helius plan or reduce limit.

Research Pipeline

Prediction Markets

On-Chain Agent: track Solana on-chain whale activity

Requirements

CLI usage

Python usage

`get_whale_activity_summary()`

Parameters

Threshold logic

Return value

Example response

Graceful degradation

​Requirements

​CLI usage

​Python usage

​get_whale_activity_summary()

​Parameters

​Threshold logic

​Return value

​Example response

​Graceful degradation

Requirements

CLI usage

Python usage

`get_whale_activity_summary()`

Parameters

Threshold logic

Return value

Example response

Graceful degradation