Melaya.SDK 0.4.0

Melaya .NET 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. Normalized market data, paper/live strategies, backtesting, and WebSocket streaming across 70+ venues — with zero external NuGet dependencies.

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

Installation

<PackageReference Include="Melaya.SDK" Version="0.3.0" />

Or reference the project directly during development:

<ProjectReference Include="../sdk-csharp/Melaya/Melaya.csproj" />

Authentication

Every Melaya API key is prefixed mk_. Create one at melaya.org → Settings → API Keys. On REST requests the SDK sends the key only as an Authorization: Bearer mk_… header — never in the query string. Public WebSocket market streams authenticate with an ?apiKey= query parameter on the wss:// URL (the server's protocol for public feeds); private WebSocket streams never carry the key — they use a short-lived ?wsTicket= minted over REST.

Never commit your key. Read it from an environment variable:

var mk = Environment.GetEnvironmentVariable("MK")
    ?? throw new InvalidOperationException("MK env var not set");

Quick start: Agent Builder & Device Control

The generally available surface. Pair an Android phone, then let a pipeline agent operate approved apps through the visible interface.

using Melaya;

var mk = Environment.GetEnvironmentVariable("MK")!;
await using var m = new MelayaClient(new MelayaOptions { ApiKey = mk });

// 1. Pair a phone — enter the code in the Melaya mobile app
var pair = await m.Phone.PairAsync();
Console.WriteLine($"Pair code: {pair.Code} (expires in {pair.ExpiresInSeconds}s)");

var devices = await m.Phone.ListDevicesAsync();
var apps    = await m.Phone.ListAppsAsync();

// Give the agent the smallest practical app allowlist
await m.Phone.SetAllowedAppsAsync(new[] { "com.android.chrome" });

Configure provider credentials through Melaya Connectors first. Never include a provider key in pipeline configuration or per-run overrides.

using System.Text.Json;

// 2. Create a pipeline (extra config fields go through Config extension data).
//
//    The run is generated ONLY from `steps` — a top-level `agents` array by itself
//    produces an EMPTY pipeline. Each step embeds its own full agent definition.
//    There is no `prompt` field: the task goes in `instruction`, and
//    `system_prompt_override` replaces the persona prompt entirely.
await m.Pipelines.CreateAsync(new PipelineCreateRequest
{
    Name    = "mobile-review",
    Project = "Operations",
    Config  = new Dictionary<string, JsonElement>
    {
        ["steps"] = JsonSerializer.SerializeToElement(new object[]
        {
            new
            {
                kind  = "agent",
                agent = new
                {
                    name        = "mobile-operator",
                    role        = "Careful mobile operator",
                    instruction = "Read before acting. Never send, publish, or delete.",
                    model       = new { provider = "anthropic", name = "claude-sonnet-4-6" },
                    agent_tools = new[]
                    {
                        "phone_get_screen_tree",
                        "phone_current_app",
                        "phone_open_app",
                        "phone_click_text",
                        "phone_back",
                        "phone_wait",
                    },
                    human_approval_tools = Array.Empty<string>(),
                },
            },
        }),
        ["maxCostUsd"] = JsonSerializer.SerializeToElement(1.00),
        // Other config knobs 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  bool — force execution on the caller's own runner.
        //   inputs[]          declares the run_inputs schema accepted by RunAsync().
    },
});

// 3. Run it, hand the phone to the run, and watch status.
//    `executionTarget` below is used ONLY for the tier/capacity check — it does NOT
//    decide where the run executes (that's the stored config: local model providers,
//    force_local_runner). env_overrides' MEL_* / MELAYA_* keys are stripped server-side.
var run = await m.Pipelines.RunAsync("mobile-review", new PipelineRunRequest { Project = "Operations" });
await m.Phone.RegisterActiveRunAsync(run.RunId!);

m.Events.OnRunUpdate(run.RunId!, e => Console.WriteLine($"{e.EventType}: {e.Message}"));

var status = await m.Pipelines.RunStatusAsync("mobile-review", run.RunId!);
Console.WriteLine(status.Status);

Read → edit → save a pipeline config

GetAsync returns the full envelope { name, client, config, code, docs } — the editable pipeline config lives under config. Mutate it (e.g. via JsonNode) and pass it straight back to UpdateAsync:

using System.Text.Json;
using System.Text.Json.Nodes;

var envelope = await m.Pipelines.GetAsync("mobile-review", "Operations");
var config   = JsonNode.Parse(envelope.GetProperty("config").GetRawText())!;

// Swap the model on the first (and only) step's agent.
config["steps"]![0]!["agent"]!["model"] = JsonNode.Parse("""{"provider":"anthropic","name":"claude-opus-4-8"}""");

await m.Pipelines.UpdateAsync("mobile-review", new PipelineUpdateRequest
{
    Config  = JsonSerializer.SerializeToElement(config),
    Project = "Operations",
});

Run inputs and file uploads

// Upload a file first (single-use, valid 24h), then reference it by file_id.
var upload = await m.Pipelines.UploadRunFileAsync(
    "mobile-review", key: "screenshot", file: File.ReadAllBytes("shot.png"), filename: "shot.png");

var run = await m.Pipelines.RunAsync("mobile-review", new PipelineRunRequest
{
    Project    = "Operations",
    RunInputs  = new PipelineRunInputs
    {
        Brief  = "Review the attached screenshot and summarize any issues.",
        Values = new Dictionary<string, object>
        {
            ["screenshot"] = new { file_id = upload.FileId },
        },
    },
});

var inputs = await m.Pipelines.RunInputsAsync("mobile-review", run.RunId!);
var active = await m.Pipelines.RunActiveAsync("mobile-review", run.RunId!);

The platform catalogs currently expose 8,000+ scoped tools, 100+ specialized subagents, and 48 AI providers (m.Pipelines.ToolsAsync(), m.Pipelines.SubagentsAsync(), m.Agents.Models.ListModelsAsync(); live counts via m.Market.CatalogCountsAsync()).

GA API surface

All namespaces below are generally available. Flat accessors (m.Pipelines, …) and domain accessors (m.Agents.Pipelines, m.Platform.Projects, …) point to the same objects.

auth (m.Auth) + mfa (m.Mfa)

projects (m.Projects)

connectors (m.Connectors)

credentials (m.Credentials)

pipelines (m.Pipelines)

templates (m.Templates)

phone (m.Phone)

hitl (m.Hitl)

evals (m.Evals)

connector tools (m.ConnectorTools, also m.Agents.ConnectorTools)

The same discover/call surface the Melaya MCP server exposes, over plain REST — not to be confused with m.Connectors / m.Credentials, which store the credentials this module's tools use. Reads run immediately. Writes default to approval: "required": the call is staged as the same approval card the Assistant raises in the Melaya app and returns 202 (a success, not an error) with a requestId to poll; approval: "none" runs a write immediately and is still audit-logged. Tools that move money or trade are always refused, under both approval modes. No method here ever accepts or returns a credential value.

var found = await m.ConnectorTools.SearchAsync("unread email");

// Staged for approval in the Melaya app, then polled to completion.
var outcome = await m.ConnectorTools.CallAndWaitAsync(
    "gmail_send", new Dictionary<string, object?> { ["to"] = "a@b.c", ["subject"] = "Hi" });
Console.WriteLine(outcome.Status); // "done" | "rejected" | "expired"

// Skips the approval card; still audit-logged. Money-moving/trading tools are refused either way.
var sent = await m.ConnectorTools.CallAsync(
    "gmail_send", new Dictionary<string, object?> { ["to"] = "a@b.c" }, approval: "none");

triggers (m.Triggers, also m.Agents.Triggers)

Read, diagnose and dry-run the event triggers that start your pipelines. Creating, editing and deleting a trigger stay in the Agent Builder and the MCP server. No method returns a signing secret. TestAsync and PollTestAsync are dry runs: the action never executes.

var live = await m.Triggers.EventsAsync(verdicts: new[] { "rejected", "failed" }, limit: 50);
var test = await m.Triggers.TestAsync(triggerId, new { type = "refund.created" });
var dry  = await m.Triggers.PollTestAsync(pollTriggerId);
Console.WriteLine(dry.Ok == true ? $"{dry.Found} found, {dry.WouldPublish} new" : dry.Error);

events (m.Events)

Connects lazily on the first subscription — constructing MelayaClient opens no socket.

billing (m.Billing)

accounts (m.AccountManagement)

runner (m.Runner)

team (m.Team)

assistant (m.Assistant)

bugs (m.Bugs)

Quick start: trading (preview)

Trading namespaces are preview-only and not generally available. Do not use them with real funds.

using Melaya;

var mk = Environment.GetEnvironmentVariable("MK")!;
await using var m = new MelayaClient(new MelayaOptions { ApiKey = mk });

// Market data
var ticker = await m.Market.TickerAsync("binance", "BTC/USDT", "spot");
Console.WriteLine($"BTC last: {ticker.GetProperty("last")}");

// Launch a custom paper strategy
var created = await m.Strategies.CreateAsync(new
{
    name         = "my-rhai-bot",
    strategyType = "custom",
    exchange     = "binance",
    symbol       = "BTC/USDT",
    market       = "spot",
    dryRun       = true,
    @params      = new
    {
        language   = "rhai",
        definition = "fn evaluate() { emit_long(param(\"qty\")); }",
        qty        = 0.001,
    },
});
string sid = created.StrategyId!;
Console.WriteLine($"Strategy: {sid}");

// Sim: virtual balance
var balance = await m.Sim.BalanceAsync(sid);
Console.WriteLine($"Balance: {balance}");

// Backtest (completes in seconds)
var job = await m.Backtest.StartAsync(new
{
    strategyType = "custom",
    language     = "rhai",
    definition   = "fn evaluate() { emit_long(param(\"qty\")); }",
    exchange     = "binance",
    symbol       = "BTC/USDT",
    timeframe    = "1h",
    since_ms     = DateTimeOffset.UtcNow.AddDays(-30).ToUnixTimeMilliseconds(),
    until_ms     = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
    @params      = new { qty = 0.001 },
});
Console.WriteLine($"Backtest job: {job.JobId}");

// Clean up
await m.Strategies.StopAsync(sid);
await m.Strategies.DeleteAsync(sid);

Streaming (preview)

// Public ticker stream
await foreach (var frame in m.Stream.TickerAsync("binance", "BTC/USDT", "spot"))
{
    Console.WriteLine(frame);
    break; // take one frame then stop
}

// Private strategy events (mints a short-lived WS ticket)
await foreach (var frame in m.Stream.StrategiesAsync())
{
    Console.WriteLine(frame);
    break;
}

Trading method tables (preview)

market

account

sim (paper trading)

strategies

backtest

stream