Getting Started

🚀 New to GMGN.ai? Create your account with our referral link to support GmGnAPI’s development → Sign up on GMGN.ai
💬 Need help? Join the Chipa Discord · ⚡ Go no-code with ChipaEditor

Learn how to install and set up GmGnAPI to start receiving real-time Solana blockchain data from GMGN.ai.

Installation

GmGnAPI is available on PyPI:

pip install gmgnapi

For development or the latest features:

git clone https://gitlab.chipatrade.com/chipadevorg/GmGnAPI.git
cd GmGnAPI
pip install -e .

See the full Installation guide for Docker, Poetry, Conda, and optional extras.

GMGN Account Setup

1. Create your GMGN account

To use GmGnAPI you need a GMGN account. Create yours with our referral link — it’s free and helps support GmGnAPI development:

👉 Create GMGN Account

2. Get your API token

1. Log in to your GMGN account
2. Navigate to Account Settings
3. Generate an API token
4. Copy and securely store your token

⚠️ Security note: never share your API token or commit it to version control.

3. Join the community

Get help, share experiences, and stay updated with the latest features on the Chipa Discord.

Requirements

# Install with optional dependencies
pip install gmgnapi[all]

# Or install specific optional dependencies
pip install gmgnapi[pandas,analysis]

Quick Start

Here’s the fastest way to start receiving real-time data:

import asyncio
from gmgnapi import GmGnClient

async def main():
    # Create client instance
    async with GmGnClient() as client:
        # Subscribe to new liquidity pools
        await client.subscribe_new_pools(chain="sol")

        # Define event handler
        @client.on_new_pool
        async def handle_new_pool(pool_data):
            print(f"🆕 New pool detected!")
            for pool in pool_data.pools:
                if pool.bti:  # Base token info available
                    print(f"  Token: {pool.bti.s} ({pool.bti.n})")
                    print(f"  Market Cap: ${pool.bti.mc:,.2f}")
                    print(f"  Exchange: {pool.ex}")
                    print("-" * 40)

        # Start listening for messages
        print("🔥 Starting GMGN data stream...")
        await client.listen()

# Run the async function
if __name__ == "__main__":
    asyncio.run(main())

Save this as quick_start.py and run it with python quick_start.py. You should start seeing real-time pool data!

Authentication

Some GMGN.ai channels require authentication. You can provide your access token in several ways:

1. Environment variable (recommended)

export GMGN_ACCESS_TOKEN="your_access_token_here"

# Client will automatically use the environment variable
async with GmGnClient() as client:
    await client.subscribe_wallet_trades()  # Requires auth

2. Direct parameter

async with GmGnClient(access_token="your_token") as client:
    await client.subscribe_wallet_trades()

3. Configuration file

# config.json
# {
#     "access_token": "your_access_token_here",
#     "default_chain": "sol"
# }

import json
with open('config.json') as f:
    config = json.load(f)

async with GmGnClient(access_token=config['access_token']) as client:
    ...  # Your code here

⚠️ Never commit access tokens to version control. Use environment variables or secure configuration management.

Basic Usage Patterns

Available subscriptions

Multiple subscriptions

async def multi_subscription_example():
    async with GmGnClient() as client:
        # Subscribe to multiple data streams
        await client.subscribe_new_pools(chain="sol")
        await client.subscribe_token_updates(tokens=["EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"])

        # Handle different event types
        @client.on_new_pool
        async def handle_pools(data):
            print(f"📊 New pool: {len(data.pools)} pools")

        @client.on_token_update
        async def handle_updates(data):
            print(f"💰 Token update: ${data.price_usd}")

        @client.on_error
        async def handle_error(error):
            print(f"❌ Error: {error}")

        await client.listen()

Chain selection

# Solana (default)
await client.subscribe_new_pools(chain="sol")

# Ethereum
await client.subscribe_new_pools(chain="eth")

# Binance Smart Chain
await client.subscribe_new_pools(chain="bsc")

# Polygon
await client.subscribe_new_pools(chain="polygon")

Error Handling

GmGnAPI includes comprehensive error handling and automatic reconnection:

import logging
from gmgnapi import GmGnClient, GmGnAPIError

# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

async def robust_client_example():
    try:
        async with GmGnClient() as client:
            # Error event handler
            @client.on_error
            async def handle_error(error):
                logger.error(f"WebSocket error: {error}")

            # Connection event handlers
            @client.on_connect
            async def handle_connect():
                logger.info("✅ Connected to GMGN WebSocket")

            @client.on_disconnect
            async def handle_disconnect():
                logger.warning("⚠️ Disconnected from GMGN WebSocket")

            @client.on_reconnect
            async def handle_reconnect():
                logger.info("🔄 Reconnected to GMGN WebSocket")

            await client.subscribe_new_pools()
            await client.listen()

    except GmGnAPIError as e:
        logger.error(f"GMGN API Error: {e}")
    except Exception as e:
        logger.error(f"Unexpected error: {e}")
        raise

Common error types

Next Steps

• Examples — practical examples for common use cases
• API Reference — complete documentation of all classes and methods
• Advanced Features — filtering, monitoring, and data export

Pro tips

• Use the enhanced client (GmGnEnhancedClient) for production applications
• Enable logging to debug connection issues
• Consider implementing data persistence for important events
• Monitor your application’s memory usage with long-running connections
• Join the Chipa Discord for community support — and try ChipaEditor to build strategies without writing code