Black Market Python SDK

Discover launch offerings, prepare explicit token-launch plans, and work with Abyss DEX and lending contracts. Built on web3.py for Python 3.10+. Imports never sign, send transactions, or publish metadata.

Install

python -m pip install black-market-sdk

For the examples and tests in this checkout:

python -m pip install -e ".[dev]"

Read-only quickstart

This is a complete mainnet example: no wallet, private key, or plan file needed. It reads the live registry, including admission status and configuration topology.

from web3 import Web3
from black_market_sdk import (
    ROBINHOOD_MAINNET_RPC, get_addresses, get_launch_addresses,
    read_lifecycle_profiles,
)

chain_id = 4663
client = Web3(Web3.HTTPProvider(ROBINHOOD_MAINNET_RPC))
assert client.eth.chain_id == chain_id
launch = get_launch_addresses(chain_id)
print("orchestrator:", launch.orchestrator)
print("lending pool:", get_addresses(chain_id).lending_pool)

for profile in read_lifecycle_profiles(
    client, orchestrator=launch.orchestrator, offset=0, limit=100
):
    print(profile.id, profile.venue_kind, profile.admitted, profile.reason)

Or run python examples/quickstart.py / python examples/launch_matrix.py. Both default to read-only Robinhood mainnet discovery.

Launch workflow

1. Discover a live admitted profile and inspect its bounds and developer terms.
2. Build a complete LaunchPlanV1: explicitly choose chain, orchestrator, creator, nonce, deadline, token, funding, fees, markets, and opening buys.
3. Finalize pool-bound hook salts with prepare_pool_bound_lifecycle_plan and review the resulting hash_launch_plan before any submission.
4. Use plan_launch with explicit execution mode and observed gas/calldata caps. build_next_transaction emits only a proven unsigned next step.
5. Your wallet submits each chosen transaction. Recover from actual receipts with read_launch_progress; revalidate before another step.

The deployed mainnet launcher offers pool-bound V4/config5 and canonical Abyss/config1. Staged preparation still ends in one indivisible activation. The SDK does not silently change fees, funding, execution mode, or plan identity.

See the launch guide for configuration layouts, runnable CLI commands, simulation requirements, recovery, author fees, and metadata API usage.

Networks and configuration

Select get_addresses(4663) explicitly: get_addresses() defaults to workbench. get_launch_addresses(chain_id) requires a chain and raises for unconfigured launch chains. Plans and EIP-712 builders always require their own orchestrator.

Current mainnet launch addresses:

• Orchestrator: 0xb75CBD17b9aecb7305B4DFcDa69595F783341c0E
• Registry: 0xaa8a410709B79cBA6F118F1be1FF568877A3B8Ee
• Fee-owner registry: 0x15778Aad08e12D458B2848F035860e2a8c2a0725

DEX fee tiers, pool/router/position ABIs, TickMath, lending clients, reserve/user normalization, and exact RAY/WAD helpers are also exported at the package root. Override precedence and the full deployment view are documented in the guide.

Individually runnable token-launch smoke

examples/smoke_launch.py consumes the owned local fork fixture and runs one of eight ERC20/ERC404, reward, burn, V4/Abyss cases at a time. --list is offline; the default only prepares a plan. --execute enables real token creation and API publication, or explicitly partial --chain-only proof. No production key is used. Each fresh --output retains redacted diagnostics and submitted hashes even on failure; private session recovery is mode 0600. See the runner commands and artifacts.

Tests and real HTTP API integration

# Local unit suite: no RPC, API service, wallet, or key required.
python -m pytest -q

# Opt-in GET-only API checks against your running real test service.
export LAUNCH_API_TEST_URL=http://127.0.0.1:18763
export LAUNCH_API_TEST_CHAIN_ID=4663
export LAUNCH_API_TEST_ORCHESTRATOR=0xb75CBD17b9aecb7305B4DFcDa69595F783341c0E
python -m pytest -q tests/test_launch_api_http.py -m 'launch_api_http and not launch_api_write'

# Explicit signed metadata-session suite; supply a disposable test wallet key.
: "${LAUNCH_API_TEST_PRIVATE_KEY:?Set the disposable test wallet private key}"
python -m pytest -q tests/test_launch_api_http.py -m launch_api_http

# Real API example: read-only by default; no injected or simulated transport.
python examples/launch_api_lifecycle.py
# Opt-in signed creation; protects the one-time capability in a mode-0600 file.
python examples/launch_api_lifecycle.py --signed --state-file launch-session.private.json

The test API must run the actual launch router and session database, with chain 4663 and the current orchestrator as its authorization verifying contract. API clients require HTTPS by default; the test suite/example explicitly enable allow_loopback_http=True for local HTTP only. Image uploads still require HTTPS. Signed tests/examples refuse non-loopback endpoints. The metadata-only suite needs no image store, indexed launch, funded wallet, or chain writes. Explicitly selected suites fail on missing service/key prerequisites; default pytest excludes HTTP. See the guide for service requirements and what these tests cover.

License

MIT