melaya (Python SDK)

Current production scope: Agent Builder and Mobile Device Control are available now. Melaya Trading namespaces are preview-only and not generally available; do not use them with real funds.

Official SDK for the Melaya Agent Builder and flagship Mobile Device Control APIs. Trading namespaces are included only as a preview of a later product.

Install

pip install melaya            # REST
pip install "melaya[stream]"  # REST + WebSocket streaming

Quick start: Agent Builder & Device Control

Pair an Android phone, then create and run an agent pipeline that operates it. Configure provider credentials through Melaya Connectors first — never put a provider key in pipeline configuration or per-run overrides.

from melaya import Melaya

m = Melaya(api_key="mk_...")  # keys are prefixed `mk_`

# 1. Pair a phone — enter the code in the Melaya APK
pairing = m.agents.phone.pair()
print(pairing["code"])

devices = m.agents.phone.list_devices()
apps = m.agents.phone.list_apps()
m.agents.phone.set_allowed_apps(["com.android.chrome"])

# 2. Create an agent pipeline with a minimal tool allowlist
m.agents.pipelines.create(
    name="mobile-review",
    project="Operations",
    model_provider="anthropic",
    model_name="claude-sonnet-4-6",
    agents=[{
        "name": "mobile-operator",
        "role": "Careful mobile operator",
        "instruction": "Read before acting. Never send, publish, or delete.",
        "agent_tools": [
            "phone_get_screen_tree", "phone_current_app", "phone_open_app",
            "phone_click_text", "phone_back", "phone_wait",
        ],
    }],
    steps=[{"kind": "agent", "agent": {"name": "mobile-operator"}}],
    maxCostUsd=1.00,
)

# 3. Run it and attach the run to the paired phone
run = m.agents.pipelines.run("mobile-review", project="Operations")
run_id = run["run_id"]
m.agents.phone.register_active_run(run_id)

status = m.agents.pipelines.run_status("mobile-review", run_id)
print(status["status"])

Real-time run updates arrive over Socket.IO (async):

import asyncio
from melaya import Melaya

async def main():
    m = Melaya(api_key="mk_...")
    await m.events.connect()
    m.events.on_run_update(run_id, lambda e: print(e["event_type"]))
    await m.events.wait_closed()

asyncio.run(main())

Market data quick start (preview)

from melaya import Melaya

m = Melaya(api_key="mk_...")

# Normalized ticker from any of 70+ venues
t = m.market.ticker(exchange="binance", symbol="BTC/USDT", market="spot")
print(t["last"], t["bid"], t["ask"])

# Order book + candles
book = m.market.orderbook(exchange="bybit", symbol="BTC/USDT", market="spot", limit=20)
candles = m.market.ohlcv(exchange="okx", symbol="ETH/USDT", timeframe="1h", limit=200)

Streaming (async, preview)

import asyncio
from melaya import Melaya

async def main():
    m = Melaya(api_key="mk_...")
    async for t in m.stream.ticker(exchange="binance", symbol="BTC/USDT", market="spot"):
        print(t["last"])

asyncio.run(main())

Trading (preview — not for real funds)

The same client covers your account, paper trading, live strategies, and backtests. Reads need only your mk_ key; live order placement needs a connected exchange key (m.account.keys()).

# Account
keys = m.account.keys()            # [{"apiKeyId": "BINANCEUSDM_0", "exchange": ..., "market": ...}]
usage = m.account.usage()

# Strategies — create() launches immediately. Paper (dry_run) needs no exchange key.
# SDK-launchable strategies are `custom` Rhai definitions (an `evaluate()` that
# emits signals: emit_long / emit_short / emit_close).
res = m.strategies.create(
    name="My first bot", strategy_type="custom",
    exchange="binanceusdm", symbol="BTC/USDT:USDT", market="FUTURES", dry_run=True,
    params={"language": "rhai",
            "definition": 'fn evaluate() { emit_long(param("qty")); }',
            "qty": 0.001},   # dry_run=False + api_key_id places real orders
)
sid = res["strategyId"]
m.strategies.pause(sid)
m.strategies.resume(sid)
trades = m.strategies.trades(sid)

# Paper trading (sim broker) — synthetic fills, no venue state
bal = m.sim.balance(strategy_id=sid)
fill = m.sim.create_order(strategy_id=sid, exchange="binanceusdm",
                          symbol="BTC/USDT:USDT", side="buy", type="market",
                          amount=0.001, market="FUTURES")

# Backtest on the Rust engine
import time
start = m.backtest.start({"strategyType": "custom", "exchange": "binance",
                          "symbol": "BTC/USDT", "timeframe": "1h", "language": "rhai",
                          "definition": 'fn evaluate() { emit_long(param("qty")); }',
                          "params": {"qty": 0.001}})
job_id = start["job_id"]
while m.backtest.job(job_id)["status"] not in ("done", "error"):
    time.sleep(2)
result = m.backtest.results(job_id)   # metrics, equity_curve, ohlcv

# Live private strategy feed (async; a fresh ticket is minted per connection)
async for ev in m.stream.strategies():
    print(ev["type"], ev.get("strategyId"))

Authentication

Create an API key in the dashboard (melaya.org → Settings → API Keys). Keys are prefixed mk_. On REST calls the SDK sends the key only as an Authorization: Bearer mk_... header — never in a query string. Public WebSocket market-data streams pass the key as an ?apiKey= query parameter in the wss:// URL (server protocol); private WebSocket streams never expose the key — they use a short-lived, one-shot ?wsTicket= minted fresh for every connection. Public market-data and account/strategy reads work with the key alone. Live order placement and live strategy launches additionally require a connected exchange key — connect one in Settings → Connectors, then reference it by api_key_id. Paper trading and backtesting never touch a venue and need no exchange credentials.

API surface

Generally available

Trading preview (not for real funds)

Full docs: melaya.org/docs.

License

Apache-2.0