The0.Sdk 0.4.0

the0 C#/.NET SDK

Optional SDK for building trading bots on the0 platform using C#/.NET 8.

Note: This SDK is optional. The the0 runtime automatically wraps your bot's output:

• Exit code 0 → {"status":"success","message":"Bot executed successfully"}
• Exit code non-zero → {"status":"error","message":"Bot execution failed"}
• If you output JSON with a "status" field, it's passed through as-is

Minimal Example (No SDK)

// No SDK needed - just run your code and exit normally
var botId = Environment.GetEnvironmentVariable("BOT_ID");
var configJson = Environment.GetEnvironmentVariable("BOT_CONFIG");

Console.Error.WriteLine($"Bot {botId} running...");

// Your trading logic here

// Exit normally - runtime outputs {"status":"success",...}

With SDK (Optional)

The SDK provides convenience methods for parsing config and outputting custom results.

Installation

Install from NuGet:

dotnet add package The0.Sdk

Or add to your .csproj:

<PackageReference Include="The0.Sdk" Version="0.4.0" />

Usage

using The0;

// Parse bot configuration
var (botId, config) = Input.Parse();

Console.Error.WriteLine($"Bot {botId} starting...");

// Access configuration values
var symbol = config?["symbol"]?.ToString() ?? "BTC/USDT";
var amount = config?["amount"]?.GetValue<decimal>() ?? 100m;

// Your trading logic here

// Optionally output custom result (otherwise runtime generates it)
Input.Success("Trade executed for " + symbol);

API Reference

Input.Parse()

Parse bot configuration from environment variables.

var (botId, config) = Input.Parse();
// botId: string - unique bot instance ID
// config: JsonNode? - configuration as JSON

Input.ParseAsDict()

Parse configuration as a Dictionary for easier access.

var (botId, config) = Input.ParseAsDict();
// config: Dictionary<string, JsonNode?>
if (config.TryGetValue("symbol", out var symbol))
{
    Console.Error.WriteLine($"Symbol: {symbol}");
}

Input.Success(message, data?)

Output a success result. data is optional and can be any JSON-serializable value.

Input.Success("Trade executed successfully");
// Output: {"status":"success","message":"Trade executed successfully"}

Input.Success("Trade executed", new { trade_id = "12345", filled = 0.5 });
// Output: {"status":"success","message":"Trade executed","data":{"trade_id":"12345","filled":0.5}}

Input.Error(message, data?)

Output an error result, print the message to stderr as an error log line, and exit with code 1. data is optional and goes in the result only.

Input.Error("Failed to connect to exchange");
// Output: {"status":"error","message":"Failed to connect to exchange"}
// Stderr: {"level":"error","message":"Failed to connect to exchange","timestamp":"..."}
// Process exits with code 1

Input.Error("Trade failed", new { code = "INSUFFICIENT_FUNDS", available = 100 });
// Output: {"status":"error","message":"Trade failed","data":{"code":"INSUFFICIENT_FUNDS","available":100}}

Input.Result(data)

Output a custom JSON result.

Input.Result(new {
    status = "success",
    trade_id = "12345",
    filled_amount = 0.5m
});

Input.Metric(type, data)

Emit a metric for the platform to collect.

Input.Metric("price", new { symbol = "BTC/USD", value = 45000.0 });
// Output to stdout: {"_metric":"price","symbol":"BTC/USD","value":45000,"timestamp":"2026-10-12T09:30:00.123Z"}

Metric and log lines carry a UTC ISO 8601 timestamp.

Input.Log(message, data?, level?)

Log a structured message to stderr.

// Simple log (defaults to info level)
Input.Log("Starting bot");

// Log with level
Input.Log("Connection lost", null, LogLevel.Warn);

// Log with structured data
Input.Log("Order placed", new { orderId = "12345", symbol = "BTC" });

// Log with data and level
Input.Log("Order failed", new { orderId = "12345" }, LogLevel.Error);

Query

A query entrypoint registers handlers and then calls Query.Run(), which answers one query when QUERY_PATH is set, serves HTTP on port 9476 for a realtime bot, and otherwise answers /info. /health and /info are built in.

Query.Handler("/signals", req =>
{
    // Params are JSON values. Get<T> and JsonParams hand them over typed.
    var limit = req.Get("limit", 10);
    var symbols = req.Get<List<string>>("symbols") ?? new List<string>();

    // Get(key) and Params hand them over as text: a string as itself,
    // any other value as its JSON text ("10", "true", "[\"AAPL\"]").
    var symbol = req.Get("symbol", "BTC/USD");

    if (limit > 100)
    {
        // A handler that throws answers {"status":"error","error":"..."}.
        throw new ArgumentException("limit must be at most 100");
    }
    return new { symbol, symbols, limit };
});

Query.Run();

In server mode, a request with no JSON object body takes its params from the URL query string, and every value is then a string. The accessors handle that and null params:

• Get<T> parses a string param as T, so req.Get("limit", 10) reads ?limit=50 as 50. It throws a JsonException when the value is not a T either way.
• Get<string> reads like Get(key): a non-string value as its JSON text.
• Get(key), Params and Get<string> treat a null param as absent, so the default applies.
• The other Get<T> calls read a null param as null, or as the default when T cannot hold null (req.Get("cursor", 0) gives 0). JsonParams keeps every null.

State is read-only during an ephemeral query: State.Set, State.Delete and State.Clear throw ReadOnlyStateError, the SDK's one read-only error type.

Environment Variables

The SDK reads from these environment variables (set automatically by the0 runtime):

• BOT_ID - Unique identifier for the bot instance
• BOT_CONFIG - JSON-encoded configuration object

Logging

Use Console.Error for logs (stdout is reserved for results):

Console.Error.WriteLine("DEBUG: Processing trade...");  // Logs to stderr
Console.WriteLine("...");  // Reserved for JSON result output

Publishing (Maintainers)

This package is published to NuGet.org.

export NUGET_API_KEY="your_key_here"
make publish

Get your API key from: https://www.nuget.org/account/apikeys

License

Apache-2.0