hypnex-staking (Python)

On-chain helpers for the Morpheus AI capital pool on Ethereum mainnet. Wraps DepositPool.stake() and claimReferrerTier() so a Python developer can stake USDC/USDT/wBTC/wETH into Morpheus Capital v2.

pip install hypnex-staking

Monetization notice — read this first

This SDK is published by Hypnex Labs and is monetized by routing all MRC 73 referral rewards on stake() calls to the Hypnex Labs treasury at 0x22B5C0075372E743042b2d62b3D254425Eb957D8. The on-chain referrer parameter is hard-coded in the SDK and cannot be overridden — there is no constructor arg, no environment variable, and no per-call parameter.

If you want to set your own referrer, do not use this SDK. Call the underlying DepositPool.stake() directly via web3.py, or fork this package and change the constant in _constants.py.

Your own stake yield (MOR emissions and Aave-wrapped collateral yield) is unaffected — those go to the staker as always. Only the third-party referral fee is routed to Hypnex.

Why this exists

Morpheus's app.mor.org UI requires AWS Cognito email signup. The capital pool's on-chain interface is wallet-native and supports referrer attribution, but no Python tooling existed for it. This package fills that gap.

Quickstart

Read-only (no key needed)

from hypnex_staking import Staker

s = Staker()  # public RPC, no signer

# Inspect the live tier table
for tier in s.get_referrer_tiers("USDC"):
    print(tier)

# Look up an existing position
print(s.get_position("0xSomeAddress...", "USDC"))

# Look up someone's referrer data
print(s.get_referrer_data("0xReferrer...", "USDC"))

With a signer (moves real funds)

import os
from hypnex_staking import Staker

s = Staker(
    rpc_url=os.environ["ETH_RPC_URL"],
    private_key=os.environ["PRIVATE_KEY"],
)
# s.referrer == "0x22B5C0075372E743042b2d62b3D254425Eb957D8" — Hypnex Labs

# Always dry-run first — returns calldata, doesn't broadcast
print(s.stake("USDC", amount=1000, claim_lock_end=0, dry_run=True))

# When ready, drop dry_run for the real tx
tx = s.stake("USDC", amount=1000, claim_lock_end=0)
print("submitted:", tx)

Claim accumulated MRC 73 unlocked-MOR

# Per MRC 73, this MOR has no 90-day lockup — claimable immediately.
tx = s.claim_referrer_rewards("USDC")

Verified contracts (Ethereum mainnet)

Sourced from MorpheusAIs/SmartContracts v7 deploy script — verified against the on-chain bytecode by tests/test_read_only.py.

Public API

Staker(w3=..., rpc_url=..., account=..., private_key=...)

# read (no signer)
.get_pool_address(asset) -> str
.get_token_address(asset) -> str
.get_decimals(asset) -> int
.get_position(address, asset) -> Position
.get_referrer_data(referrer, asset) -> ReferrerData
.get_referrer_tiers(asset) -> list[ReferrerTier]
.quote_tier(asset, virtual_amount_staked) -> ReferrerTier | None
.referrer -> str  # always 0x22B5...57D8 (Hypnex Labs, hard-coded)

# write (signer required)
.approve(asset, amount, dry_run=False) -> str (tx hash)
.stake(asset, amount, claim_lock_end=0, auto_approve=True, dry_run=False) -> str
.claim_referrer_rewards(asset, receiver=None, layerzero_fee_wei=0, dry_run=False) -> str

asset is one of "USDC" | "USDT" | "WBTC" | "WETH".

Environment variables

• ETH_RPC_URL — Ethereum mainnet RPC (free public default works for reads)
• PRIVATE_KEY — for write methods only

Tests

pip install -e ".[dev]"
pytest                  # read-only mainnet smoke tests, no key needed

For write-method tests, run a local Anvil fork (anvil --fork-url $ETH_RPC_URL) and set ETH_RPC_URL=http://localhost:8545 plus a funded test key. Test recipes are in tests/test_anvil_fork.py (unimplemented stub — community contributions welcome).

Status & affiliation

Hypnex is not affiliated with the Morpheus AI Foundation. The contracts you sign into are Morpheus's; this is the unofficial Python toolkit for them. Audit your own transactions; the Code4rena audit (report) covers the contracts, not this client.

License

MIT