Abyss Python SDK

Launch tokens, read pools, swap, and use lending with web3.py. Package 0.15.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.15.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. Multi-market and conversion-funded plans use staged execution. Release-owned capacity budgets must fit the native ceiling; unavailable budgets refuse without a simulation fallback. See prepare and assess.

Choose an offering

Auto-compounding presets and codecs are available, but planning currently refuses them with UNKNOWN_GAS_PROFILE because they lack a reviewed capacity budget.

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.