Place MetaTrader 5 orders from Ruby — no MetaTrader installed

export FXAPIS_KEY="fx_test_…"          # your API key
export MT5_LOGIN="26177561"
export MT5_SERVER="VantageMarkets-Demo"
export MT5_PASSWORD="…"                # the trading password
export MT5_SYMBOL="EURUSD"             # as your broker names it

# Connect an MT5 account through fxapis, open a small trade, and close it.
# Run it against a broker DEMO account. Every fxapis key reaches a real broker.
require "json"
require "net/http"
require "securerandom"
require "uri"

API = URI(ENV.fetch("FXAPIS_API", "https://api.fxapis.com"))
KEY = ENV.fetch("FXAPIS_KEY")
NEEDS_ATTENTION = %w[invalid_credentials trading_disabled needs_2fa needs_certificate].freeze
# Codes that mean "nothing was placed yet — ask again with the SAME key".
RETRY_SAME_KEY = %w[SEND_FAILED IDEMPOTENCY_IN_FLIGHT ACCOUNT_NOT_READY NO_RUNTIME RATE_LIMITED].freeze

# Every failure the API reports. Match on code; the message is for people.
class ApiError < StandardError
  attr_reader :status, :code, :details

  def initialize(status, code, message, details = nil)
    super("#{status} #{code}: #{message}")
    @status = status
    @code = code
    @details = details || []
  end
end

# One connection, kept alive for every call. 90 s reads, because an order waits for the broker.
HTTP = Net::HTTP.new(API.host, API.port).tap do |http|
  http.use_ssl = API.scheme == "https"
  http.open_timeout = 10
  http.read_timeout = 90
  http.start
end

def send_request(method, path, body = nil, headers = {})
  request = Net::HTTPGenericRequest.new(method, !body.nil?, true, path)
  request["Authorization"] = "Bearer #{KEY}"
  headers.each { |name, value| request[name] = value }
  unless body.nil?
    request["Content-Type"] = "application/json" # only with a body
    request.body = JSON.generate(body)
  end
  HTTP.request(request)
end

# The error object of a failed response, or nil if the body is not ours (a proxy page).
def error_of(response)
  error = JSON.parse(response.body.to_s)["error"]
  error.is_a?(Hash) && error["code"] ? error : nil
rescue JSON::ParserError
  nil
end

def fail_with(response)
  error = error_of(response) || { "code" => "HTTP_ERROR", "message" => response.message }
  raise ApiError.new(response.code.to_i, error["code"], error["message"], error["details"])
end

# Sends a request and returns `data`, or raises ApiError.
def call(method, path, body = nil)
  response = send_request(method, path, body)
  fail_with(response) unless response.code.to_i < 300
  JSON.parse(response.body)["data"]
end

# Stores the account at fxapis. It does not log in yet.
def connect_account(login, server, password)
  call("POST", "/v1/accounts", {
    login: login, server: server, password: password,
    mode: "warm_on_demand", label: "ruby-guide"
  })
rescue ApiError => e
  raise unless e.code == "ACCOUNT_EXISTS"
  # Connected on an earlier run: find it instead of connecting it twice.
  existing = call("GET", "/v1/accounts").find { |a| a["login"] == login && a["server"] == server }
  existing or raise
end

# Starts the broker login, then polls until the account is ready to trade.
def bring_online(account_id, timeout: 120)
  call("POST", "/v1/accounts/#{account_id}/warm") # 409 NEEDS_OPERATOR / NO_SECRET raises
  deadline = Time.now + timeout
  while Time.now < deadline
    status = call("GET", "/v1/accounts/#{account_id}/status")
    return status if status["state"] == "ready"
    if NEEDS_ATTENTION.include?(status["state"])
      # Not retryable. Repeated failed logins are how brokers lock accounts.
      raise "account needs attention: #{status['state']} (#{status['detail']})"
    end
    sleep 2
  end
  raise "account not ready after #{timeout}s"
end

# After ORDER_UNRESOLVED: never resend. Poll the order until the broker's record settles it.
def wait_for_outcome(order_id, timeout: 300)
  deadline = Time.now + timeout
  while Time.now < deadline
    order = call("GET", "/v1/orders/#{order_id}")
    return order unless order["state"] == "unknown"
    sleep 5
  end
  raise "order #{order_id} is still unknown. Do not resend it; check it again later."
end

# Places an order (or a close) exactly once, however many times the request is retried.
def send_order(path, body, attempts: 6)
  key = SecureRandom.uuid # one key per order, reused on every retry
  attempts.times do |attempt|
    backoff = [2**attempt, 10].min
    begin
      response = send_request("POST", path, body, "Idempotency-Key" => key)
    rescue Net::ReadTimeout, Net::OpenTimeout, IOError, SystemCallError
      HTTP.finish if HTTP.started?
      HTTP.start
      sleep backoff # we never saw the answer; the same key makes asking again safe
      next
    end

    return JSON.parse(response.body)["data"] if response.code == "201"

    error = error_of(response)
    if error.nil?
      fail_with(response) if response.code.to_i < 500
      sleep backoff # not our error body: a gateway hiccup
      next
    end

    return wait_for_outcome(error["details"][0]["orderId"]) if error["code"] == "ORDER_UNRESOLVED"

    if RETRY_SAME_KEY.include?(error["code"])
      retry_after = response["retry-after"].to_i
      sleep(retry_after.positive? ? retry_after : backoff)
      next
    end
    fail_with(response) # ORDER_REJECTED, INVALID_REQUEST, QUOTA_EXCEEDED, …
  end
  raise "gave up after #{attempts} attempts; retrying later with key #{key} is still safe"
end

login = ENV.fetch("MT5_LOGIN")
server = ENV.fetch("MT5_SERVER")
symbol = ENV.fetch("MT5_SYMBOL", "EURUSD")

account = connect_account(login, server, ENV.fetch("MT5_PASSWORD"))
id = account["id"]
puts "account #{id} (#{account['state']})"

bring_online(id)
puts "online"

begin
  order = send_order("/v1/accounts/#{id}/orders/market",
                     { symbol: symbol, side: "buy", volume: "0.01" }) # a string, never a Float
rescue ApiError => e
  raise unless e.code == "ORDER_REJECTED"
  puts "rejected by the broker: #{e.message}"
  exit 1
end
puts "order #{order['id']}: #{order['state']} at #{order['filledPrice']}"
exit 1 unless %w[filled partially_filled].include?(order["state"])

# Positions refresh on their own about every 15 s; reconcile (optional) refreshes them now.
call("POST", "/v1/accounts/#{id}/reconcile")
call("GET", "/v1/accounts/#{id}/positions").each do |p|
  puts "  ##{p['brokerPositionId']} #{p['side']} #{p['volume']} #{p['symbol']} @ #{p['openPrice']} " \
       "profit #{p['profit']} (seen #{p['observedAt']})"
end

close = send_order("/v1/accounts/#{id}/positions/#{order['brokerPositionId']}/close", {})
puts "closed: #{close['state']} at #{close['filledPrice']}"

# Offline now rather than after the idle window. The stored password is kept.
call("POST", "/v1/accounts/#{id}/cool")

if ENV["FXAPIS_DISCONNECT"] == "1"
  # Erases the stored password for good. Only when you are done with this account.
  result = call("POST", "/v1/accounts/#{id}/disconnect")
  puts "disconnected, credentials removed: #{result['credentialsRemoved']}"
end

account 0d7c1f5e-4b6a-4c1e-9f0a-2d9e8c7b6a51 (created)
online
order b1c7…9e2a: filled at 1.13426
  #2109584418 buy 0.01 EURUSD @ 1.13426 profit -0.07 (seen 2026-09-30T10:14:03.512Z)
closed: filled at 1.13419