black-market-sdk

Canonical Python SDK for the Black Market protocol on Robinhood Chain — Abyss DEX infrastructure, Atomic token launches, and the lending market.

Built on web3.py. Python 3.10+. Mirrors the TypeScript SDK (@black-market/sdk).

Install

pip install black-market-sdk

Quick start

from black_market_sdk import create_protocol_web3, get_addresses, ROBINHOOD_MAINNET_CHAIN_ID

w3 = create_protocol_web3(chain_id=ROBINHOOD_MAINNET_CHAIN_ID)
addresses = get_addresses(ROBINHOOD_MAINNET_CHAIN_ID)  # canonical mainnet deployment
# get_addresses() defaults to the workbench fork (46631); pass the chain id explicitly.

Wallet client (signing)

import os

from black_market_sdk import create_protocol_wallet_web3

w3, account = create_protocol_wallet_web3(
    private_key=os.environ["PRIVATE_KEY"],
    chain_id=4663,
)

Atomic launches

from black_market_sdk import (
    AtomicLaunchPoolRecipeInput,
    build_atomic_launch_calldata,
    derive_atomic_launch_pool_recipe,
    estimate_atomic_launch_initial_buy,
)

# Derive the one-sided launch position from a target FDV.
recipe = derive_atomic_launch_pool_recipe(
    AtomicLaunchPoolRecipeInput(
        paired_token_decimals=18,
        paired_token_usd_price_x18=2_500 * 10**18,
        target_market_cap_usd_x18=5_000 * 10**18,
        launched_token_is_quote=False,
        fee=3_000,
    )
)

# Validate a request and encode deployAndLaunch calldata.
calldata = build_atomic_launch_calldata(request, native_buy_amount=0)

Networks

get_addresses() defaults to workbench chain 46631; pass 4663 for canonical mainnet or 31337 for Anvil. Overrides are read once at module import. Launch addresses accept bare, VITE_, then NEXT_PUBLIC_ keys on every chain. Abyss infrastructure overrides apply only to 31337 and 46631; mainnet Abyss addresses remain canonical. Lending overrides apply to 31337 with all three forms and to 46631 with VITE_/NEXT_PUBLIC_ only. LIQUIDATION_EXECUTOR is additionally overridable on mainnet.

Package layout

Examples

Examples never sign or broadcast transactions. quickstart.py builds a fresh launch request offline; launch_recipe.py focuses on pricing math; and abby_launch.py reconstructs the successful Abby mainnet launch byte-for-byte.

python examples/quickstart.py
python examples/launch_recipe.py
python examples/abby_launch.py

Development

pip install -e ".[dev]"
pytest

Releasing

Releases are published to PyPI from GitHub Actions with trusted publishing (OIDC) — no API tokens or passwords are stored in this repository.

1. Bump version in pyproject.toml and commit.
2. Cut a matching git tag (for example, v0.1.0) and create a GitHub Release from it.
3. The publish workflow runs on the release published event, verifies the tag matches pyproject.toml, builds and checks the sdist and wheel, then uploads them to PyPI via OIDC. It can also be run manually with an explicit version input.

The publish job declares environment: pypi. Configure the pypi environment in the repository settings (required reviewers, allowed branches/tags) so a human approves every release, and register the workflow as a trusted publisher in the PyPI project settings.

License

MIT