gigadex-sdk

The community Python SDK for building on GigaDex on Robinhood Chain.

gigadex-sdk gives Python developers a typed foundation for reading GigaDex data, working with concentrated-liquidity prices and ticks, loading verified contract ABIs, and preparing inspectable Web3 transaction plans.

It is useful for:

• liquidity tooling and range-management bots
• portfolio dashboards
• analytics and reporting scripts
• research notebooks
• trading and automation tools

This SDK is community maintained. Review all transactions yourself before sending funds on-chain.

For detailed examples covering nearly every public module, see the full SDK usage guide.

Features

• GigaDex GraphQL client for tokens, pools, positions, and portfolio state.
• Typed Pydantic models for safer application code.
• Pool discovery helpers for filtering, finding, and sorting CL/classic pools.
• DEX-wide stats and portfolio summaries backed by GraphQL models where data is available.
• Concentrated-liquidity math for ticks, prices, ranges, and tick-spacing alignment.
• Packaged ABI loading for common GigaDex/Web3 contract interactions.
• Canonical Robinhood Chain contract registry for core, concentrated-liquidity, routing, and classic-liquidity contracts.
• Low-level calldata builders for ERC-20 approvals/transfers, swaps/quotes, CL positions, classic liquidity, CL/classic MasterChef earnings, and multicalls.
• Web3 helpers for contracts, chain validation, gas checks, signing, and sending transactions.
• Modern Python packaging with uv, pyproject.toml, and Python 3.11+ support.

Installation

With uv:

uv add gigadex-sdk

With pip:

pip install gigadex-sdk

Quick start

Fetch portfolio data

from gigadex_sdk.graphql_client import GigaDexGraphQLClient

GRAPHQL_URL = "https://edge.gigadex.fi/v1/graphql"
CHAIN_ID = 4663
ACCOUNT = "0x0000000000000000000000000000000000000000"

client = GigaDexGraphQLClient(GRAPHQL_URL)
portfolio = client.fetch_portfolio(chain_id=CHAIN_ID, account=ACCOUNT)

for position in portfolio.positions:
    print(position.token_id, position.pool, position.tick_lower, position.tick_upper)

List, filter, and sort pools

from gigadex_sdk.graphql_client import GigaDexGraphQLClient
from gigadex_sdk.pools import filter_pools, sort_pools

client = GigaDexGraphQLClient("https://edge.gigadex.fi/v1/graphql")
pools = client.fetch_pools(chain_id=4663, page_size=100)

cl_pools = filter_pools(pools, kind="cl")
top_by_tvl = sort_pools(cl_pools, by="tvl")[:10]

for pool in top_by_tvl:
    print(pool.address, pool.token0, pool.token1, pool.fee, pool.total_value_locked_usd)

Fetch DEX-wide stats

from gigadex_sdk.graphql_client import GigaDexGraphQLClient

client = GigaDexGraphQLClient("https://edge.gigadex.fi/v1/graphql")
stats = client.fetch_dex_stats(chain_id=4663)

print(stats.total_value_locked_usd, stats.volume24h_usd, stats.pool_count)

Plan a swap without sending it

from gigadex_sdk.contracts import ROBINHOOD_CONTRACTS
from gigadex_sdk.swaps import ExactInputSingleSwap, SwapPlanner, min_amount_out

planner = SwapPlanner()

# Usually this comes from a quoter call or simulation. The helper only applies
# explicit slippage math; it does not fetch prices by itself.
quoted_out = 1_000_000
amount_out_min = min_amount_out(quoted_out, slippage_bps=50)  # 0.50%

call = planner.exact_input_single_call(
    ExactInputSingleSwap(
        token_in=ROBINHOOD_CONTRACTS.weth,
        token_out=ROBINHOOD_CONTRACTS.usdg,
        fee=500,
        recipient="0x0000000000000000000000000000000000000000",
        amount_in=10**18,
        amount_out_minimum=amount_out_min,
    )
)

print(call.target)    # smart router address
print(call.calldata)  # review/simulate before signing elsewhere

Plan ERC-20 approvals and liquidity calls

from gigadex_sdk.contracts import ROBINHOOD_CONTRACTS
from gigadex_sdk.erc20 import ERC20Planner
from gigadex_sdk.position_manager import MintAmounts, MintPlan, PositionManagerPlanner

account = "0x0000000000000000000000000000000000000000"

erc20 = ERC20Planner()
approval = erc20.approve_call(
    token=ROBINHOOD_CONTRACTS.usdg,
    spender=ROBINHOOD_CONTRACTS.giga_positions,
    amount=1_000_000,
)

positions = PositionManagerPlanner()
mint = positions.mint_call(
    MintPlan(
        token0=ROBINHOOD_CONTRACTS.weth,
        token1=ROBINHOOD_CONTRACTS.usdg,
        fee=500,
        tick_lower=-200_200,
        tick_upper=-199_800,
        amounts=MintAmounts(10**18, 1_000_000, 99 * 10**16, 990_000),
        recipient=account,
        deadline=1_800_000_000,
    )
)

print(approval.calldata)
print(mint.calldata)

Plan “claim all fees” for CL positions

from gigadex_sdk.position_manager import PositionManagerPlanner

planner = PositionManagerPlanner()
calldata = planner.claim_all_fees_multicall_calldata(
    token_ids=[101, 102, 103],
    recipient="0x0000000000000000000000000000000000000000",
)

print(calldata)

Work with concentrated-liquidity ticks

from decimal import Decimal

from gigadex_sdk.math import percentage_range_ticks, range_width_percent

current_tick = -200_000
tick_spacing = 10

tick_lower, tick_upper = percentage_range_ticks(
    current_tick=current_tick,
    percent_each_side=Decimal("5"),
    tick_spacing=tick_spacing,
)

lower_pct, upper_pct = range_width_percent(tick_lower, tick_upper, current_tick)

print(tick_lower, tick_upper)
print(f"range: -{lower_pct:.2f}% / +{upper_pct:.2f}%")

Load packaged ABIs

from gigadex_sdk.abis import ERC20_ABI, GIGA_POSITIONS_ABI, abi_events

print(len(ERC20_ABI))
print(len(GIGA_POSITIONS_ABI))
print([event["name"] for event in abi_events(GIGA_POSITIONS_ABI)])

Use known Robinhood Chain contracts

from gigadex_sdk.contracts import ROBINHOOD_CHAIN_ID, contracts_for_chain

contracts = contracts_for_chain(ROBINHOOD_CHAIN_ID)

print(contracts.giga_positions)
print(contracts.cl_factory)
print(contracts.weth, contracts.usdg)

Create a Web3 contract

from dataclasses import dataclass

from gigadex_sdk.abis import ERC20_ABI
from gigadex_sdk.chain import ChainClient
from gigadex_sdk.contracts import ROBINHOOD_CHAIN_ID


@dataclass
class Settings:
    rpc_url: str
    chain_id: int = ROBINHOOD_CHAIN_ID
    private_key: str = ""
    account_address: str = ""
    max_gas_price_wei: int | None = None
    gas_limit_multiplier: float = 1.2
    wait_for_receipt_seconds: int = 0

    def require_rpc(self) -> None:
        if not self.rpc_url:
            raise ValueError("rpc_url is required")

    def require_wallet(self) -> None:
        if not self.private_key or not self.account_address:
            raise ValueError("wallet config is required")


chain_client = ChainClient(Settings(rpc_url="https://your-rpc.example"))
token = chain_client.contract("0x0000000000000000000000000000000000000000", ERC20_ABI)

Common constants

GIGADEX_GRAPHQL_URL = "https://edge.gigadex.fi/v1/graphql"
ROBINHOOD_CHAIN_ID = 4663

Contract coverage

The SDK ships the known verified GigaDex contract addresses for Robinhood Chain:

• core/governance: controller, emission center, vault, fee center, fee receiver, WETH
• concentrated liquidity: CL factory/deployer/router/quoters, Giga Positions, CL MasterChef, LM pool deployer, position descriptor
• routing/classic liquidity: smart router, mixed quoter, tick lens, interface multicall, classic factory/router/MasterChef

Addresses are exposed as lowercase strings for stable comparisons and config. Convert with Web3.to_checksum_address(...) before constructing Web3 contracts.

SDK boundary

This package is intentionally a reusable SDK, not a keeper bot. It provides the basic building blocks for GigaDex integrations: data fetching, typed models, contract addresses, ABI loading, Web3 helpers, CL math, and low-level calldata builders. Strategy code such as “rebalance when near edge”, alerting, retries, position sizing, private-key policy, or fully automated execution should live in separate applications that depend on this SDK.

The write-side modules deliberately return calldata or transaction-plan objects. They do not sign or send transactions by default. Review, simulate, and apply your own gas/slippage/private-key policy in the application layer.

Project status

gigadex-sdk is early software. The current focus is reliable read access, reusable data models, concentrated-liquidity math, and safe building blocks for bot authors.

On-chain write helpers are intentionally low-level. Applications should add their own policy layer for slippage, gas limits, simulation, private-key handling, retries, alerts, and human review.

Pool creation transaction execution is intentionally not implemented yet. The SDK exposes only safe calldata-building extension points where the packaged ABIs support them; full pool-creation workflows should be added later with tests, simulation guidance, and clear review steps.

Contributing

Contributions are welcome. For development setup, test commands, release steps, and PyPI publishing notes, see README-DEV.md.

License

MIT