> ## 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.

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

> Identify large SOL and SPL token transfers for any Solana wallet via Helius. Classifies inflows and outflows above configurable thresholds as whale moves.

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](https://helius.dev) and set it in your environment:

```bash theme={null}
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:

```bash theme={null}
python3 agents/onchain_agent.py <solana_wallet_address>
```

Example using the default demo wallet:

```bash theme={null}
python3 agents/onchain_agent.py vines1vzrYbzLMRdu58ou5XTby4qAqVRLmqo36NKPTg
```

## Python usage

```python theme={null}
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**

```python theme={null}
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

<ParamField path="wallet" type="string" required>
  Base58-encoded Solana wallet address to inspect.
</ParamField>

<ParamField path="limit" type="number" default="100">
  Maximum number of token transfers to fetch from Helius. Clamped to the range 1–100 by the underlying collector.
</ParamField>

<ParamField path="sol_threshold" type="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.
</ParamField>

<ParamField path="token_threshold" type="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.
</ParamField>

<ParamField path="api_key" type="string">
  Helius API key. If omitted, the function reads `HELIUS_API_KEY` from the environment. Raises `HeliusAPIError` if neither is present.
</ParamField>

### 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]`.

<ResponseField name="wallet" type="string" required>
  The wallet address that was queried.
</ResponseField>

<ResponseField name="whale_transfers" type="object[]" required>
  Combined list of all whale transfers (inbound and outbound), in the order they were encountered. Each entry contains the fields below.

  <Expandable title="Transfer object fields">
    <ResponseField name="signature" type="string">
      Solana transaction signature.
    </ResponseField>

    <ResponseField name="timestamp" type="number">
      Unix timestamp of the transaction.
    </ResponseField>

    <ResponseField name="direction" type="string">
      `"in"` for inbound transfers, `"out"` for outbound transfers.
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transfer amount in token units (SOL or SPL).
    </ResponseField>

    <ResponseField name="symbol" type="string">
      Token ticker symbol. Defaults to `"UNKNOWN"` if not present in the Helius response.
    </ResponseField>

    <ResponseField name="counterparty" type="string">
      The other wallet address involved in the transfer.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="whale_in" type="object[]" required>
  Subset of `whale_transfers` where `direction` is `"in"`.
</ResponseField>

<ResponseField name="whale_out" type="object[]" required>
  Subset of `whale_transfers` where `direction` is `"out"`.
</ResponseField>

<ResponseField name="total_whale_in" type="number" required>
  Sum of all inbound whale transfer amounts, rounded to 4 decimal places.
</ResponseField>

<ResponseField name="total_whale_out" type="number" required>
  Sum of all outbound whale transfer amounts, rounded to 4 decimal places.
</ResponseField>

<ResponseField name="count_in" type="number" required>
  Number of inbound whale transfers found.
</ResponseField>

<ResponseField name="count_out" type="number" required>
  Number of outbound whale transfers found.
</ResponseField>

<ResponseField name="sol_threshold" type="number" required>
  The `sol_threshold` value used for this query, echoed back for reference.
</ResponseField>

<ResponseField name="token_threshold" type="number" required>
  The `token_threshold` value used for this query, echoed back for reference.
</ResponseField>

### Example response

```json theme={null}
{
  "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:

```python theme={null}
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}
```

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