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, 2 for V3 and 3 for V4 — direct launches, which skip the bonding curve entirely, also report 3, and are told apart by launched_at / graduated rather than by this field. The API types it as a plain integer with no enum, so treat the set as open and always handle an unrecognised value.

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.1
    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 python3 examples/01_quickstart.py
PYTHONPATH=src python3 examples/03_token_deep_dive.py 0x42322852a918f94186b7dfda2e0e3f4ad3528480
PYTHONPATH=src python3 examples/04_export_tokens.py dog > tokens.csv
BSC_RPC_URL=https://bsc-dataseed.bnbchain.org PYTHONPATH=src python3 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 python3 -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
python3 -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.

../scripts/test-all.sh      # every SDK, offline
../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, and the script flattens all four and compares them leaf field by leaf field — it prints all 4 SDKs agree on every field, or the exact divergence. 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.