Tutorials
Hands-on, step-by-step guides that take you from zero to production. Each tutorial builds on the previous — follow them in order or jump straight to what you need.
All Tutorials
1. First Connection
Connect to GMGN.ai WebSocket and receive your first live token event in under 5 minutes.
2. Filtering Tokens
Use the built-in filter system to only receive tokens that match your criteria.
3. Alerts & Webhooks
Send Discord or Telegram notifications when high-potential tokens are spotted.
4. Saving to Database
Persist token data to SQLite or CSV for backtesting and analysis.
5. Simple Trading Bot
Wire GmGnAPI to a buy/sell execution layer for automated trading.
6. Production Deployment
Run your bot reliably with Docker, systemd, and health checks.
All tutorials were written and tested inside Chipa Editor — an AI-powered code editor that autocompletes async Python, explains errors in plain English, and lets you run snippets instantly. Try it free →
01. Your First Connection
This tutorial assumes you have Python 3.8+ installed. If you haven't installed GmGnAPI yet, see the Installation Guide.
Step 1 — Install the package
pip install gmgnapiStep 2 — Create a GMGN account
You need a free GMGN.ai account to access the API. Use our referral link — it's free and helps support development.
Create Free Account →Step 3 — Write the code
import asyncio
from gmgnapi import GmGnClient
async def main():
async with GmGnClient() as client:
await client.subscribe_new_pools()
@client.on_new_pool
async def on_pool(pool):
print(f"🆕 New pool on {pool.chain}: {pool.address}")
print(f" Market cap: ${pool.market_cap:,.0f}")
print("Listening for new pools… (Ctrl+C to stop)")
await client.listen()
asyncio.run(main())Step 4 — Run it
python first_connection.pyYou should see new Solana token pools streaming in within seconds. Next, learn to filter them.
02. Filtering Tokens
Most new pools are noise. The filter system lets you set hard conditions — only tokens that pass all filters fire your handler. See the full Filters Guide for every available option.
import asyncio
from gmgnapi import GmGnClient
from gmgnapi.filters import TokenFilter
async def main():
filters = TokenFilter(
min_market_cap=50_000, # at least $50k market cap
max_market_cap=5_000_000, # not already mega-cap
min_liquidity=10_000, # enough liquidity to trade
min_volume_1h=5_000, # some trading activity
require_verified=False, # include unverified
)
async with GmGnClient(filters=filters) as client:
await client.subscribe_new_pools()
@client.on_new_pool
async def on_pool(pool):
print(f"✅ PASSED FILTER: {pool.address} — mcap ${pool.market_cap:,.0f}")
await client.listen()
asyncio.run(main())Continue to Tutorial 3 — Alerts to notify yourself when these tokens appear.
03. Alerts & Webhooks
Send real-time Discord alerts when a token passes your filters. Join our Discord community to share your setups.
import asyncio, aiohttp
from gmgnapi import GmGnClient
from gmgnapi.filters import TokenFilter
DISCORD_WEBHOOK = "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE"
async def send_discord(pool):
payload = {
"embeds": [{
"title": f"🚀 New Token Alert",
"description": f"`{pool.address}`",
"color": 0x00ff88,
"fields": [
{"name": "Chain", "value": pool.chain, "inline": True},
{"name": "Market Cap", "value": f"${pool.market_cap:,.0f}", "inline": True},
{"name": "Liquidity", "value": f"${pool.liquidity:,.0f}", "inline": True},
{"name": "GMGN Link", "value": f"[View on GMGN](https://gmgn.ai/token/{pool.address})", "inline": False},
]
}]
}
async with aiohttp.ClientSession() as session:
await session.post(DISCORD_WEBHOOK, json=payload)
async def main():
filters = TokenFilter(min_market_cap=50_000, min_liquidity=10_000)
async with GmGnClient(filters=filters) as client:
await client.subscribe_new_pools()
@client.on_new_pool
async def on_pool(pool):
await send_discord(pool)
await client.listen()
asyncio.run(main())04. Saving to Database
Persist every token event for later analysis. GmGnAPI has built-in export helpers. See the Advanced docs for full options.
import asyncio
from gmgnapi import GmGnClient
from gmgnapi.export import SQLiteExporter
async def main():
exporter = SQLiteExporter("tokens.db")
await exporter.init()
async with GmGnClient() as client:
await client.subscribe_new_pools()
@client.on_new_pool
async def on_pool(pool):
await exporter.save(pool)
print(f"Saved {pool.address}")
await client.listen()
asyncio.run(main())05. Simple Trading Bot
Wire the stream to your execution layer. See the full Trading Bots guide for patterns, risk management, and position sizing.
import asyncio
from gmgnapi import GmGnClient
from gmgnapi.filters import TokenFilter
async def buy_token(address: str, amount_sol: float):
# plug in your own DEX / wallet execution here
print(f"BUY {amount_sol} SOL worth of {address}")
async def main():
filters = TokenFilter(
min_market_cap=30_000,
max_market_cap=500_000,
min_liquidity=8_000,
)
async with GmGnClient(filters=filters) as client:
await client.subscribe_new_pools()
@client.on_new_pool
async def on_pool(pool):
print(f"Signal: {pool.address}")
await buy_token(pool.address, amount_sol=0.1)
await client.listen()
asyncio.run(main())Automated trading carries real financial risk. Always test with small amounts first. Read the full Trading Bots guide before running live.
06. Production Deployment
Run your bot reliably 24/7. See the full Advanced → Production section for Docker Compose, systemd, and monitoring dashboards.
Minimal Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "bot.py"]requirements.txt
gmgnapi>=1.0.0
aiohttp>=3.9.0Run it
docker build -t my-gmgn-bot .
docker run -d --restart=always --name gmgn-bot my-gmgn-botWhat's Next?
Write These Tutorials Faster with Chipa Editor
Chipa Editor is the AI-powered code editor purpose-built for Python developers. It autocompletes async patterns, explains library docs inline, and catches bugs before you run your code.