Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.getelyra.xyz/llms.txt

Use this file to discover all available pages before exploring further.

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

​
wallet
string
required
Base58-encoded Solana wallet address to inspect.
​
limit
number
default:"100"
Maximum number of token transfers to fetch from Helius. Clamped to the range 1–100 by the underlying collector.
​
sol_threshold
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.
​
token_threshold
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.
​
api_key
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].
​
wallet
string
required
The wallet address that was queried.
​
whale_transfers
object[]
required
Combined list of all whale transfers (inbound and outbound), in the order they were encountered. Each entry contains the fields below.
​
whale_in
object[]
required
Subset of whale_transfers where direction is "in".
​
whale_out
object[]
required
Subset of whale_transfers where direction is "out".
​
total_whale_in
number
required
Sum of all inbound whale transfer amounts, rounded to 4 decimal places.
​
total_whale_out
number
required
Sum of all outbound whale transfer amounts, rounded to 4 decimal places.
​
count_in
number
required
Number of inbound whale transfers found.
​
count_out
number
required
Number of outbound whale transfers found.
​
sol_threshold
number
required
The sol_threshold value used for this query, echoed back for reference.
​
token_threshold
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.