Python SDK

The official Merx Python client. Requires Python 3.9+. Zero external dependencies - uses only the standard library for HTTP and JSON.

Installation

pipbash
pip install merx-sdk

Initialization

Setuppython
from merx import MerxClient

client = MerxClient(api_key="sk_live_your_key_here")

# Optional: override base URL for testing
# client = MerxClient(
#     api_key="sk_live_your_key_here",
#     base_url="https://staging.merx.exchange",
# )

Prices

Query live energy prices across all providers. The prices endpoint is public and does not require authentication.

Prices modulepython
# All provider prices
prices = client.prices.list()

# Cheapest price for given params
best = client.prices.best(
    resource_type="ENERGY",
    amount=65000,
    duration_sec=86400,
)

# Historical price data
history = client.prices.history(provider="catfee", hours=24)

# Aggregated statistics
stats = client.prices.stats()

# Preview order cost without placing it
preview = client.prices.preview(
    resource_type="ENERGY",
    amount=65000,
    duration_sec=86400,
)

Orders

Create and manage energy and bandwidth orders. All order endpoints require authentication.

Orders modulepython
# Place an order
order = client.orders.create(
    resource_type="ENERGY",
    amount=65000,
    duration_sec=86400,
    target_address="TYourTargetAddressHere",
)

# List orders with optional filters
orders = client.orders.list(status="FILLED", limit=20)

# Get a specific order by ID
detail = client.orders.get("ord_abc123")

Balance

Balance modulepython
# Current balances
balance = client.balance.get()

# Deposit address and instructions
deposit = client.balance.deposit_info()

# Withdraw TRX (amount in SUN)
withdrawal = client.balance.withdraw(
    amount=1000000,
    to_address="TYourWithdrawAddress",
)

# Transaction history
history = client.balance.history(limit=50)

# Balance summary with totals
summary = client.balance.summary()

Webhooks

Webhooks modulepython
# Register a webhook endpoint
webhook = client.webhooks.create(
    url="https://example.com/webhooks/merx",
    events=["order.filled", "deposit.received"],
)

# List all registered webhooks
webhooks = client.webhooks.list()

# Delete a webhook
client.webhooks.delete("wh_abc123")

Error Handling

All SDK methods raise MerxError on failure. The exception includes a machine-readable code, a human-readable message, and the HTTP status.

Error handlingpython
from merx import MerxClient, MerxError

try:
    order = client.orders.create(...)
except MerxError as e:
    print(e.code)     # e.g. "INSUFFICIENT_BALANCE"
    print(e.message)  # human-readable description
    print(e.status)   # HTTP status code
    print(e.details)  # additional context, if any
INFO

The Python SDK has zero external dependencies. It uses urllib.request from the standard library for all HTTP requests.

All Methods

MethodDescription
prices.list()All provider prices
prices.best(**params)Cheapest available price
prices.history(**params)Historical price data
prices.stats()Aggregated price statistics
prices.preview(**params)Preview order cost
orders.create(**params)Place an order
orders.list(**filters)List orders
orders.get(id)Get order by ID
balance.get()Current balances
balance.deposit_info()Deposit address
balance.withdraw(**params)Withdraw TRX
balance.history(**params)Transaction history
balance.summary()Balance summary
webhooks.create(**params)Register webhook
webhooks.list()List webhooks
webhooks.delete(id)Delete webhook