TaoStats Skill

Purpose: Interact with TaoStats API for Bittensor blockchain data - subnets, validators, miners, staking, emissions, and more.

API Documentation: https://docs.taostats.io/
Base URL: https://api.taostats.io
Rate Limit: 5 calls/minute (free tier)

---

Setup

1. Set API Key

Get a free API key from taostats.io and export it as an environment variable:

export TAOSTATS_API_KEY="tao-xxxxx:yyyyy"

2. Source Helper Functions

source ~/.openclaw/workspace/skills/taostats/taostats.sh

---

Complete Endpoint Reference

dTAO Pool Endpoints

GET /api/dtao/pool/latest/v1?netuid={N}

CRITICAL: This endpoint has EVERYTHING for trading decisions.

Key Fields:

• price - Current alpha price in TAO
• root_prop - % of price from root TAO injection (CRITICAL for entry validation)
• fear_and_greed_index / fear_and_greed_sentiment - Market sentiment
• seven_day_prices - Historical price array (42 data points)
• price_change_1_hour, price_change_1_day, price_change_1_week, price_change_1_month
• market_cap, liquidity, total_tao, total_alpha
• tao_volume_24_hr, alpha_volume_24_hr, buys_24_hr, sells_24_hr
• highest_price_24_hr, lowest_price_24_hr

Example:

curl -s "https://api.taostats.io/api/dtao/pool/latest/v1?netuid=33" \
  -H "Authorization: $TAOSTATS_API_KEY" | jq '.data[0].root_prop'
# Returns: "0.2104087259347016725" (21% - GOOD entry)

GET /api/dtao/pool/history/v1?netuid={N}&limit={L}

Historical pool snapshots for backtesting.

GET /api/dtao/validator/yield/latest/v1?netuid={N}

Validator APYs with multiple timeframes.

Key Fields:

• seven_day_apy - Primary metric for staking decisions
• one_day_apy, one_hour_apy, thirty_day_apy
• seven_day_epoch_participation - Validator reliability
• name, hotkey.ss58, stake, take

Example:

curl -s "https://api.taostats.io/api/dtao/validator/yield/latest/v1?netuid=33" \
  -H "Authorization: $TAOSTATS_API_KEY" | \
  jq -r '.data | sort_by(-.seven_day_apy) | .[0] | 
  "\(.name // .hotkey.ss58): \(.seven_day_apy * 100)% APY"'

GET /api/dtao/stake_balance/latest/v1?coldkey={COLDKEY}

All stake positions across all subnets.

Key Fields:

• netuid, hotkey.ss58, hotkey_name
• balance_as_tao - ⚠️ IN RAO (divide by 1e9)
• price, price_change_1_day
• root_prop - Per-position root proportion

Subnet Endpoints

GET /api/subnet/latest/v1 or ?netuid={N}

Complete subnet parameters and economics.

Key Fields:

• netuid, emission, projected_emission
• net_flow_1_day, net_flow_7_days, net_flow_30_days - Capital flow tracking
• recycled_24_hours, recycled_lifetime - Registration economics
• tao_flow, excess_tao - dTAO mechanics
• immune_owner_uids_limit, immunity_period - Risk assessment
• max_validators, active_validators
• difficulty, adjustment_alpha - Mining economics

GET /api/subnet/registration/v1?netuid={N}

Subnet registration details.

Key Fields:

• owner.ss58 - Subnet owner
• registration_cost - Current registration cost
• timestamp - When registered

Validator Endpoints

GET /api/validator/latest/v1?netuid={N}

Current validator state.

Key Fields:

• apr, apr_7_day_average, apr_30_day_average
• nominator_return_per_k - Staker yield per 1000 TAO
• nominators, nominators_24_hr_change - Capital inflows/outflows
• stake, stake_24_hr_change, validator_stake, system_stake
• take - Commission rate
• name, coldkey.ss58, hotkey.ss58
• permits - Subnet permissions

GET /api/validator/history/v1?netuid={N}&hotkey={H}&limit={L}

Historical validator performance.

Key Fields:

• All APR metrics with daily granularity
• nominators_24_hr_change - Track capital movements
• dominance, subnet_dominance - Market share

Transaction Endpoints

GET /api/delegation/v1?nominator={COLDKEY}&action={all|stake|unstake}&limit={L}

Complete transaction history (stakes, unstakes, transfers).

Key Fields:

• action ("add" = stake, "remove" = unstake)
• amount, rate (price), tao_amount, alpha_amount
• fee, slippage
• block_number, timestamp
• hotkey.ss58, coldkey.ss58

GET /api/transfer/v1?from={COLDKEY}&limit={L}

TAO transfer history (not staking).

Key Fields:

• from.ss58, to.ss58, amount, fee
• block_number, timestamp

Metagraph Endpoints

GET /api/metagraph/latest/v1?netuid={N}&limit={L}

Complete subnet state for every neuron.

Key Fields:

• uid, hotkey.ss58, coldkey.ss58
• rank, trust, consensus, incentive, dividends, emission
• alpha_stake, root_stake, total_alpha_stake
• daily_mining_alpha, daily_validating_alpha, daily_reward
• validator_permit, is_immunity_period, in_danger
• daily_burned_alpha, daily_owner_alpha

GET /api/neuron/latest/v1?netuid={N}&limit={L}

Simplified neuron view with pruning risk.

Key Fields:

• uid, name, hotkey.ss58, coldkey.ss58
• pruning_score, in_danger, is_immune
• miner_rank, validator_rank

---

Quick Reference

Get Subnet Pool Data

taostats_pool 33
# Returns: price, root_prop, fear_and_greed_index, 7-day price history, volume

Get Validator APYs

taostats_validator_yield 33
# Returns: All validators with 1h/1d/7d/30d APYs

Get Stake Balances

taostats_stake_balance "YOUR_COLDKEY_HERE"
# Returns: All positions with root_prop per subnet

Get Transaction History

taostats_delegation_history "YOUR_COLDKEY_HERE"
# Returns: All stake/unstake transactions with slippage

Get Subnet Parameters

taostats_subnet_info 33
# Returns: Emissions, net flows, registration cost, immunity params

Get Metagraph

taostats_metagraph 33
# Returns: All neurons with stakes, ranks, emissions

---

Common Patterns

Check Entry Quality (root_prop < 0.30)

NETUID=33
ROOT_PROP=$(curl -s "https://api.taostats.io/api/dtao/pool/latest/v1?netuid=$NETUID" \
  -H "Authorization: $TAOSTATS_API_KEY" | jq -r '.data[0].root_prop')

if (( $(echo "$ROOT_PROP < 0.30" | bc -l) )); then
  echo "SN$NETUID: GOOD entry (root_prop: $ROOT_PROP)"
else
  echo "SN$NETUID: AVOID (root_prop: $ROOT_PROP - artificial price)"
fi

Find Best Validator for Subnet

NETUID=33
curl -s "https://api.taostats.io/api/dtao/validator/yield/latest/v1?netuid=$NETUID" \
  -H "Authorization: $TAOSTATS_API_KEY" | \
  jq -r '.data | sort_by(-.seven_day_apy) | .[0] | 
  "\(.name // .hotkey.ss58) | APY: \(.seven_day_apy * 100)% | Commission: \(.take * 100)%"'

Check Portfolio with root_prop per Position

COLDKEY="YOUR_COLDKEY_HERE"
curl -s "https://api.taostats.io/api/dtao/stake_balance/latest/v1?coldkey=$COLDKEY" \
  -H "Authorization: $TAOSTATS_API_KEY" | \
  jq -r '.data[] | 
  "SN\(.netuid): \((.balance_as_tao | tonumber) / 1000000000) TAO | root_prop: \(.root_prop)"'

Scan for High APY Opportunities (S-tier only)

for NETUID in 33 64 51 13 3 1 100; do
  MAX_APY=$(curl -s "https://api.taostats.io/api/dtao/validator/yield/latest/v1?netuid=$NETUID" \
    -H "Authorization: $TAOSTATS_API_KEY" | jq -r '.data | max_by(.seven_day_apy) | .seven_day_apy')
  echo "$NETUID|$MAX_APY"
  sleep 0.3
done | sort -t'|' -k2 -rn | while IFS='|' read netuid apy; do
  printf "SN%-3s: %6.1f%%\n" "$netuid" "$(echo "$apy * 100" | bc -l)"
done

Monitor Capital Flows (net_flow indicates momentum)

curl -s "https://api.taostats.io/api/subnet/latest/v1" \
  -H "Authorization: $TAOSTATS_API_KEY" | \
  jq -r '.data[] | select(.netuid != 0) | 
  "SN\(.netuid): net_flow_7d=\(.net_flow_7_days) | emission=\(.emission)"' | \
  sort -t'=' -k2 -rn | head -10

---

Python Tools

taostats_client.py

Robust API client with automatic retry logic.

from taostats_client import TaostatsAPI

api = TaostatsAPI("your-api-key")

# Single call with retry
result = api.get_json("dtao/pool/latest/v1?netuid=33")

# Paginated (handles all pages automatically)
all_data = api.get_paginated("dtao/stake_balance/latest/v1?coldkey=XYZ")

# Balance history
history = api.get_balance_history(coldkey, start_timestamp, end_timestamp)

balance_history.py

Track daily portfolio changes over time.

# View last 30 days
python3 skills/taostats/balance_history.py --days 30

# Export to CSV
python3 skills/taostats/balance_history.py --days 90 --export

Output:

📊 Portfolio History (30 records):
--------------------------------------------------------------------------------
Date         Free τ    Staked τ    Total τ    Daily Δ
--------------------------------------------------------------------------------
2026-01-07   0.0234    1.9567    1.9801            
2026-01-08   0.0256    1.9789    2.0045   +0.0244
...
Overall Change: +0.5399 τ (+27.27%)

---

Bash Functions (taostats.sh)

Core Trading Functions

taostats_pool <netuid>

Get full pool data including root_prop and fear & greed.

• Returns: price, root_prop, fear_and_greed_index, seven_day_prices, volume
• Use for: Entry validation, sentiment analysis, price history

taostats_pool_history <netuid> [limit]

Historical pool snapshots.

• Returns: Time-series of pool state
• Use for: Backtesting, trend analysis

taostats_validator_yield <netuid>

All validators with APYs.

• Returns: 1h/1d/7d/30d APYs, participation rates
• Use for: Validator selection

taostats_stake_balance <coldkey>

All positions with per-subnet root_prop.

• Returns: Balance, price, root_prop per position
• Use for: Portfolio monitoring, risk assessment

taostats_delegation_history <coldkey> [limit]

Transaction history with slippage.

• Returns: Stakes, unstakes, fees, slippage
• Use for: Performance tracking, tax records

Subnet Analysis Functions

taostats_subnet_info [netuid]

Subnet parameters and economics.

• Returns: Emissions, net flows, registration costs
• Use for: Fundamental analysis

taostats_subnet_registration <netuid>

Subnet ownership and registration details.

• Returns: Owner, registration cost, timestamp
• Use for: Due diligence

Validator Analysis Functions

taostats_validator_info <netuid>

Current validator state.

• Returns: APR, nominator returns, stake changes
• Use for: Deep validator research

taostats_validator_history <netuid> <hotkey> [limit]

Historical validator performance.

• Returns: Daily APR trends
• Use for: Validator reliability assessment

Metagraph Functions

taostats_metagraph <netuid>

Complete subnet state.

• Returns: All neurons with stakes, emissions, ranks
• Use for: Ecosystem analysis

taostats_neurons <netuid>

Simplified neuron view.

• Returns: Pruning scores, immunity status
• Use for: Risk monitoring

---

Rate Limit Handling

Free tier: 5 calls per minute

Best practices:

1. Cache pool data (changes slowly)
2. Use sleep 0.3 between calls (20 calls/min safe)
3. Batch where possible
4. Monitor for 429 errors

Example rate-limited loop:

for NETUID in {1..50}; do
  taostats_pool $NETUID | jq -r '.data[0] | "SN\(.netuid): root_prop=\(.root_prop)"'
  sleep 0.3
done

---

Error Handling

---

Critical Fields for Trading

Entry Validation

• root_prop < 0.30 = Good (organic price)
• root_prop > 0.70 = Bad (artificially pumped)

Momentum Signals

• net_flow_7_days > 0 = Capital inflow
• nominators_24_hr_change > 0 = Growing validator stake

Risk Metrics

• in_danger = true → Pruning risk
• is_immunity_period = true → Protected from dereg
• pruning_score → Lower is safer

Sentiment

• fear_and_greed_index < 30 = Fear (potential buy)
• fear_and_greed_index > 70 = Greed (potential wait)

---

Known Issues

balance_as_tao Field Bug

Issue: Returns value in rao (raw units), not TAO.

Workaround: Always divide by 1,000,000,000

balance_tao=$(echo "$balance_as_tao / 1000000000" | bc -l)

Affected endpoints:

• /api/dtao/stake_balance/latest/v1

---

Integration Examples

Entry Scanner (root_prop + APY + flow)

#!/bin/bash
source ~/.openclaw/workspace/skills/taostats/taostats.sh

echo "=== High-Quality Entry Opportunities ==="
for NETUID in 33 64 51 13 3 1 100 117 12 120; do
  POOL=$(taostats_pool $NETUID)
  ROOT_PROP=$(echo "$POOL" | jq -r '.data[0].root_prop')
  PRICE=$(echo "$POOL" | jq -r '.data[0].price')
  FEAR_GREED=$(echo "$POOL" | jq -r '.data[0].fear_and_greed_sentiment')
  
  MAX_APY=$(taostats_validator_yield $NETUID | jq -r '.data | max_by(.seven_day_apy) | .seven_day_apy')
  
  if (( $(echo "$ROOT_PROP < 0.30" | bc -l) )); then
    printf "SN%-3s | root_prop: %.2f | APY: %5.1f%% | Sentiment: %s\n" \
      "$NETUID" "$ROOT_PROP" "$(echo "$MAX_APY * 100" | bc -l)" "$FEAR_GREED"
  fi
  sleep 0.3
done

Portfolio Risk Monitor

#!/bin/bash
source ~/.openclaw/workspace/skills/taostats/taostats.sh

COLDKEY="YOUR_COLDKEY"
echo "=== Portfolio Risk Assessment ==="

taostats_stake_balance $COLDKEY | jq -r '.data[] | 
  "\(.netuid)|\(.balance_as_tao)|\(.root_prop)"' | while IFS='|' read netuid balance root_prop; do
  BALANCE_TAO=$(echo "$balance / 1000000000" | bc -l)
  if (( $(echo "$root_prop > 0.50" | bc -l) )); then
    printf "⚠️ SN%-3s: %6.3f TAO | HIGH root_prop: %.2f - Consider exit\n" "$netuid" "$BALANCE_TAO" "$root_prop"
  else
    printf "✅ SN%-3s: %6.3f TAO | OK root_prop: %.2f\n" "$netuid" "$BALANCE_TAO" "$root_prop"
  fi
done

---

Python Wrapper

import requests
import os

class TaoStatsAPI:
    def __init__(self):
        self.base_url = "https://api.taostats.io"
        self.api_key = os.getenv("TAOSTATS_API_KEY")
        
    def _get(self, endpoint):
        headers = {"Authorization": self.api_key, "accept": "application/json"}
        r = requests.get(f"{self.base_url}{endpoint}", headers=headers)
        return r.json()
    
    def pool(self, netuid):
        """Get pool data with root_prop and fear & greed"""
        return self._get(f"/api/dtao/pool/latest/v1?netuid={netuid}")
    
    def validator_yield(self, netuid):
        """Get all validators with APYs"""
        return self._get(f"/api/dtao/validator/yield/latest/v1?netuid={netuid}")
    
    def stake_balance(self, coldkey):
        """Get all positions with root_prop per subnet"""
        return self._get(f"/api/dtao/stake_balance/latest/v1?coldkey={coldkey}")
    
    def subnet_info(self, netuid=None):
        """Get subnet parameters and net flows"""
        if netuid:
            return self._get(f"/api/subnet/latest/v1?netuid={netuid}")
        return self._get("/api/subnet/latest/v1")

# Usage
api = TaoStatsAPI()
pool = api.pool(33)
print(f"SN33 root_prop: {pool['data'][0]['root_prop']}")

---

Skill Maintenance

Last Updated: 2026-02-06
Author: vanlabs-dev
Dependencies: curl, jq, bc

Changelog:

• 2026-02-06: COMPLETE OVERHAUL - Discovered root_prop, fear_and_greed, 7-day history in pool endpoint
• 2026-02-06: Added all working endpoints from discovery testing
• 2026-02-06: Added entry validation patterns using root_prop
• 2026-02-03: Initial version

TODO:

• Add caching layer for pool data
• Build retry logic with exponential backoff
• Create real-time monitoring dashboard
• Add root_prop alerts for portfolio positions