🐍 fyuz-sdk (Python)

Typed, zero-dependency Python client for the Fyuz bonding-curve launchpad on BNB Smart Chain.

Fyuz tokens trade on an internal bonding curve until they reach a $30,000 market cap, then graduate into a PancakeSwap V2 pair. Before graduation there is no DEX pool anywhere on chain, so this API is the only source of price, liquidity and curve state for a pre-graduation token. This package wraps every one of its 28 read-only endpoints in frozen dataclasses, and builds unsigned bonding-curve transactions your own wallet signs. Standard library only — urllib, json, dataclasses. No requests, no httpx, no pydantic, no web3.

📦 Install

pip install fyuz-sdk          # import name: fyuz

From a checkout of this repository:

pip install /path/to/fyuz/sdk/python

Requires Python 3.9+. Ships a py.typed marker, so mypy and Pyright see the annotations.

⚡ Quickstart

from fyuz import FyuzClient

with FyuzClient() as fyuz:
    print(fyuz.health().status)                    # 'ok'

    # One dense row per token: cap, volume, holders, graduation progress.
    for t in fyuz.discover(tab="trending", limit=3):
        print(f"{t.symbol:<8} ${t.marketcap:>10,.0f}  {t.graduation_pct:5.1f}% to graduation")

    # Full curve state for one token — prices stay exact decimal strings.
    detail = fyuz.get_token("bsc", "0x42322852a918f94186b7dfda2e0e3f4ad3528480")
    token = detail.token_details
    print(token.token_symbol, token.price, token.graduated)

Real output, run against https://api.fyuz.fun:

ok
PROGI    $     4,473   14.9% to graduation
TUTACO   $     4,473   14.9% to graduation
SRIRA    $     4,473   14.9% to graduation
KIMKACHU 7.853031083E-9 False

🏆 Why this SDK

🎓 What "graduation" means

pair_address is None and no DEX pool exists anywhere until a token graduates at a $30,000 market cap. Nothing on PancakeSwap, DexScreener or any aggregator will show a pre-graduation token, because it does not exist there yet.

pool_type is 1 for PancakeSwap V2 and 2 for V3. network is the chain slug. The API serves BNB Smart Chain ("bsc", chain 56) and Robinhood Chain (chain 4663); every token today is on BSC.

🔢 Precision: decimal fields are strings, and they stay strings

Token amounts, prices, market caps and every *_wei value arrive as decimal strings, because 18-decimal values and uint256 wei amounts do not survive a round trip through a 64-bit float:

>>> float("123456789.123456789123456789")
123456789.12345679          # four digits gone, silently

This SDK keeps them as str in the models and never parses them into float. When you need arithmetic, use the opt-in helpers — they go through decimal.Decimal and are exact:

from fyuz import to_decimal, wei_to_bnb

mcap = to_decimal(token.marketcap)            # Decimal('4566.671076655321500000')
paid = wei_to_bnb(stats.total_paid_wei)       # Decimal BNB, no rounding

Aggregates computed server-side — volume_usd, points, reward_eth, pot_bnb, everything on DiscoverToken, Portfolio, WalletStats and the analytics endpoints — are genuine float values on the wire and are typed as float here.

Timestamps: Trade.date, KingReign.started_at, RoundReceipt.time_end and friends are int UNIX seconds. Token.created_at / updated_at / launched_at / creation_time and ChatMessage.date are RFC-3339 strings. Convert either with from_unix() / parse_datetime().

All four pass None straight through, so nullable fields stay nullable.

⚠️ None is not 0

Several fields are nullable and their None means unknown, not zero — usually because an RPC read failed or an on-chain settlement has not been indexed yet. Rendering them as 0 is a correctness bug:

📚 API surface

All 28 endpoints are unauthenticated and read-only.

from fyuz import fyuz_address, chain_addresses, known_chains, BSC

fyuz_address(56)                 # '0x33a98bef6496684a8dac83734d9ceb0cefc7019c'
chain_addresses("bsc").rpc_url   # 'https://bsc-dataseed.bnbchain.org'
BSC.distributor                  # '0x2c88255f6a80296a3aa8c328e5ff308d74615c7b'
[c.network for c in known_chains()]

📄 Pagination

list_tokens() returns one page plus token_count. iter_tokens() walks every page lazily — pages are fetched on demand, so breaking out of the loop stops the requests:

for token in fyuz.iter_tokens(search_word="pepe", page_size=100):
    if token.graduated:
        print(token.token_symbol, token.pair_address)

Iteration ends at the first of: a page shorter than page_size, an empty page, token_count being reached, or max_pages (default MAX_ITER_PAGES = 10_000) requests. page_size is clamped to MAX_SERVER_PAGE_SIZE = 100, because the server clamps it too and every page would then look short.

💱 Trading — unsigned transactions only

client.trade builds unsigned bonding-curve transactions. It never sees a private key, never signs and never broadcasts — you hand {chainId, to, data, value} to web3.py, eth-account, a hardware signer or a multisig UI, and that library owns the key. That is also why this package still has zero runtime dependencies: signing is the part that needs a crypto library, and it is not here.

from fyuz import FyuzClient, format_units, parse_units

TOKEN = "0x42322852a918f94186b7dfda2e0e3f4ad3528480"

# The RPC /config publishes belongs to the API operator and is shared by every
# caller — pass your own for anything real.
with FyuzClient(rpc_url="https://bsc-dataseed.bnbchain.org") as fyuz:
    quote = fyuz.trade.quote_buy(TOKEN, parse_units("0.01"))     # 0.01 BNB
    print("tokens out ", format_units(quote.amount_out_wei))
    print("msg.value  ", format_units(quote.value_wei), "BNB")   # amount + first-buy fee
    print("impact     ", quote.price_impact_bps, "bps")

    # slippage_bps is required — there is no default, because the right
    # tolerance depends on the trade and a wrong one costs you money.
    built = fyuz.trade.build_buy(TOKEN, parse_units("0.01"), slippage_bps=100)
    print("to         ", built.transaction.to)
    print("chainId    ", built.transaction.chain_id)
    print("data       ", built.transaction.data[:74] + "...")
    print("minOut     ", format_units(built.limit_wei))

Real output, quoted against the live curve:

tokens out  1259164.617412410713942325
msg.value   0.01 BNB
impact      11 bps
to          0x33A98BeF6496684a8daC83734D9CEB0CEFC7019c
chainId     56
data        0x6bf05b0100000000000000000000000042322852a918f94186b7dfda2e0e3f4ad3528480...
minOut      1246572.971238286606802901

Then sign and send it yourself:

w3.eth.send_transaction(built.transaction.as_dict())   # your wallet, your key

Selling needs an ERC-20 approval first, because the contract pulls the tokens with transferFrom:

if fyuz.trade.allowance(TOKEN, owner) < amount_wei:
    approve = fyuz.trade.build_approve(TOKEN, amount_wei=amount_wei)
    w3.eth.send_transaction(approve.as_dict())

sell = fyuz.trade.build_sell(TOKEN, amount_wei, slippage_bps=150)

💸 Fees, and why msg.value is bigger than you asked for

transaction.value already includes getFirstBuyFee(token): the fee rides on top of the swap amount, so msg.value = amount_in + first_buy_fee. Sending only amount_in reverts with InsufficientEthValue(). Any excess is refunded by the contract.

The buy fee is PLATFORM_BUY_FEE_BPS (80) + TOKEN_OWNER_FEE_BPS (20) = 100 bps. Both are owner-settable storage variables, so the SDK reads them from the chain rather than assuming them.

A token that has graduated raises FyuzTokenGraduatedError instead of building a transaction that would revert.

🚨 Errors

from fyuz import FyuzClient, FyuzRateLimitError, FyuzNotFoundError, FyuzAPIError, FyuzError

with FyuzClient() as fyuz:
    try:
        profile = fyuz.get_user_profile("0xdead...")
    except FyuzNotFoundError:
        profile = None
    except FyuzRateLimitError as exc:          # 429, after retries were exhausted
        print("slow down", exc.retry_after)
    except FyuzAPIError as exc:                # any other non-2xx
        print(exc.status, exc.message)         # message from the {"error": ...} envelope
    except FyuzError:                          # transport / decode / argument failures
        raise

except FyuzError really does catch everything, including argument validation. Catch FyuzRateLimitError before FyuzAPIError, and FyuzTimeoutError before FyuzConnectionError — they are subclasses.

🔁 Rate limits and retries

The API rate-limits per client IP at 120 requests/minute and answers 429 with {"error": "Too many requests"}.

The client retries 429, 5xx and transport failures automatically, with exponential backoff and full jitter (sleep = uniform(0, min(cap, 0.25 * 2**n))). A Retry-After header, when present, raises the computed backoff — it can lengthen the wait but never shorten it, so Retry-After: 0 cannot spin the retries away — and is capped at 60s. It is honoured on a 503 from a draining load balancer just as much as on a 429. No other 4xx is ever retried.

FyuzClient(
    "https://api.fyuz.fun",
    timeout=30.0,          # seconds, per request
    max_retries=3,         # 0 disables retrying entirely
    backoff_initial=0.25,
    backoff_max=8.0,
    user_agent="my-indexer/1.0",   # default: fyuz-sdk-python/0.1.0
    headers={"X-Trace": "..."},    # extra headers on every API request
    rpc_url="https://my-node.example",   # for client.trade
)

timeout bounds one attempt, not the whole call: with retries the worst case is timeout * (max_retries + 1) plus backoff. Lower both to bound a call.

🧭 Notes for indexers and data partners

• GET /discover is the highest-signal single call: market cap, 24h volume, buy/sell counts, holders, price change and graduation progress per token.
• get_recent_trades(latest_trade_id=...) polls the platform-wide feed incrementally — pass back the highest Trade.id you have seen.
• rank on every leaderboard is a server-assigned 1-based ordinal in returned order. Do not re-sort client-side; the server's ordering is what the payout logic uses.
• Response models ignore unknown fields, so a server-side addition will never break a deployed client. Collection fields are tuples (the models are frozen); endpoints returning a bare JSON array give you a list.
• The client does not pool connections: urllib.request opens a fresh TCP connection and TLS handshake per call, where the Go, Rust and TypeScript clients reuse one. That is the price of the zero-dependency guarantee, and on a tight poll loop it is the dominant cost.

🧑‍🍳 Examples

Runnable programs in examples/:

PYTHONPATH=src python examples/01_quickstart.py
PYTHONPATH=src python examples/03_token_deep_dive.py 0x42322852a918f94186b7dfda2e0e3f4ad3528480
PYTHONPATH=src python examples/04_export_tokens.py dog > tokens.csv
BSC_RPC_URL=https://bsc-dataseed.bnbchain.org PYTHONPATH=src python examples/06_trade.py

(PYTHONPATH=src is only for running against a checkout; after pip install fyuz-sdk they run as-is.) The same six exist in the TypeScript, Go and Rust clients — see ../README.md.

🛠️ Development

Tests are stdlib unittest. There is no pytest, and nothing to install to run them.

cd sdk/python

# 177 hermetic tests against a local stub HTTP server, never the network.
# tests/ joins src/ on the path: the suite imports its stub server and payload
# fixtures as top-level modules.
PYTHONPATH=src:tests python -m unittest discover -s tests -t tests

# Type check (strict) and lint
pip install -e ".[dev]"
mypy
ruff check src tests examples
ruff format --check src tests examples

# Build the distributions
pip install build
python -m build

tests/test_conformance.py additionally reads ../shared/test-vectors from disk — the same fixtures drive the TypeScript, Go and Rust suites, so a change to the wire contract fails all four at once.

sdk/scripts/test-all.sh      # every SDK, offline
sdk/scripts/fork-test.sh     # fork BSC, run everything against the live contract

fork-test.sh spins up an anvil fork of BNB Smart Chain and points all four suites at the real deployed proxy. Each writes a conformance record; the four hash identically. Without FYUZ_FORK_RPC set, the fork tests skip and the suite stays offline and hermetic.

👨‍👩‍👧‍👦 The SDK family

Same API, same behaviour, four languages:

🔗 Links

• 🌐 Homepage — https://fyuz.fun
• 🔌 API — https://api.fyuz.fun
• 📦 Repository — https://github.com/fyuz-launchpad/fyuz-sdk

📜 License

MIT — see LICENSE.