Class: Melaya::StrategiesAPI

Inherits:
Object
  • Object
show all
Defined in:
lib/melaya/strategies.rb

Overview

Strategies API — launch, control, and inspect trading strategies.

A strategy is a server-managed runner (the Trading Engine, or an Agentic Trading Crew) that trades a universe on a cadence with server-side SL/TP and safety rails. Launch in paper mode (dry_run: true) or live (dry_run: false, which requires a connected exchange key).

Maps to api.melaya.org/api/v1/strategies/* on the private plane.

Instance Method Summary collapse

Constructor Details

#initialize(http) ⇒ StrategiesAPI

Returns a new instance of StrategiesAPI.



13
14
15
 
# File 'lib/melaya/strategies.rb', line 13

def initialize(http)
  @http = http
end

Instance Method Details

#ai_opt_approve(strategy_id, body = {}) ⇒ Object

Approve and apply the optimizer’s proposed params to the running strategy.

Parameters:

  • body (Hash) (defaults to: {}) —

    optional extra params



141
142
143
 
# File 'lib/melaya/strategies.rb', line 141

def ai_opt_approve(strategy_id, body = {})
  @http.post("/api/v1/strategies/#{strategy_id}/ai-opt/approve", body)
end

#ai_opt_runs(strategy_id) ⇒ Object

Past optimization runs for a strategy.



151
152
153
 
# File 'lib/melaya/strategies.rb', line 151

def ai_opt_runs(strategy_id)
  @http.get("/api/v1/strategies/#{strategy_id}/ai-opt/runs")
end

#ai_opt_start(strategy_id, param_bounds:, objective: "sharpe", max_iterations: 3, require_approval: nil) ⇒ Object

Kick off an AI-driven parameter optimization. param_bounds maps each param name to a [min, max] array. objective defaults to “sharpe”; max_iterations is clamped to 1-20. Returns a hash including “runId”.

Parameters:

  • strategy_id (String)
  • param_bounds (Hash) —

    e.g. { “qty” => [0.001, 0.1] }

  • objective (String) (defaults to: "sharpe")
  • max_iterations (Integer) (defaults to: 3)
  • require_approval (Boolean, nil) (defaults to: nil) 


123
124
125
126
127
128
129
130
131
132
 
# File 'lib/melaya/strategies.rb', line 123

def ai_opt_start(strategy_id, param_bounds:, objective: "sharpe",
                 max_iterations: 3, require_approval: nil)
  body = {
    "paramBounds"     => param_bounds,
    "objective"       => objective,
    "maxIterations"   => max_iterations,
  }
  body["requireApproval"] = require_approval unless require_approval.nil?
  @http.post("/api/v1/strategies/#{strategy_id}/ai-opt/start", body)
end

#ai_opt_status(strategy_id) ⇒ Object

Current optimization status for a strategy.



135
136
137
 
# File 'lib/melaya/strategies.rb', line 135

def ai_opt_status(strategy_id)
  @http.get("/api/v1/strategies/#{strategy_id}/ai-opt/status")
end

#ai_opt_stop(strategy_id) ⇒ Object

Stop an in-progress optimization.



146
147
148
 
# File 'lib/melaya/strategies.rb', line 146

def ai_opt_stop(strategy_id)
  @http.post("/api/v1/strategies/#{strategy_id}/ai-opt/stop")
end

#create(name:, strategy_type:, exchange:, market: nil, symbol: nil, api_key_id: nil, params: nil, runtime_mode: nil, dry_run: true, key_bindings: nil) ⇒ Object

Launch a strategy. Pass dry_run: true for paper; live needs api_key_id. Returns the full response hash (includes “strategyId”).

Parameters:

  • name (String)
  • strategy_type (String) —

    e.g. “custom”

  • exchange (String)
  • market (String, nil) (defaults to: nil)
  • symbol (String, nil) (defaults to: nil)
  • api_key_id (String, nil) (defaults to: nil)
  • params (Hash, nil) (defaults to: nil)
  • runtime_mode (String, nil) (defaults to: nil)
  • dry_run (Boolean) (defaults to: true)
  • key_bindings (Hash, nil) (defaults to: nil) 


41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/melaya/strategies.rb', line 41

def create(name:, strategy_type:, exchange:, market: nil, symbol: nil,
           api_key_id: nil, params: nil, runtime_mode: nil, dry_run: true,
           key_bindings: nil)
  body = {
    "name"         => name,
    "strategyType" => strategy_type,
    "exchange"     => exchange,
    "market"       => market,
    "symbol"       => symbol,
    "apiKeyId"     => api_key_id,
    "params"       => params,
    "runtimeMode"  => runtime_mode,
    "dryRun"       => dry_run,
    "keyBindings"  => key_bindings,
  }.reject { |_, v| v.nil? }
  @http.post("/api/v1/strategies", body)
end

#delete(strategy_id) ⇒ Object

Soft-delete a strategy.



75
76
77
 
# File 'lib/melaya/strategies.rb', line 75

def delete(strategy_id)
  @http.delete("/api/v1/strategies/#{strategy_id}")
end

#executions(strategy_id) ⇒ Object

Execution (order) rows for a strategy.



97
98
99
 
# File 'lib/melaya/strategies.rb', line 97

def executions(strategy_id)
  @http.get("/api/v1/strategies/#{strategy_id}/executions")["rows"]
end

#get(strategy_id) ⇒ Object

A single strategy by id.

Parameters:

  • strategy_id (String) 


24
25
26
 
# File 'lib/melaya/strategies.rb', line 24

def get(strategy_id)
  @http.get("/api/v1/strategies/#{strategy_id}")["strategy"]
end

#list ⇒ Object

Every strategy you own (running, paused, paper, and live).



18
19
20
 
# File 'lib/melaya/strategies.rb', line 18

def list
  @http.get("/api/v1/strategies/list")["strategies"]
end

#logs(strategy_id) ⇒ Object

Log rows for a strategy (cycle markers, persona messages, errors).



107
108
109
 
# File 'lib/melaya/strategies.rb', line 107

def logs(strategy_id)
  @http.get("/api/v1/strategies/#{strategy_id}/logs")["rows"]
end

#pause(strategy_id) ⇒ Object

Pause a running strategy (stops entering new cycles until resumed).



60
61
62
 
# File 'lib/melaya/strategies.rb', line 60

def pause(strategy_id)
  @http.post("/api/v1/strategies/#{strategy_id}/pause")
end

#performance(strategy_id) ⇒ Object

Performance series for a strategy (equity, PnL over time).



92
93
94
 
# File 'lib/melaya/strategies.rb', line 92

def performance(strategy_id)
  @http.get("/api/v1/strategies/#{strategy_id}/performance")["rows"]
end

#resume(strategy_id) ⇒ Object

Resume a paused strategy.



65
66
67
 
# File 'lib/melaya/strategies.rb', line 65

def resume(strategy_id)
  @http.post("/api/v1/strategies/#{strategy_id}/resume")
end

#status(strategy_id) ⇒ Object

Live runtime status of a strategy’s runner (container health, tick count).



87
88
89
 
# File 'lib/melaya/strategies.rb', line 87

def status(strategy_id)
  @http.get("/api/v1/strategies/#{strategy_id}/status")
end

#stop(strategy_id) ⇒ Object

Stop a strategy and tear down its runner. Cancels any in-flight approvals.



70
71
72
 
# File 'lib/melaya/strategies.rb', line 70

def stop(strategy_id)
  @http.post("/api/v1/strategies/#{strategy_id}/stop")
end

#trades(strategy_id) ⇒ Object

Trade (fill) rows for a strategy.



102
103
104
 
# File 'lib/melaya/strategies.rb', line 102

def trades(strategy_id)
  @http.get("/api/v1/strategies/#{strategy_id}/trades")["rows"]
end

#update_params(strategy_id, params) ⇒ Object

Update a running strategy’s params (e.g. universe, cadence, risk caps).

Parameters:

  • strategy_id (String)
  • params (Hash) 


82
83
84
 
# File 'lib/melaya/strategies.rb', line 82

def update_params(strategy_id, params)
  @http.post("/api/v1/strategies/#{strategy_id}/update-params", params)
end