Tradingtools
A few trading tools to use, with Tushare, GMGN scrapper, will keep adding more, and later support MCP
Installation
npx tradingtoolsAsk AI about Tradingtools
Powered by Claude Β· Grounded in docs
I know everything about Tradingtools. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
GMGN.ai API Wrapper (Refactored) with Rugcheck Integration
A comprehensive, modular Python wrapper for the GMGN.ai API with verified rugcheck integration and advanced filtering capabilities. This library provides a clean, type-safe interface for fetching cryptocurrency token data across multiple blockchain networks with built-in safety verification.
π Features
- π Multi-Chain Support: Ethereum, Solana, Base, BSC, and Tron
- π‘οΈ Rugcheck Integration: β WORKING - Built-in rug pull risk assessment for Solana tokens
- π Advanced Filtering: Filter by volume, market cap, liquidity, price changes, and safety criteria
- π¨ Multiple Formatters: Display token data in various formats including rugcheck results
- π Factory Functions: Quick access patterns for common use cases
- β‘ Cloudflare Bypass: Built-in protection against Cloudflare blocking
- π Type Safety: Full enum support and structured data models
- π§ Modular Design: Clean separation of concerns with pluggable components
- π Smart Retry Logic: Automatic session refresh and retry on failures
- π― Small Cap Discovery: Built-in filters for your specific criteria (MC < 200K, etc.)
π¦ Installation
Prerequisites
pip install tls-client fake-useragent rugcheck
Install from Source
git clone <your-repo-url>
cd tradingdata
π― Quick Start
from gmgn_api import create_api, Chain, get_safe_tokens_with_rugcheck
# Initialize the API
api = create_api(verbose=True)
# Get top volume tokens on Solana
volume_tokens = api.get_top_volume_tokens(Chain.SOLANA, limit=5)
# π‘οΈ Get rugcheck-verified safe tokens (WORKING!)
safe_tokens = get_safe_tokens_with_rugcheck(
Chain.SOLANA,
limit=5,
max_risk_score=0.3 # 0.0 = safest, 1.0 = highest risk
)
# Display results
for i, token in enumerate(volume_tokens, 1):
print(f"{i}. {token.symbol} - Volume: ${token.volume:,.0f}")
π‘οΈ Rugcheck Integration (Verified Working)
β Individual Token Risk Assessment
# Check any Solana token for rug risk
api = create_api()
# Real example from testing
risk_result = api.check_token_rug_risk(
"9BB6NFEcjBCtnNLFko2FqVQBq8HHM13kCyYcdQbgpump", # Fartcoin
Chain.SOLANA
)
print(f"Risk Score: {risk_result['risk_score']}") # 0.0 (Low Risk)
print(f"Rugcheck Score: {risk_result['rugcheck_score']}") # 3001 (High Safety)
print(f"Is Rugged: {risk_result['is_rugged']}") # False
print(f"Data Fields: {len(risk_result.keys())}") # 37+ fields available
π Risk Score Interpretation (Tested & Verified)
Based on actual testing with high-volume Solana tokens:
# Risk Score Guide (Inverted from rugcheck's safety score)
# 0.0 - 0.2: β
Low Risk (High Safety) - Recommended
# 0.2 - 0.5: β οΈ Medium Risk - Use Caution
# 0.5 - 1.0: π¨ High Risk - Avoid
# Real example interpretations:
if risk_result['risk_score'] <= 0.2:
print("β
Low Risk - Safe to trade")
elif risk_result['risk_score'] <= 0.5:
print("β οΈ Medium Risk - Research more")
else:
print("π¨ High Risk - Avoid")
π Batch Rugcheck Verification
# Get multiple rugcheck-verified tokens
verified_tokens = api.get_rugcheck_verified_tokens(
Chain.SOLANA,
criteria=SortCriteria.VOLUME,
limit=10,
max_risk_score=0.3 # Only tokens with risk β€ 0.3
)
# Tested output: Returns tokens like Fartcoin, PepeSquid, etc. with risk scores
print(f"Found {len(verified_tokens)} safe tokens")
π¨ Rugcheck Formatting
from gmgn_api import RugcheckFormatter
formatter = RugcheckFormatter()
# Individual token with rugcheck
risk_result = api.check_token_rug_risk(token.address, Chain.SOLANA)
formatted = formatter.format_with_rugcheck(token, risk_result, 1)
print(formatted)
# Output: "1. Fartcoin - β
Low Risk (0.00) | Price: $1.100560 | Vol: $72,685,000"
π Core API Reference
Token Data Model
@dataclass
class Token:
id: int
chain: str
address: str # Contract address
symbol: str # Token symbol
price: float # Current price
volume: float # 24h trading volume
liquidity: float # Available liquidity
market_cap: float # Market capitalization
holder_count: int # Number of holders
price_change_percent: float # 24h price change
price_change_percent1h: float # 1h price change
price_change_percent5m: float # 5m price change
is_honeypot: bool # Honeypot detection flag
# ... 20+ additional fields
Your Specific Use Case: Small Cap Discovery
# Your exact criteria implementation
small_cap_tokens = api.get_small_cap_tokens(Chain.SOLANA, limit=10)
# This filters for:
# - Market cap below $200K
# - Liquidity under $150K
# - Trading volume less than $300K
# - Minimum 1-day-old (when timestamp data available)
# - Excludes honeypots
# Display with specialized formatter
from gmgn_api import SmallCapFormatter
formatter = SmallCapFormatter()
for i, token in enumerate(small_cap_tokens, 1):
print(formatter.format(token, i))
# Output: "1. derek - MC: $17K | Liq: $14K | Vol: $259K | Price: $0.000017"
Advanced Filtering System
from gmgn_api import FilterCriteria, CriteriaFilter
# Custom criteria matching your needs
criteria = FilterCriteria(
min_volume=1000, # Minimum volume filter
max_volume=300000, # Your max: less than $300K
min_market_cap=1000, # Minimum market cap
max_market_cap=200000, # Your max: below $200K
min_liquidity=1000, # Minimum liquidity
max_liquidity=150000, # Your max: under $150K
min_holder_count=10, # Minimum holders
min_price_change=-100, # Minimum price change %
max_price_change=1000, # Maximum price change %
min_age_days=1, # Minimum 1-day-old
exclude_honeypots=True # Exclude honeypots
)
# Apply custom filter
custom_tokens = api.get_filtered_tokens(Chain.SOLANA, criteria, limit=20)
Supported Chains
class Chain(Enum):
ETHEREUM = "eth" # Ethereum mainnet
BINANCE_SMART_CHAIN = "bsc" # BSC
BASE = "base" # Base network
SOLANA = "sol" # Solana (rugcheck supported)
TRON = "tron" # Tron network
Time Periods & Sorting
class TimePeriod(Enum):
ONE_MINUTE = "1m"
FIVE_MINUTES = "5m"
ONE_HOUR = "1h"
SIX_HOURS = "6h"
TWENTY_FOUR_HOURS = "24h"
class SortCriteria(Enum):
VOLUME = "volume"
MARKETCAP = "marketcap"
LIQUIDITY = "liquidity"
HOLDER_COUNT = "holder_count"
CHANGE_1M = "change1m"
CHANGE_5M = "change5m"
CHANGE_1H = "change1h"
π§ Advanced Examples
Example 1: Complete Safety-First Workflow
from gmgn_api import create_api, Chain, RugcheckFormatter
# Step 1: Get potential tokens with your criteria
api = create_api()
candidates = api.get_small_cap_tokens(Chain.SOLANA, limit=20)
# Step 2: Rugcheck verification
safe_candidates = []
formatter = RugcheckFormatter()
for token in candidates:
risk_result = api.check_token_rug_risk(token.address, Chain.SOLANA)
# Only keep low-risk tokens
if risk_result.get('risk_score', 1.0) <= 0.3:
safe_candidates.append((token, risk_result))
# Step 3: Display results
print(f"π‘οΈ Found {len(safe_candidates)} safe small-cap tokens:")
for i, (token, risk_result) in enumerate(safe_candidates, 1):
formatted = formatter.format_with_rugcheck(token, risk_result, i)
print(formatted)
Example 2: Real-Time Market Scanning
from gmgn_api import create_volume_query, CompositeFilter, CriteriaFilter, TopNFilter
# Create market scan query
api = create_api()
params = create_volume_query(Chain.SOLANA, TimePeriod.ONE_HOUR)
# Apply your specific filters
criteria = FilterCriteria(
max_market_cap=200000, # Below $200K
max_volume=300000, # Less than $300K
max_liquidity=150000, # Under $150K
min_holder_count=20, # At least 20 holders
exclude_honeypots=True
)
# Combine with top filter
filters = CompositeFilter([
CriteriaFilter(criteria),
TopNFilter(10)
])
# Get filtered results
tokens = api.get_tokens_with_filter(params, filters)
# Batch rugcheck
print("π Scanning with rugcheck verification...")
for token in tokens:
risk_result = api.check_token_rug_risk(token.address, Chain.SOLANA)
risk_score = risk_result.get('risk_score', 1.0)
risk_emoji = "β
" if risk_score <= 0.2 else "β οΈ" if risk_score <= 0.5 else "π¨"
print(f"{risk_emoji} {token.symbol}: Risk {risk_score:.2f}, MC ${token.market_cap:,.0f}")
Example 3: Cross-Chain Volume Comparison
chains = [Chain.ETHEREUM, Chain.SOLANA, Chain.BASE]
print("π Top Volume Tokens Across Chains:")
for chain in chains:
try:
tokens = api.get_top_volume_tokens(chain, limit=3)
print(f"\nπ {chain.value.upper()}:")
for i, token in enumerate(tokens, 1):
vol_str = f"${token.volume/1_000_000:.1f}M" if token.volume >= 1_000_000 else f"${token.volume:,.0f}"
print(f" {i}. {token.symbol} - {vol_str}")
except Exception as e:
print(f" β {chain.value} Error: {e}")
π¨ Error Handling
from gmgn_api import GMGNAPIError, GMGNParsingError
try:
# Your trading logic
tokens = api.get_small_cap_tokens(Chain.SOLANA)
for token in tokens:
risk_result = api.check_token_rug_risk(token.address, Chain.SOLANA)
# Process results...
except GMGNAPIError as e:
print(f"π API Error {e.status_code}: {e.message}")
except GMGNParsingError as e:
print(f"π Data Parsing Error: {e}")
except Exception as e:
print(f"β Unexpected Error: {e}")
π Performance & Rate Limits
# Configure for your needs
config = GMGNConfig(
timeout=120, # 2 minute timeout
max_retries=5, # Retry failed requests
verbose=True, # Debug logging
request_delay=1.0 # 1 second between requests
)
api = GMGNTokenAPI(config)
π― Factory Functions for Quick Access
from gmgn_api import (
create_api,
get_safe_tokens_with_rugcheck,
create_volume_query,
create_gainers_query
)
# Quick API setup
api = create_api(verbose=True)
# Quick safe token access
safe_tokens = get_safe_tokens_with_rugcheck(
Chain.SOLANA,
limit=10,
max_risk_score=0.2
)
# Quick query builders
volume_query = create_volume_query(Chain.SOLANA, TimePeriod.TWENTY_FOUR_HOURS)
gainers_query = create_gainers_query(Chain.SOLANA, TimePeriod.ONE_HOUR)
π Migration from Old Version
See MIGRATION_GUIDE.md for detailed migration instructions from the previous API version.
π Additional Documentation
- Complete Examples: See
examples.pyfor comprehensive usage demonstrations - Rugcheck Testing: Run
python examples.pyto see working rugcheck integration - API Source: Check
gmgn_api.pyfor full implementation details
β οΈ Important Notes
- Rugcheck Limitation: Currently works with Solana tokens only
- Rate Limits: GMGN.ai may have rate limits; use delays between requests
- Risk Assessment: Rugcheck is one factor; always do additional research
- Data Freshness: Token data is real-time but rugcheck scores may cache
π Ready to Use!
This implementation has been tested with real Solana tokens and provides working rugcheck integration. The risk scoring system has been validated with high-volume tokens showing appropriate safety scores.
# Start trading safely!
from gmgn_api import get_safe_tokens_with_rugcheck, Chain
safe_tokens = get_safe_tokens_with_rugcheck(
Chain.SOLANA,
limit=10,
max_risk_score=0.3
)
print(f"Found {len(safe_tokens)} verified safe tokens!")
