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.

Melaya products: Melaya Agents · Melaya Assistant · Device Control · Browser Control · MCP Server · Melaya Marketing

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. The run is generated ONLY from `steps` — each
#    agent step carries its full definition inline (there is no top-level
#    `agents` list, and no `prompt` field: use `instruction` + `model`).
m.agents.pipelines.create(
    name="mobile-review",
    project="Operations",
    steps=[{
        "kind": "agent",
        "agent": {
            "name": "mobile-operator",
            "role": "Careful mobile operator",
            "instruction": "Read before acting. Never send, publish, or delete.",
            "model": {"provider": "anthropic", "name": "claude-sonnet-4-6"},
            "agent_tools": [
                "phone_get_screen_tree", "phone_current_app", "phone_open_app",
                "phone_click_text", "phone_back", "phone_wait",
            ],
            "human_approval_tools": [],
        },
    }],
    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"])

Other config fields worth knowing: hitl_mode ("safe" default | "autonomous" | "payments_only" — only "safe" honours each agent's human_approval_tools), connector_source ("personal" | "project"), force_local_runner, and inputs (declares the fields run(run_inputs=...) populates). get() returns an envelope {name, client, config, code, docs} — edit envelope["config"] and pass that to update():

envelope = m.agents.pipelines.get("mobile-review", project="Operations")
envelope["config"]["steps"][0]["agent"]["model"] = {"provider": "anthropic", "name": "claude-opus-4-8"}
m.agents.pipelines.update("mobile-review", config=envelope["config"], project="Operations")

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())

Connector tools

Call a connected service's tools directly — the same surface the MCP server exposes to models: discover what's available, then call one.

from melaya import Melaya

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

m.agents.connector_tools.services()                 # {"services": [...], "toolCounts": {...}}
tools = m.agents.connector_tools.search("unread email")
m.agents.connector_tools.describe("gmail_list_messages")

# Reads run immediately.
result = m.agents.connector_tools.call("gmail_list_messages", {"max_results": 5})

# Writes default to an approval card in the Melaya app (`approval="required"`);
# `call_and_wait` blocks and polls until the user decides (or timeout).
outcome = m.agents.connector_tools.call_and_wait(
    "gmail_send", {"to": "a@b.c", "subject": "Hi", "body": "..."},
)
print(outcome["status"])  # "done" | "rejected" | "expired"

# approval="none" runs a write immediately (still audit-logged); tools that
# move money or trade are refused under BOTH approval modes.
m.agents.connector_tools.call("slack_post_message", {"channel": "#eng", "text": "shipped"}, approval="none")

Flat alias: m.connector_tools (same instance as m.agents.connector_tools).

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/documentation.

License

Apache-2.0