neutrl-contracts

neutrl-contracts

Python SDK for interacting with Neutrl Protocol smart contracts. Provides typed, async-ready clients for NUSD minting/redeeming, sNUSD staking, and Router swaps.

Installation

pip install neutrl-contracts

Quick Start

Mint NUSD

from neutrl_contracts import NUSDClient, MintParams

client = NUSDClient(
    rpc_url="https://eth.llamarpc.com",
    nusd_address="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
    private_key="0x...",
)

# Preview mint
nusd_amount = client.preview_mint(
    collateral_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  # USDC
    amount=1_000_000_000,  # 1000 USDC (6 decimals)
)
print(f"Expected NUSD: {nusd_amount / 10**18:.2f}")

# Execute mint
result = client.mint(MintParams(
    collateral_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    collateral_amount=1_000_000_000,
    min_nusd_amount=int(nusd_amount * 0.995),
))
print(f"Minted {result.nusd_minted / 10**18:.2f} NUSD — TX: {result.tx_hash}")

Stake for sNUSD

from neutrl_contracts import StakingClient, StakeParams

staking = StakingClient(
    rpc_url="https://eth.llamarpc.com",
    snusd_address="0x08EFCC2F3e61185D0EA7F8830B3FEc9Bfa2EE313",
    nusd_address="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
    private_key="0x...",
)

# Check exchange rate
rate = staking.exchange_rate()
print(f"sNUSD/NUSD rate: {rate / 10**18:.6f}")

# Stake 1000 NUSD
staking.stake(StakeParams(nusd_amount=1000 * 10**18))

Router Swap

from neutrl_contracts import RouterClient, SwapParams

router = RouterClient(
    rpc_url="https://eth.llamarpc.com",
    router_address="0xa052883ebEe7354FC2Aa0f9c727E657FdeCa744a",
    private_key="0x...",
)

# Preview swap
amount_out, impact = router.get_amount_out(
    token_in="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",   # USDC
    token_out="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",    # NUSD
    amount_in=5_000_000_000,  # 5000 USDC
)
print(f"Output: {amount_out / 10**18:.2f} NUSD, impact: {impact} bps")

# Execute swap
result = router.swap(SwapParams(
    token_in="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    token_out="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
    amount_in=5_000_000_000,
    min_amount_out=int(amount_out * 0.995),
))
print(f"Swapped via route: {result.route}")

Async Usage

import asyncio
from neutrl_contracts import AsyncNUSDClient, MintParams

async def main():
    client = AsyncNUSDClient(
        rpc_url="wss://eth.llamarpc.com",
        nusd_address="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
        private_key="0x...",
    )

    supply = await client.total_supply()
    print(f"NUSD supply: {supply / 10**18:,.2f}")

    result = await client.mint(MintParams(
        collateral_address="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        collateral_amount=500_000_000,
    ))
    print(f"Async mint TX: {result.tx_hash}")

asyncio.run(main())

Event Listening

from neutrl_contracts import EventListener

listener = EventListener(
    rpc_url="https://eth.llamarpc.com",
    contract_address="0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE",
    contract_type="nusd",
    from_block=20_000_000,
)

listener.on("Minted", lambda e: print(f"Mint: {e.args['nusdAmount'] / 10**18:.2f} NUSD"))
listener.on("Redeemed", lambda e: print(f"Redeem: {e.args['nusdAmount'] / 10**18:.2f} NUSD"))

listener.poll_loop()

Contract Registry

from web3 import Web3
from neutrl_contracts import ContractRegistry

registry = ContractRegistry()

# Known deployments are auto-loaded
nusd = registry.get("nusd")
print(f"NUSD: {nusd.address}")

# Get a web3 contract instance
w3 = Web3(Web3.HTTPProvider("https://eth.llamarpc.com"))
contract = registry.get_contract(w3, "nusd")
supply = contract.functions.totalSupply().call()

API Reference

Clients

Client	Description
NUSDClient / AsyncNUSDClient	NUSD mint, redeem, balance, supply
RouterClient / AsyncRouterClient	Token swaps with route optimization
StakingClient / AsyncStakingClient	sNUSD stake, unstake, cooldown
EventListener / AsyncEventListener	Event polling and callbacks
ContractRegistry	Multi-chain deployment management

Contract Addresses (Ethereum Mainnet)

Contract	Address
NUSD	0xE556ABa6fe6036275Ec1f87eda296BE72C811BCE
sNUSD	0x08EFCC2F3e61185D0EA7F8830B3FEc9Bfa2EE313
Router	0xa052883ebEe7354FC2Aa0f9c727E657FdeCa744a

Requirements

• Python 3.9+
• web3.py >= 6.0

License

MIT