zero-network

Python SDK for the Zero Network — stablecoin microtransactions for AI agents.

1 Z = $0.01 USD | Ed25519 signatures | 136-byte transactions | x402 support

Install

pip install zero-network

For x402 server-side gating (requires Starlette/FastAPI):

pip install zero-network[x402]

Quick Start

fromzero_networkimportWallet# Create a new walletwallet=Wallet.create()
print(wallet.address) # hex-encoded public keyprint(wallet.seed_hex) # save this! needed to restore# Restore from seedwallet=Wallet.from_seed("your_64char_hex_seed")
# Or from ZERO_KEY environment variablewallet=Wallet.from_env()
# Request testnet fundswallet.faucet()
# Check balanceprint(wallet.balance(), "Z")
# Send 0.50 Z to another addresswallet.send("recipient_pubkey_hex_64chars", 0.5)
# Transaction historyfortxinwallet.history(limit=5):
print(tx)

Async Usage

All wallet methods have async variants prefixed with a:

importasynciofromzero_networkimportWalletasyncdefmain():
wallet=Wallet.create()
awaitwallet.afaucet()
balance=awaitwallet.abalance()
print(f"{balance} Z")
awaitwallet.asend("recipient_pubkey_hex", 1.0)
awaitwallet.aclose()
asyncio.run(main())

x402 Auto-Paying Client

Fetch paywalled resources with automatic micropayment:

fromzero_networkimportWalletfromzero_network.x402importx402_fetchwallet=Wallet.from_env()
response=x402_fetch("https://api.example.com/premium", wallet, max_price_z=0.10)
print(response.json())

If the server returns 402 Payment Required with a JSON body containing {"address": "...", "amount": 0.05}, the SDK pays automatically and retries.

x402 Server-Side Gating

Gate FastAPI/Starlette endpoints behind a paywall:

fromfastapiimportFastAPI, Requestfromzero_network.x402importx402_gateapp=FastAPI()
@app.get("/premium")@x402_gate(0.05, recipient_address="your_pubkey_hex")asyncdefpremium(request: Request):
return {"data": "premium content"}

Low-Level Client

fromzero_networkimportZeroClientclient=ZeroClient()
print(client.status())
print(client.balance("pubkey_hex"))
print(client.account("pubkey_hex"))

API Reference

Wallet

Method	Description
Wallet.create()	Generate new Ed25519 keypair
Wallet.from_seed(hex)	Restore from 32-byte hex seed
Wallet.from_env(var="ZERO_KEY")	Restore from environment variable
wallet.address	Hex-encoded public key
wallet.seed_hex	Hex-encoded seed (keep secret!)
wallet.balance() / abalance()	Query balance in Z
wallet.send(to, amount_z) / asend()	Send Z (auto nonce + sign)
wallet.account() / aaccount()	Full account state
wallet.history(limit) / ahistory()	Transaction history
wallet.faucet() / afaucet()	Request testnet funds

ZeroClient

Method	Description
client.status() / astatus()	Network status
client.balance(pubkey) / abalance()	Account balance
client.account(pubkey) / aaccount()	Account state
client.history(pubkey, limit) / ahistory()	Transaction history
client.send(...) / asend()	Submit signed transaction
client.faucet(address) / afaucet()	Request testnet funds

Transaction Helpers

Function	Description
build_transfer(from_pub, to_pub, amount, nonce)	Build unsigned 72-byte tx
sign_transfer(unsigned_tx, signing_key)	Sign and return 136-byte tx
parse_transfer(tx_bytes)	Parse 136-byte tx into Transfer

Constants

Constant	Value	Description
UNITS_PER_Z	100	Internal units per 1 Z
FEE_UNITS	1	Flat transfer fee (0.01 Z)
BRIDGE_OUT_FEE_UNITS	50	Bridge-out fee (0.5 Z)
MAX_TRANSFER_UNITS	2500	Max transfer (25 Z)
DEFAULT_RPC	https://rpc.zzero.net	Default RPC endpoint
TESTNET_FAUCET	http://157.180.56.48:8093	Testnet faucet

Network Details

• Denomination: 1 Z = $0.01 USD = 100 internal units
• Transfer fee: 0.01 Z (1 unit) flat per transaction
• Bridge-out fee: 0.5 Z (50 units) per withdrawal
• Max transfer: 25 Z (2500 units)
• Account creation: 1.00 Z deducted on first receive
• Signatures: Ed25519 (compatible with tweetnacl/dalek)
• Hashing: BLAKE3
• Transaction size: 136 bytes

License

MIT