Abyss Python SDK

Launch tokens, read pools, swap, and use lending with web3.py. Package 0.16.1, Python 3.10+, import black_market_sdk. The launch examples target Robinhood Chain mainnet (4663).

Install

Install the published package in your Python environment:

python -m pip install black-market-sdk==0.16.1

For the runnable examples, install an editable checkout:

git clone https://github.com/abysshopper/black-market-python-sdk.git
cd black-market-python-sdk
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

Discover without a wallet

python examples/quickstart.py
python examples/launch_matrix.py

These optional audits read profile IDs, venues, admission, and refusal reasons. Use list_known_lifecycle_profiles for the shipped zero-RPC offering catalog; new registrations appear there when the SDK release is updated.

Run your first launch

Start with launch_erc20_abyss.py: one ERC20, one canonical Abyss pool, one permanent position, and one opening buy, atomically.

cp -n examples/.env.example .env
chmod 600 .env

Set LAUNCH_API_URL=https://api.abyss.trading and exactly one key source: PRIVATE_KEY, or EXAMPLE_KEYSTORE_PATH with EXAMPLE_KEYSTORE_PASSWORD if needed. Fund that creator with ETH for the buy and gas. RPC_URL optionally overrides the official mainnet RPC. Process environment values override .env.

# Dry run: discovery, pricing and admission; no signatures or writes.
python examples/launch_erc20_abyss.py
# Authorizes spending and publication, without an interactive prompt.
python examples/launch_erc20_abyss.py --broadcast
# After partial execution, use the ORIGINAL broadcast run directory.
python examples/launch_erc20_abyss.py --resume "launch-results/<original-run>"

Even a dry run needs the creator key, sufficient funds, and live RPC/API access. Review the full supply, aligned starting valuation, fees, buy output/share, minimum output, and gas before broadcasting. --broadcast builds a fresh plan, not the dry-run plan. --resume retains the original identity, plan, receipts, and session. Keep recovery files private; never commit keys, capabilities, or signed bytes.

Understand the defaults

• ERC20 supply: 1,000,000 tokens; ERC404 supply: 10,000, with 100-token NFT units.
• EXAMPLE_TARGET_MARKET_CAP_USD=5000: full minted-supply valuation, not cash raised. At 1M tokens, that is $0.005/token before tick rounding. It is not a recommendation.
• EXAMPLE_BUY_AMOUNT_WEI=10000000000000: 0.00001 ETH per buy, plus gas. WETH funding wraps ETH; USDG funding uses a Kyber conversion.
• Abyss fee: 3000 pips (0.3%), spacing 60. Fixed V4 examples add a 1% hook fee to their 0.3% LP fee. Their config6 minimum does not select dynamic behavior.
• Reward examples allocate 40% of distributed fees to rewards and 60% to the owner. The 275 bps collection reward is a fee-distribution share, not a trader tax.
• Launch commands reserve the preset's 32M total gas on Robinhood, including poster gas. Profiles select mode, never signing-gas size. An atomic preference can select staged execution; review the returned launch.mode.
• Approvals leave gas/fee preparation to the wallet. Held launch gas must match the native ceiling, and held prices below the pinned fee floor refuse without a bump.

Examples

All eleven cases use launch_examples.py and _launch_support.py. Counts below are markets / positions / ordered buys.

Planning never executes launch calldata, including conversion routes. A known single-market plan can use atomic execution, including conversion funding, when its padded compute budget plus poster allocation fits the native ceiling. Multi-market plans remain staged; unavailable budgets refuse without a simulation fallback. See prepare and assess.

Choose an offering

Raeto and auto-compounding use the robinhood-4663-capacity-v5 budget model, retaining reviewed template coefficients and adding an empirical conversion reserve. Launch commands still reserve the native 32M total gas ceiling.

Integrate and recover

Follow the launch guide for pricing, signing, publication, recovery, and claims. Check receipt confirmed → markets active → metadata published → API indexed separately; an API timeout does not undo an open token.

Release-owned openings use versioned capacity budgets and exact ordered local buy math. launch.assessment reports readiness and actionable refusals, not execution proof. build_next_transaction refreshes only the immediate command. The wallet assigns its transaction nonce; LaunchPlanV1.nonce remains launch identity.

See runner configuration, limits and codecs, release changes, and the MIT license.