Place MetaTrader 5 orders from PHP — no MetaTrader installed

mkdir mt5-trade && cd mt5-trade
composer require guzzlehttp/guzzle:^7

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

<?php
// 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.
declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\TransferException;
use Psr\Http\Message\ResponseInterface;

const NEEDS_ATTENTION = ['invalid_credentials', 'trading_disabled', 'needs_2fa', 'needs_certificate'];
// Codes that mean "nothing was placed yet — ask again with the SAME key".
const RETRY_SAME_KEY = ['SEND_FAILED', 'IDEMPOTENCY_IN_FLIGHT', 'ACCOUNT_NOT_READY', 'NO_RUNTIME', 'RATE_LIMITED'];

final class ApiError extends RuntimeException
{
    public function __construct(
        public readonly int $status,
        public readonly string $errorCode,
        string $message,
        public readonly array $details = [],
    ) {
        parent::__construct("$status $errorCode: $message");
    }
}

function setting(string $name, ?string $default = null): string
{
    $value = getenv($name);
    if ($value === false || $value === '') {
        if ($default === null) {
            throw new RuntimeException("Set $name");
        }
        return $default;
    }
    return $value;
}

$http = new Client([
    'base_uri' => setting('FXAPIS_API', 'https://api.fxapis.com'),
    'headers' => ['Authorization' => 'Bearer ' . setting('FXAPIS_KEY')],
    'http_errors' => false, // we read every status ourselves
    'timeout' => 30,
]);

/** The error object of a failed response, or null if the body is not ours (a proxy page). */
function errorOf(ResponseInterface $response): ?array
{
    $body = json_decode((string) $response->getBody(), true);
    return is_array($body) && isset($body['error']['code']) ? $body['error'] : null;
}

function fail(ResponseInterface $response): never
{
    $error = errorOf($response) ?? ['code' => 'HTTP_ERROR', 'message' => $response->getReasonPhrase()];
    throw new ApiError($response->getStatusCode(), $error['code'], $error['message'], $error['details'] ?? []);
}

/** Sends a request and returns `data`, or throws ApiError. */
function api(Client $http, string $method, string $path, ?array $options = []): mixed
{
    $response = $http->request($method, $path, $options ?? []);
    if ($response->getStatusCode() >= 300) {
        fail($response);
    }
    return json_decode((string) $response->getBody(), true)['data'];
}

/** Stores the account at fxapis. It does not log in yet. */
function connectAccount(Client $http, string $login, string $server, string $password): array
{
    try {
        return api($http, 'POST', '/v1/accounts', ['json' => [
            'login' => $login,
            'server' => $server,
            'password' => $password,
            'mode' => 'warm_on_demand',
            'label' => 'php-guide',
        ]]);
    } catch (ApiError $e) {
        if ($e->errorCode !== 'ACCOUNT_EXISTS') {
            throw $e;
        }
        // Connected on an earlier run: find it instead of connecting it twice.
        foreach (api($http, 'GET', '/v1/accounts') as $account) {
            if ($account['login'] === $login && $account['server'] === $server) {
                return $account;
            }
        }
        throw $e;
    }
}

/** Starts the broker login, then polls until the account is ready to trade. */
function bringOnline(Client $http, string $accountId, int $timeout = 120): array
{
    api($http, 'POST', "/v1/accounts/$accountId/warm"); // 409 NEEDS_OPERATOR / NO_SECRET throws
    $deadline = time() + $timeout;
    while (time() < $deadline) {
        $status = api($http, 'GET', "/v1/accounts/$accountId/status");
        if ($status['state'] === 'ready') {
            return $status;
        }
        if (in_array($status['state'], NEEDS_ATTENTION, true)) {
            // Not retryable. Repeated failed logins are how brokers lock accounts.
            throw new RuntimeException("account needs attention: {$status['state']} ({$status['detail']})");
        }
        sleep(2);
    }
    throw new RuntimeException("account not ready after {$timeout}s");
}

/** After ORDER_UNRESOLVED: never resend. Poll the order until the broker's record settles it. */
function waitForOutcome(Client $http, string $orderId, int $timeout = 300): array
{
    $deadline = time() + $timeout;
    while (time() < $deadline) {
        $order = api($http, 'GET', "/v1/orders/$orderId");
        if ($order['state'] !== 'unknown') {
            return $order;
        }
        sleep(5);
    }
    throw new RuntimeException("order $orderId is still unknown. Do not resend it; check it again later.");
}

/** Places an order (or a close) exactly once, however many times the request is retried. */
function sendOrder(Client $http, string $path, array|object $body, int $attempts = 6): array
{
    $key = bin2hex(random_bytes(16)); // one key per order, reused on every retry
    for ($attempt = 0; $attempt < $attempts; $attempt++) {
        $backoff = min(2 ** $attempt, 10);
        try {
            $response = $http->request('POST', $path, [
                'json' => $body,
                'headers' => ['Idempotency-Key' => $key],
                'timeout' => 90,
            ]);
        } catch (TransferException) {
            sleep($backoff); // we never saw the answer; the same key makes asking again safe
            continue;
        }

        if ($response->getStatusCode() === 201) {
            return json_decode((string) $response->getBody(), true)['data'];
        }

        $error = errorOf($response);
        if ($error === null && $response->getStatusCode() >= 500) {
            sleep($backoff); // not our error body: a gateway hiccup
            continue;
        }
        if ($error === null) {
            fail($response);
        }

        if ($error['code'] === 'ORDER_UNRESOLVED') {
            return waitForOutcome($http, $error['details'][0]['orderId']);
        }
        if (in_array($error['code'], RETRY_SAME_KEY, true)) {
            $retryAfter = (int) $response->getHeaderLine('retry-after');
            sleep($retryAfter > 0 ? $retryAfter : $backoff);
            continue;
        }
        fail($response); // ORDER_REJECTED, INVALID_REQUEST, QUOTA_EXCEEDED, …
    }
    throw new RuntimeException("gave up after $attempts attempts; retrying later with key $key is still safe");
}

$login = setting('MT5_LOGIN');
$server = setting('MT5_SERVER');
$symbol = setting('MT5_SYMBOL', 'EURUSD');

$account = connectAccount($http, $login, $server, setting('MT5_PASSWORD'));
$id = $account['id'];
echo "account $id ({$account['state']})\n";

bringOnline($http, $id);
echo "online\n";

try {
    $order = sendOrder($http, "/v1/accounts/$id/orders/market", [
        'symbol' => $symbol,
        'side' => 'buy',
        'volume' => '0.01', // a string, never a float
    ]);
} catch (ApiError $e) {
    if ($e->errorCode === 'ORDER_REJECTED') {
        echo "rejected by the broker: {$e->getMessage()}\n";
        exit(1);
    }
    throw $e;
}
echo "order {$order['id']}: {$order['state']} at {$order['filledPrice']}\n";
if (!in_array($order['state'], ['filled', 'partially_filled'], true)) {
    exit(1);
}

// Positions refresh on their own about every 15 s; reconcile (optional) refreshes them now.
api($http, 'POST', "/v1/accounts/$id/reconcile");
foreach (api($http, 'GET', "/v1/accounts/$id/positions") as $p) {
    echo "  #{$p['brokerPositionId']} {$p['side']} {$p['volume']} {$p['symbol']} @ {$p['openPrice']}"
        . " profit {$p['profit']} (seen {$p['observedAt']})\n";
}

$close = sendOrder($http, "/v1/accounts/$id/positions/{$order['brokerPositionId']}/close", new stdClass());
echo "closed: {$close['state']} at {$close['filledPrice']}\n";

// Offline now rather than after the idle window. The stored password is kept.
api($http, 'POST', "/v1/accounts/$id/cool");

if (getenv('FXAPIS_DISCONNECT') === '1') {
    // Erases the stored password for good. Only when you are done with this account.
    $result = api($http, 'POST', "/v1/accounts/$id/disconnect");
    echo 'disconnected, credentials removed: ' . var_export($result['credentialsRemoved'], true) . "\n";
}

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